Die meisten Token-Implementierungen scheitern nicht an der Technik, sondern an der Struktur. Wer keine Taxonomie hat, produziert Redundanz und Inkonsistenz. Die richtige Architektur entscheidet, ob ein Token-System mit 50 oder 5.000 Tokens gleich gut funktioniert.
Das 3-Tier-Modell
Das etablierte Architekturmuster unterscheidet drei Ebenen, die aufeinander aufbauen:
Tier 1: Primitive Tokens definieren die Rohwerte – die vollständige Palette aller verfügbaren Werte. Sie sind beschreibend benannt: color.blue.500, spacing.16, font.size.24. Primitive Tokens werden nie direkt in Komponenten verwendet. Sie sind die Palette, nicht die Anwendung.
Tier 2: Semantic Tokens (auch Alias Tokens) geben Primitives eine funktionale Bedeutung: color.action.primary: {color.blue.500}, spacing.component.gap: {spacing.16}. Sie beschreiben den Verwendungszweck, nicht den Wert. Das ist der entscheidende Architekturvorteil: Wenn sich die Markenfarbe ändert, wird ein Semantic Token umverdrahtet – alle Komponenten folgen automatisch.
Tier 3: Component Tokens binden Semantik an konkrete UI-Elemente: button.primary.bg: {color.action.primary}, card.padding: {spacing.component.gap}. Sie ermöglichen komponentenspezifisches Theming ohne die globale Semantik zu brechen.
Aliasing-Strategien
Aliasing ist das Herzstück der Token-Architektur. Ein Token verweist auf einen anderen Token statt auf einen konkreten Wert. Dadurch entstehen Referenzketten: button.primary.bg → color.action.primary → color.blue.500 → #2563EB.
Die optimale Aliasing-Tiefe ist zwei Stufen: Component → Semantic → Primitive. Drei Stufen sind das Maximum. Mehr Stufen machen das System unübersichtlich und schwer debuggbar. Eine Faustregel: Wenn ein Entwickler den Wert eines Tokens nicht innerhalb von drei Klicks zurückverfolgen kann, ist die Kette zu lang.
Naming Conventions
Das CTI-Schema (Category-Type-Item) hat sich als Standard etabliert: color.background.page, spacing.inset.medium, font.size.heading.large. Die wichtigsten Regeln:
Token-Namen beschreiben Funktion, nicht Werte: color.border.subtle statt color.gray.300. Token-Namen enthalten keine plattformspezifischen Begriffe: spacing.4 statt padding-sm. Token-Namen verwenden konsistente Trennzeichen: Punkte (.) im JSON, Bindestriche (-) in CSS.
Anti-Patterns
Zu flache Struktur: Alle Tokens auf einer Ebene, keine Hierarchie. Ergebnis: 500 Tokens ohne erkennbare Ordnung.
Zu tiefe Struktur: Fünf Ebenen Aliasing für einen einfachen Farbwert. Ergebnis: Kein Entwickler versteht mehr, woher ein Wert kommt.
Fehlende Semantik: Primitive Tokens direkt in Komponenten: background: var(--color-blue-500). Ergebnis: Jedes Rebranding erfordert das Durchsuchen aller Komponentendateien.
Inkonsistente Benennung: Mischung aus verschiedenen Schemata in einem System. Ergebnis: Niemand kann Token-Namen vorhersagen.
Multi-Brand und Multi-Theme
Das 3-Tier-Modell ermöglicht Multi-Brand-Setups: Primitive Tokens bleiben bei allen Brands gleich (gleiche Palette). Semantic Tokens werden pro Brand überschrieben: color.action.primary verweist bei Brand A auf Blau, bei Brand B auf Grün. Component Tokens bleiben identisch – die Komponenten funktionieren automatisch mit jedem Brand.
Dark Mode funktioniert nach demselben Prinzip: Die Semantic Tokens werden pro Mode (Light/Dark) definiert, die Primitive Palette bleibt identisch.
Kernpunkte
- Das 3-Tier-Modell (Primitive → Semantic → Component) ist der Architekturstandard für skalierbare Token-Systeme.
- Aliasing-Tiefe von maximal zwei Stufen hält das System debuggbar.
- Token-Namen beschreiben Funktion, nicht Werte –
color.border.subtlestattcolor.gray.300. - CTI (Category-Type-Item) hat sich als Naming Convention etabliert.
- Fehlende Semantik macht jedes Rebranding zur Mammutaufgabe.
- Multi-Brand und Dark Mode basieren auf dem gleichen Architekturprinzip: Semantic Tokens überschreiben, Rest bleibt stabil.
