Token-Architektur für mehrere Themes und Marken

Ein Theme ändert den Farbmodus derselben Marke (helle und dunkle Versionen desselben Produkts). Eine Brand ist eine andere visuelle Identität – dieselben Komponenten eines Designsystems werden mit unterschiedlichen Farben, einer anderen Typografie und anderen Abständen dargestellt, um verschiedene Produkte oder Kunden zu bedienen. Beide verwenden dieselbe Token-Architektur, jedoch auf unterschiedlichen Abstraktionsebenen.

Primitive Tokens sind die vollständige Palette von Rohwerten, die dem System zur Verfügung stehen. Dazu gehören jede Farbabstufung (color-blue-50 bis color-blue-900), jede Abstandseinheit und jede Schriftgröße. Primitive Tokens werden nie direkt in Komponenten verwendet, sondern nur von semantischen Tokens referenziert. Die Palette wird einmal definiert und von allen Themes und Marken gemeinsam genutzt.

Semantische Tokens drücken eine Absicht aus: color-background-page, color-text-primary, color-action-primary. Jedes semantische Token referenziert einen für das aktuelle Theme geeigneten primitiven Token-Wert. Komponenten werden ausschließlich auf Grundlage semantischer Tokens erstellt. Auf dieser Ebene findet das Theming statt.

Im hellen Theme referenziert color-background-page color-white, color-text-primary referenziert color-gray-900 und color-action-primary referenziert color-blue-500. Diese Zuordnungen sind in einer themenspezifischen Token-Datei definiert, die die semantische Ebene für den hellen Kontext überschreibt.

Im dunklen Theme referenziert color-background-page color-gray-950, color-text-primary referenziert color-gray-50 und color-action-primary referenziert color-blue-400 (für den Kontrast auf dunklen Hintergründen etwas heller). Nur die semantischen Zuordnungen ändern sich – die primitive Palette und alle Komponenten bleiben unverändert.

Marke A verwendet Blau als Primärfarbe (color-action-primary: {color-blue-500}). Marke B verwendet Grün (color-action-primary: {color-green-500}). Die Button-Komponente liest var(--color-action-primary) – sie weiß nichts darüber, welche Marke aktiv ist. Markenüberschreibungen ändern ausschließlich semantische Token-Zuordnungen, niemals den Komponentencode.

CSS Custom Properties machen den Theme-Wechsel zur Laufzeit unkompliziert. Speichern Sie das aktuelle Theme in einem Datenattribut: document.documentElement.setAttribute('data-theme', 'dark'). CSS-Regeln überschreiben die semantischen Tokens innerhalb von [data-theme="dark"]. Der Browser löst alle var()-Referenzen sofort in die neuen Werte auf – ein erneutes Rendern durch JavaScript ist nicht erforderlich.

Für verschiedene Marken, die als separate Deployments bereitgestellt werden, verwenden Sie Theming zur Build-Zeit: Generieren Sie mit Style Dictionary separate CSS-Token-Dateien pro Marke und laden Sie beim Start der Anwendung die passende Marken-CSS-Datei. Dieser Ansatz eignet sich, wenn die Marke zum Zeitpunkt des Deployments festgelegt wird (unterschiedliche Domains, Subdomains oder White-Label-Instanzen) und nicht durch eine Benutzerinteraktion.

Ein System mit mehreren Marken und Themes erfordert eine zweidimensionale Matrix: Marke A hell, Marke A dunkel, Marke B hell, Marke B dunkel. CSS Custom Properties bewältigen dies elegant mit verschachtelten Selektoren: [data-brand="a"][data-theme="dark"] überschreibt die semantischen Tokens für diese spezifische Kombination. Vier Kombinationen bedeuten vier CSS-Blöcke und nicht vier Codebasen.

Mit der Weiterentwicklung des Designsystems werden Tokens hinzugefügt, umbenannt oder entfernt. Stellen Sie Tokens im selben Repository wie den Code unter Versionskontrolle. Wenn Sie ein Token stilllegen, behalten Sie den alten Namen für einen Release-Zyklus als Alias bei, der auf den neuen Namen verweist, fügen Sie einen Hinweis zur Stilllegung hinzu und aktualisieren Sie den nutzenden Code. Stimmen Sie Token-Änderungen in Design und Engineering über ein strukturiertes Changelog ab.

Governance legt fest, wer Tokens hinzufügen oder ändern darf und welcher Review-Prozess erforderlich ist. Primitive Tokens erfordern die Freigabe des Designteams. Semantische Tokens müssen sowohl vom Design- als auch vom Engineering-Team geprüft werden. Component-Tokens können vom zuständigen Component-Owner verwaltet werden. Ohne diese Governance entstehen doppelte Tokens, und die Garantie einer „Single Source of Truth“ wird hinfällig.

Warum sollten Komponenten statt primitiver Tokens semantische Tokens referenzieren?

Themes ändern die Farbmodi innerhalb einer Marke; Brands sind unterschiedliche visuelle Identitäten. Primitive Tokens bilden die rohe Farbpalette ab, semantische Tokens drücken Bedeutung aus und ermöglichen Theming. Komponenten verwenden ausschließlich semantische Tokens. Dark Mode und Brand-Overrides ändern nur die Zuordnungen semantischer Tokens – die Komponenten bleiben unverändert. Runtime-Theming verwendet CSS Custom Properties mit [data-theme]-Selektoren; beim Build-time-Branding wird für jede Brand ein eigenes CSS generiert. Token-Governance und Versionierung sorgen dafür, dass das System bei seiner Weiterentwicklung konsistent bleibt.