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.
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.
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.
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.
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.
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.