Design Tokens sind die benannten Grundwerte deines Designs: Farben, Abstände, Schriftgrößen und Radien. In Tailwind CSS lassen sie sich als CSS-Variablen hinterlegen und direkt als Utility-Klassen nutzen. Dieser Leitfaden zeigt, wie du Tokens sauber verankerst, sodass dein Theme an einer Stelle steuerbar bleibt.
- Tokens sind benannte Entscheidungen. Nicht blau, sondern Primärfarbe.
- In Tailwind v4 stehen sie als CSS-Variablen im Theme und gelten damit für Utilities und eigenes CSS gleichzeitig.
- Wenige Rollen schlagen viele Werte. Drei Grautöne, die man versteht, sind besser als zwölf, die man rät.
- Ein Dark Mode ist mit Tokens ein Austausch von Werten, kein zweiter Satz Klassen.
Warum Tokens statt fester Werte
Wenn Farbwerte und Abstände quer durch das Projekt fest verdrahtet sind, wird jede Anpassung zur Suchaktion. Ein Token bündelt den Wert unter einem sprechenden Namen, etwa color-primary oder space-4. Eine Änderung an der Quelle wirkt dann überall.
Namen schaffen zudem eine gemeinsame Sprache. Design und Entwicklung reden über primary und surface statt über zufällige Hex-Zahlen. Das reduziert Missverständnisse und hält die Oberfläche über viele Komponenten hinweg konsistent.
Tokens als CSS-Variablen definieren
Der natürliche Ort für Tokens sind CSS-Variablen im :root-Block deiner Stylesheet-Datei. Dort legst du Werte wie --color-primary, --radius-md oder --space-4 an. Weil es echte CSS-Variablen sind, stehen sie überall zur Verfügung und lassen sich zur Laufzeit ändern.
Halte die Namen flach und vorhersehbar. Eine Skala wie --space-1 bis --space-8 oder --color-fg und --color-bg ist leichter zu merken als frei erfundene Bezeichnungen. Diese Ordnung zahlt sich aus, sobald das Projekt wächst.
:root { --blue-600: #1f5eff; --slate-900: #0f172a; --color-primary: var(--blue-600); --color-text: var(--slate-900); --radius-md: 8px;}
Tokens in Tailwind verfügbar machen
In Tailwind CSS v4 konfigurierst du das Theme direkt im Stylesheet über den theme-Block. Dort verweist du auf deine Variablen, zum Beispiel color-primary auf var(--color-primary). Aus diesem Eintrag erzeugt Tailwind automatisch passende Utilities wie bg-primary oder text-primary.
So bleibt eine einzige Quelle der Wahrheit erhalten. Deine Komponenten nutzen die Utility-Klassen, diese greifen auf die Tokens zu, und die Tokens leben zentral in den Variablen. Änderst du einen Wert dort, zieht die Anpassung durch alle Klassen.
Von der Variable bis zur Klasse im Bauteil. Nur die erste Station fasst du an, wenn sich etwas ändert.
@theme { --color-primary: var(--color-primary); --color-text: var(--color-text);} /* daraus entstehen bg-primary, text-primary, border-primary */
Semantische statt roher Namen
Es lohnt sich, zwei Ebenen zu trennen. Auf der unteren Ebene stehen rohe Werte wie blue-500 mit ihrem Farbwert. Auf der oberen Ebene stehen semantische Tokens wie primary, die auf einen rohen Wert zeigen. Komponenten nutzen nur die semantische Ebene.
Dieser kleine Umweg macht dein System flexibel. Willst du die Markenfarbe wechseln, änderst du nur, worauf primary zeigt. Kein Bauteil muss angefasst werden, weil keines direkt an einen rohen Wert gebunden ist.
- primaryPrimärfarbe#1f5eff
- surfaceFläche#f8fafc
- textText#0f172a
- borderRand#e2e8f0
Links, was eine mittelgroße Seite an Werten hergibt. Rechts, was davon als Rolle in ein Projekt gehört.
- blau-500, blau-600, blau-hell.
- Beim Rebrand heißt Grün plötzlich blau-500.
- Niemand weiß, welcher der beiden Grautöne für Ränder ist.
- Der Dark Mode braucht einen zweiten Satz Namen.
- primary, surface, border, text.
- Beim Rebrand ändert sich nur, worauf primary zeigt.
- border ist border, egal welcher Grauton dahinter liegt.
- Der Dark Mode überschreibt dieselben vier Namen.
Wenige Rollen schlagen viele Werte.
Eine Liste aus Hex-Zahlen ist eine Bestandsaufnahme. Ein System wird daraus erst, wenn jeder Wert eine Aufgabe hat.
Themes über Tokens umschalten
Weil Tokens CSS-Variablen sind, wird ein Dark-Mode fast beiläufig möglich. Du überschreibst dieselben Variablen in einem zweiten Kontext, etwa unter einem data-theme-Attribut oder einer Klasse am Wurzelelement. Die Utility-Klassen bleiben unverändert.
Die Komponenten wissen nichts vom aktiven Theme, sie lesen einfach die aktuellen Variablenwerte. So schaltest du zwischen hell und dunkel um, ohne eine einzige Klasse in den Bauteilen anzufassen.
:root { --color-surface: #ffffff; --color-text: #0f172a; } [data-theme="dark"] { --color-surface: #0f1115; --color-text: #f4f5f7; }
Tokens pflegen und dokumentieren
Ein Token-Satz ist nur so gut wie seine Pflege. Halte die Liste kurz und entferne Werte, die niemand nutzt. Jeder zusätzliche Token, der keinen klaren Zweck hat, macht das System schwerer statt reicher.
Eine knappe Dokumentation hilft dem Team. Ein Abschnitt in der README oder eine DESIGN.md, die Farben, Abstände und ihre Bedeutung auflistet, sorgt dafür, dass neue Bauteile dieselben Werte verwenden und das Design konsistent bleibt.
Woran Token-Sätze scheitern
Ein Satz Tokens ist schnell angelegt. Dass er ein Jahr später noch gilt, ist die eigentliche Arbeit.
- Zu viele Werte. Zwölf Grautöne heißen, dass niemand mehr weiß, welcher wofür ist. Drei, die eine Aufgabe haben, reichen fast immer.
- Namen, die die Farbe nennen. blau-500 überlebt keinen Rebrand. Primär, Fläche, Rand und Text überleben ihn.
- Ausnahmen im Bauteil. Ein einzelnes hartes #1f2937 im Code ist die Stelle, an der ein Dark Mode später bricht.
Ein Token ist eine Entscheidung mit Namen. Ohne Namen ist es nur ein Wert.
Dark Mode ohne zweiten Satz Klassen
Wenn Farben als Tokens stehen, ist ein Dark Mode ein Austausch von Werten. Du definierst dieselben Namen unter einem Selektor noch einmal, und alles, was die Namen benutzt, zieht mit.
Zwei Dinge musst du selbst prüfen: Bilder brauchen im Dunkeln oft weniger Kontrast, und feste Farbwerte in einzelnen Bauteilen fallen erst dort auf. Wer von Anfang an über Tokens arbeitet, hat beim Umschalten fast nichts zu tun.
