coastdigitalgroup/coastai-skills

Dark Theme Design System

Zweck

Das Skill „Dark Theme Design System“ bietet eine Methode, um hell gestaltete Web-Oberflächen in dunkle Gegenstücke zu übersetzen. Die Gestaltung eines dunklen Modus ist nicht einfach eine Frage der Farbinvertierung. Ein solcher Ansatz bricht physikalische Lichtmetaphern, verursacht schwere visuelle Ermüdung und erzeugt unleserliche, stark blendende Oberflächen.

Dieses System legt die visuellen und räumlichen Regeln für das Low-Light-Design fest:

• Elevationsumkehr: Darstellung von Tiefe im dunklen Modus durch Aufhellen erhöhter Oberflächenhintergründe anstelle von dunklen Schatten.
• Farbentsättigung: Anpassung lebendiger Marken- und semantischer Akzentfarben auf kontrastarme Werte, um visuelles „Vibrieren“ und Augenbelastung zu vermeiden.
• Kontrast und Halation-Prävention: Vermeidung von reinem Weiß-auf-Schwarz-Kombinationen, die extreme Glüheffekte (Halation) bei astigmatischen oder legasthenischen Lesern verursachen; stattdessen Verwendung von gebrochenem Weiß und Schwarz.
• Typografische Gewichtskalibrierung: Ausgleich des „Irradiation“-Effekts (optische Täuschung, bei der heller Text auf dunklem Hintergrund dicker und fetter erscheint als dunkler Text auf hellem Hintergrund).
• Mediendimmung: Anpassung von Bildern, Videos und Vektordiagrammen, damit sie den Benutzer bei schlechten Lichtverhältnissen nicht visuell „blenden“.

---

Anwendungsfälle

• Entwicklung dualer UI-Kits: Aufbau der Architektur semantischer Design-Tokens für ein System, das sowohl helle als auch dunkle Modi nativ unterstützt.
• Überarbeitung von SaaS-Dashboards und Leseumgebungen: Erstellung ermüdungsarmer Oberflächen, die für langes Betrachten, Entwickler-Workflows oder die abendliche Nutzung optimiert sind.
• Audit von unzugänglichen dunklen Themen: Identifizierung und Behebung von Kontrastproblemen, vibrierenden Akzenten, unleserlichen Textgewichten und blendenden Medien-Assets.
• Erstellung von Multi-Theme-Übergabespezifikationen: Generierung sauberer, entwicklerfreundlicher Spezifikationen, die genau zeigen, wie sich Elemente über die Themen hinweg verhalten.

---

Wann NICHT zu verwenden

• Standardmäßig dunkle (filmische) Umgebungen: Wenn eine Anwendung ausschließlich dunkel ist (z.B. Spotify, Netflix oder Game-Streaming-Plattformen) und niemals ein helles Thema unterstützen wird. Ein duales Designsystem ist in diesem Fall unnötiger Aufwand.
• Hochausdrucksstarke/künstlerische Mikro-Kampagnen: Eigenständige Landingpages, bei denen visuelle Störung, extrem gesättigte Paletten oder künstlerisches Branding den Komfort bei langer Betrachtung oder strenge Zugänglichkeitsregeln übertrumpfen.
• Streng statische Legacy-Frameworks: Anwendungen, deren Frontend-Architekturen keine dynamischen Stylesheets laden können oder keine CSS-Variablen unterstützen, was eine systematische Themenanpassung verhindert.

---

Eingaben

1. Helles Modus Kernpalette und Markenstile: Die vorhandenen primären Markenfarben, Sekundärfarben, Typografieskalen und fließende Abstandstoken.
2. Komponenteninventar und Tiefenhierarchie: Eine umfassende Liste der Seitenlayouts und UI-Ebenen (Hintergründe, Sidebars, Karten, Modale, Dropdowns).
3. Kontext der Lichtumgebung: Die typischen physischen Gegebenheiten des Zielbenutzers (z.B. abendliches Lesen im Bett vs. hell erleuchtete Industrieumgebungen).
4. Zugänglichkeitsziel: Standard WCAG 2.2 AA (Mindestanforderung) oder AAA (verbessert), einschließlich Überlegungen zu Astigmatismus und Farbenblindheit.

---

Ausgaben

1. Einheitliche semantische Token-Zuordnung: Eine systematische Spezifikation, die Hellmodus-Werte direkt mit ihren entsprechenden Dunkelmodus-Äquivalenten verknüpft.
2. Elevationsbasierte Oberflächenskala: Eine 5- bis 6-stufige Skala, die definiert, wie Hintergrundwerte von Oberflächen aufgehellt werden, je höher sie auf der Z-Achse schweben.
3. Entsättigte Akzentpalette: Ein kalibrierter Satz von Primär-, Sekundär- und semantischen Statusfarben, die für dunkle Hintergründe entsättigt wurden.
4. Korrekturen für typografische Stylesheets: Spezifische Regeln für Schriftgewicht, Buchstabenabstand und Textfarbanpassungen, um dem Irradiationseffekt entgegenzuwirken.
5. Mediendimmungs-Spezifikationen: CSS- und HTML-Techniken zur Reduzierung von Bildkontrast/Helligkeit und Anpassung von Vektorgrafiken.

---

Workflow

1. Grundlage schaffen: Gebrochenes Schwarz und gebrochenes Weiß wählen

Vermeiden Sie absolutes #000000 (reines Schwarz) für Hintergründe und absolutes #FFFFFF (reines Weiß) für Fließtext.

• Der Basis-Hintergrund: Wählen Sie ein dunkles, getöntes Neutral (z.B. tiefes Schiefergrau, Anthrazit oder dunkles Marinegrau zwischen #121212 und #1A1A1A). Dies reduziert Augenbelastung, verhindert Bildschirmflackern und behält eine gewisse visuelle Tiefe.
• Die Textbasis: Wählen Sie ein gebrochenes Weiß oder hellgrau (z.B. #E2E8F0 oder #EAEAEA mit einer Deckkraft von 85% bis 90%). Dies gewährleistet angenehmen Kontrast, ohne Halation (Lichtstreuung im Auge des Lesers) zu verursachen.

2. Tiefe durch Elevationsaufhellung übersetzen

In einem hellen Thema zeigen wir an, dass ein Element erhöht ist, indem wir einen dunkleren Schatten werfen. In einem dunklen Thema ist ein dunkler Schatten auf einem dunklen Hintergrund unsichtbar.

• Das Aufhellungsprinzip: Je höher ein Element auf der Z-Achse steigt, desto näher kommt es der virtuellen Umgebungslichtquelle und wird heller, nicht dunkler.
• Erstellen einer Elevations-Oberflächen-Skala:
  • Stufe 0 (Canvas-Basis): Dunkelste Farbe (z.B. #121212).
  • Stufe 1 (Karte/Listenelement): Etwas heller (z.B. #1D1D1D).
  • Stufe 2 (Sticky Header / Schwebende Aktion): Noch heller (z.B. #242424).
  • Stufe 3 (Modal/Dialogfeld): Hellste Oberfläche (z.B. #2C2C2C).
• Unterstützung durch weiche Schatten: Verwenden Sie sehr dezente, dunkelgraue oder durchscheinende schwarze Schatten auf erhöhten Ebenen (z.B. rgba(0, 0, 0, 0.5)), um eine Trennung auf größeren Oberflächen zu schaffen, die über Stufe 1-Elementen liegen.

3. Akzentfarben kalibrieren und entsättigen

Hochgesättigte Farben, die auf einer weißen Leinwand lebendig wirken, „vibrieren“ auf einer dunklen Leinwand, verursachen schwere visuelle Ermüdung und bestehen Kontrasttests nicht.

• Markenakzente entsättigen: Verschieben Sie Markenfarben zu helleren, weicheren und pastellartigeren Äquivalenten. (z.B. sollte ein lebendiges Primärblau #0055FF auf hellem Hintergrund auf ein entsättigtes Blau #66A3FF oder #80B3FF auf dunklem Hintergrund abgebildet werden).
• Kontrastsichere Akzente beibehalten: Überprüfen Sie, ob entsättigte Akzentfarben auf dunklen Oberflächen den WCAG 2.2 AA-Standards entsprechen (Mindestens 4,5:1 für Text, 3:1 für interaktive Zustände).
• Große gesättigte Blöcke vermeiden: Rendern Sie ganze Buttons oder Banner nicht in vollgesättigten Farben, sondern verwenden Sie diese sparsam – z.B. für Textlinks, Rahmen oder dezente Indikatoren.

4. Typografie für optische Irradiation anpassen

Heller Text auf dunklem Hintergrund leidet unter Irradiation – der weiße Text scheint in die umgebende Dunkelheit „auszubluten“, wodurch Buchstaben fetter, dicker und enger beieinander erscheinen als ihre hell-auf-dunkel-Äquivalente.

• Gewichtskalibrierung: Reduzieren Sie das Schriftgewicht von fetten Überschriften im hellen Modus um eine Stufe (z.B. von 700 (Fett) auf 600 (Halbfett) oder sogar 500 (Medium) im Dunkelmodus).
• Buchstabenabstand-Kalibrierung: Erhöhen Sie den Buchstabenabstand (Tracking) für dunklen Fließtext leicht (z.B. letter-spacing: 0.02em; oder 0.015em;), um zu verhindern, dass einzelne Buchstaben ineinander übergehen.
• Sekundäre/tertiäre Hierarchie: Steuern Sie die Hierarchie durch Anpassen der Textfarbdeckkraft, nicht nur durch die Größe. Verwenden Sie opacity: 0.87 für hochprioritären Fließtext, opacity: 0.60 für sekundäre Hilfstexte und opacity: 0.38 für deaktivierte Indikatoren.

5. Medien und umfangreiche Inhalte anpassen

Unveränderte Fotos, Diagramme und Grafiken können ein ansonsten perfektes Dark-Mode-Erlebnis ruinieren, indem sie den Benutzer mit hellen, kontrastreichen Weißtönen blenden.

• Fotodimmung: Wenden Sie eine subtile Reduzierung von Helligkeit und Kontrast auf Fotos an, um sie in die Low-Light-Atmosphäre einzufügen.

  [data-theme="dark"] img:not(.avatar) {
    filter: brightness(0.85) contrast(0.95);
  }
  

• Vektor-Assets & Illustrationen: Tauschen Sie helle Hintergrundfarben in SVGs aus oder verwenden Sie SVG-Filter, um bestimmte Pfade zu invertieren. Verwenden Sie für illustrative Grafiken <picture> mit Media Queries, um angepasste dunkle Design-Assets zu laden.
• Datenvisualisierungen: Definieren Sie Diagrammfarbreihen neu, um entsättigte Linien und halbtransparente Flächenfüllungen zu verwenden, die ohne übermäßige Leuchtkraft lesbar bleiben.

---

Entscheidungsregeln

Die Elevationshelligkeitsregel

Konsultieren Sie bei der Festlegung des Hintergrunds eines visuellen Containers die Elevationsstufe. Machen Sie ein erhöhtes Modal oder Dropdown niemals dunkler als den Seitenhintergrund darunter.

Elevationsstufe	Hellmodus-Hintergrund	Dunkelmodus-Hintergrund	Implizierter Elevationshinweis
Stufe 0 (Canvas)	#FFFFFF (Weiß) oder #F8F9FA	#121212 (Gebrochenes Schwarz)	Bodenebene / Basis
Stufe 1 (Karte/Abschnitt)	#FFFFFF (Weiß) mit Rand	#1E1E1E (Oberfläche 1)	Schweben 1-2dp
Stufe 2 (Header/Sticky)	#FFFFFF oder dezenter transluzenter Farbton	#252525 (Oberfläche 2)	Schweben 4-8dp
Stufe 3 (Modal/Dialog)	#FFFFFF mit starkem Schatten	#2D2D2D (Oberfläche 3)	Schweben 12-24dp

Die Sättigungsobergrenze

• Akzente, die als Hintergründe für interaktive Zustände verwendet werden (z.B. ein sekundärer Chip-Container), sollten im Dunkelmodus eine Sättigung von 10% bis 15% aufweisen.
• Akzente, die als Vordergrundtext oder Symbole verwendet werden, sollten eine Sättigung von 40% bis 60% aufweisen, um sicherzustellen, dass sie hervorstechen, ohne gegen die dunkle Oberfläche zu vibrieren.

Der Kontrastpuffer

Da Bildschirmblendung und minderwertige Bildschirme die Sichtbarkeit im Dunkelmodus stärker beeinträchtigen als im Hellmodus, streben Sie für dunklen Fließtext immer ein Kontrastverhältnis von 5.0:1 an (über dem WCAG-Minimum von 4.5:1), um als Puffer für schlechte physische Umgebungen zu dienen.

---

Einschränkungen

• Barrierefreiheit (WCAG AA): Textelemente müssen mindestens 4.5:1 Kontrast erreichen (3:1 für großen Text). UI-Ränder, Fokusringe und Funktionssymbole müssen mindestens 3:1 Kontrast erreichen. Fokusindikatoren müssen gut sichtbar bleiben und dürfen nicht durch dunkle Hintergrundglüheffekte überstrahlt werden (WCAG 2.2 SC 2.4.11).
• Reaktive Blendungsanpassung: Textfarben müssen gegenüber hoher Umgebungsblendung (wie bei Mobilbildschirmen im Freien) widerstandsfähig sein, d.h. absolute Mindestkontraststufen müssen vermieden werden.
• Keine reine Farbhierarchie: Verlassen Sie sich nicht ausschließlich auf den Farbton einer entsättigten Farbe, um einen Status zu vermitteln (z.B. Warnung vs. Fehler in Diagrammen). Integrieren Sie deutliche Muster, Textbeschriftungen oder Symbolgrafiken.

---

Häufige Fehlermuster

• Der „Buchstäbliche Invertierer“: Anwenden eines automatischen Farbinversionsfilters auf ein helles Thema. Dies verwandelt erhöhte Hellmodus-Elemente mit dunklen Schatten in abgesenkte Dunkelmodus-Elemente mit leuchtenden weißen Ringen und zerstört alle natürlichen Beleuchtungsmodelle.
• Der „Vibrierende Neon“-Albtraum: Platzieren vollgesättigter Markenfarben (z.B. #00FF00 oder #FF00FF) direkt auf einem rein schwarzen Hintergrund. Dies löst visuelle Ermüdung aus und macht das Lesen des Texts für mehr als ein paar Sekunden nahezu unmöglich.
• Das OLED-Extrem (Reines Schwarz-Glühen): Verwendung von #FFFFFF-Text direkt auf #000000-Hintergründen. Dies erzeugt auf vielen Bildschirmen einen starken Lichthof-/Glüheffekt, der die Lesegeschwindigkeit reduziert und Augenbelastung verursacht.
• Der verschwindende Fokusring: Entwerfen eines schönen dunklen Modus, aber Beibehalten der Standard-Browser-Fokusindikatoren, die oft dunkelblau sind und auf dunklen Schieferhintergründen völlig unsichtbar werden.
• Die blendende Illustration: Erstellen einer nahtlosen dunklen Benutzeroberfläche, aber Belassen von kontrastreichen, reinweißen Hintergründen in SVG-Diagrammen, Logos oder illustrativen Symbolen.

---

Validierungskriterien

• Basiswerte: Kein absolutes reines Schwarz (#000) wird für den Haupt-Canvas-Hintergrund verwendet, und kein absolutes reines Weiß (#FFF) wird für Fließtext verwendet.
• Elevationsmodell: Oberflächen werden progressiv heller (höherer Helligkeitswert), je höher sie auf der Z-Achse angehoben werden.
• Kontrastprüfung: Jede Textfarbe, einschließlich abgeschwächter Hilfstexte, erreicht oder übertrifft das WCAG 2.2 AA-Kontrastverhältnis (4.5:1 normal, 3:1 groß).
• Nicht vibrierende Akzente: Akzent- und Statusfarben werden auf einen Bereich zwischen 10% und 60% Sättigung entsättigt, je nach Anwendung, um visuelles Vibrieren zu vermeiden.
• Fokussichtbarkeit: Interaktive Elemente haben kontrastreiche, deutliche Fokusindikatoren, die auf dunklen Oberflächen klar sichtbar sind.
• Typografische Kalibrierung: Fetter Text wird angepasst (um eine Gewichtsstufe reduziert oder im Tracking erweitert), um Irradiation auszugleichen.
• Medienfilter: Ein reaktiver Mechanismus (CSS-Filter oder Austausch von dunklen Assets) wird spezifiziert, um Helligkeit und Kontrast von umfangreichen Medien- und Vektor-Assets zu reduzieren.