Semantische vs. reine Farben
Ein reiner Farb-Token benennt die Farbe selbst: --blue-500, --gray-900. Ein semantischer Token benennt die Aufgabe, die die Farbe erfüllt: --primary, --background, --muted-foreground. Komponenten können so die konkreten Farbtöne der Marke ignorieren. Ein Button, der mit bg-primary text-primary-foreground gestylt ist, funktioniert mit Salbeigrün, Hot Pink oder einem Dark-Theme, da die Rolle fix bleibt, während sich ihr Wert ändert.
Dies ist das Modell, das shadcn/ui popularisiert hat und auf dem das Theming von Tailwind aufbaut. Mit semantischen Tokens kann die Neugestaltung eines App-Themes auf einen einzigen :root-Block beschränkt werden. Hardcodierte Klassen wie bg-gray-900 und text-white machen dieselbe Änderung zu einer codebase-weiten Suche.
Die Foreground-Kopplungsregel
Die meisten Basis-Rollen verfügen über eine gekoppelte -foreground-Rolle für Text oder Icons auf dieser Oberfläche: --primary / --primary-foreground, --card / --card-foreground, --muted / --muted-foreground. Verwenden Sie --primary-foreground auf --primary, anstatt darauf zu hoffen, dass der Standard-Foreground genügend Kontrast bietet. Jedes Paar muss dennoch in beiden Modi geprüft werden.
Die 28 Rollen, die ein vollständiges System benötigt
Eine minimale Drei-Farben-Palette lässt 25 Entscheidungen offen: Hover-Zustände, gedämpfter Text, Rahmen, Fokus-Ringe, Chart-Serien, Dark-Mode. Ein vollständiges System benennt all diese. Identity Forge Kits definieren diese 28 Rollen, gruppiert nach ihrer Funktion, für Light- und Dark-Mode:
- Oberflächen:
background/foreground,card/card-foreground,popover/popover-foreground. Die Seite, hervorgehobene Panels und schwebende Ebenen, jeweils mit ihrer eigenen lesbaren Textfarbe. - Brand & Betonung:
primary/primary-foreground,secondary/secondary-foreground,accent/accent-foreground. Die Hauptaktion, die unterstützende Aktion und das Highlight. - Dezent & Neutral:
muted/muted-foreground. Unauffällige Hintergründe und sekundärer Text. - Status:
destructive/destructive-foreground,success/success-foreground,warning/warning-foreground. Fehler, Bestätigungen und Warnungen. - Formular & Fokus:
border,input,ring. Trennlinien und Umrandungen, Formularfeld-Oberflächen und der Fokus-Indikator. - Daten:
chart-1,chart-2,chart-3,chart-4,chart-5. Fünf markenspezifische Serienfarben, damit Charts nicht auf eine generische Standardpalette zurückgreifen.
Warum fünf Chart-Farben wichtig sind
Bei der Datenvisualisierung werden unvollständig spezifizierte Systeme am deutlichsten sichtbar: ein Dashboard mit drei Markenfarben und einem zufälligen Regenbogen für sein Balkendiagramm. Die Vorab-Definition von chart-1…5 hält Grafiken in derselben visuellen Sprache wie den Rest der App.
Die Rollen in einem echten Kit sehen
Unten sehen Sie das kostenlose ambient-sage Kit, das vollständig aus diesen Tokens gerendert wurde. Die Farbmuster-Zeile zeigt --primary, --secondary, --accent und die fünf Chart-Rollen; der Button verwendet --primary mit --primary-foreground; die Oberflächen nutzen --background, --card und --muted. Nichts hier ist eine hardcodierte Farbe:
Ambient Sage
Live renderRendered from the kit's actual tokens, fonts, and treatments
Typography
Plus Jakarta Sans
Color system
28 semantic roles, light + dark
Agent outputs
DESIGN.md, CSS, Tailwind, shadcn
Ein vollständiges Token-Set erhalten
Sie können alle 28 Rollen manuell definieren, aber es ist mühsam, Light- und Dark-Mode ausgewogen und barrierefrei zu halten. Jedes Identity Forge Kit liefert diese in beiden Modi vollständig aus, exportierbar als CSS-Variablen, Tailwind v3/v4 @theme, als shadcn-Registry-Element oder DTCG/W3C JSON. Der schnellste Weg, ein vollständiges Set in ein shadcn/ui-Projekt zu integrieren:
npx shadcn add https://identityforge.io/r/ambient-sage.jsonDie Tokens bilden zudem die Hälfte einer DESIGN.md: die Werte, auf die sich das schriftliche Briefing bezieht. Zusammen sind sie das, was Sie einem Coding-Agent geben, damit dessen UI konsistent bleibt.
FAQ
Was sind semantische Farb-Tokens?
Farbvariablen, die nach ihrer Rolle statt nach ihrem Farbton benannt sind: --primary, --background, --muted-foreground anstelle von --blue-500. Komponenten werden basierend auf dem Rollennamen gestylt, sodass ein Themenwechsel oder der Wechsel in den Dark-Mode keine Bearbeitung der Komponenten erfordert.
Wie viele Farb-Tokens benötigt ein Designsystem?
Identity Forge verwendet 28 semantische Rollen: Oberflächen mit ihren Vordergrundfarben, Brand- und Muted-Rollen, Statusfarben, Formular-Rollen und fünf Chart-Farben. Jede Rolle besitzt einen Wert für Light- und Dark-Mode.
Was bedeutet die -foreground-Konvention?
Die meisten Basis-Rollen sind mit einer -foreground-Rolle für Texte oder Icons auf dieser Fläche gekoppelt: --primary mit --primary-foreground. Diese Paarung garantiert ohne Rätselraten einen lesbaren Kontrast sowohl im Light- als auch im Dark-Mode.
Wie exportiere ich einen vollständigen Satz semantischer Tokens?
Jedes Identity Forge Kit exportiert seine 28 Rollen (Light + Dark) als CSS-Variablen, Tailwind v3/v4 @theme, als shadcn-Registry-Element oder als DTCG/W3C-JSON. Für shadcn/ui können diese direkt über npx shadcn add https://identityforge.io/r/<slug>.json installiert werden.