Design Tokens zu CSS Pipeline aufbauen

1. Warum Design Tokens ein Synchronisationsproblem lösen

Design Tokens sind benannte, plattformunabhängige Design-Entscheidungen, etwa eine Markenfarbe, ein Spacing-Schritt oder eine Schriftgröße, gespeichert als strukturierte Daten statt als CSS-, Swift- oder Kotlin-Code. Das Grundproblem, das Design Tokens lösen: Ohne zentrale Quelle pflegt jedes Plattform-Team seine eigene Kopie derselben Werte, ein Web-Team in einer Tailwind-Konfiguration, ein iOS-Team in einer Swift-Datei, ein Android-Team in XML-Ressourcen. Eine Änderung der Markenfarbe erfordert drei koordinierte Pull Requests, und die Wahrscheinlichkeit, dass eine Plattform vergessen wird, steigt mit jeder weiteren Iteration.

Der zentrale Vorteil von Design Tokens liegt in der Trennung von Design-Entscheidung und Plattform-Repräsentation. Ein Token wie color.brand.500 mit dem Wert oklch(0.55 0.18 275) existiert genau einmal, in einer maschinenlesbaren Quelle, typischerweise JSON. Eine Transformationspipeline generiert daraus automatisch die passende Syntax für jede Zielplattform, CSS Custom Properties für Web, ein Swift-Enum für iOS, XML-Ressourcen für Android, ohne dass ein Mensch den Wert an mehreren Stellen manuell abtippt.

Dieser Artikel beschreibt den vollständigen Weg von der Token-Quelle bis zum ausgelieferten CSS: Struktur der JSON-Dateien, Referenz- versus Alias-Tokens, die eigentliche Transformationspipeline mit Style Dictionary, sowie Governance-Fragen, wer Design Tokens überhaupt ändern darf, bevor eine Änderung produktiv wird.

2. Die Token-Quelle strukturieren: Kategorien und Ebenen

Eine gut strukturierte Token-Quelle folgt typischerweise einer Kategorie-Eigenschaft-Wert-Hierarchie, wie sie auch die Design Tokens Community Group als Standard vorschlägt. Die oberste Ebene gruppiert nach Kategorie (color, spacing, typography), die zweite Ebene nach konkreter Eigenschaft (brand, neutral, danger), und die unterste Ebene enthält den eigentlichen Wert, oft mit einer numerischen Skala wie 50 bis 900 für Farbabstufungen.

Diese Struktur ist keine Formalität, sie bestimmt direkt, wie gut die spätere Pipeline skaliert. Eine flache, unstrukturierte Liste von Tokens ohne Kategorisierung funktioniert für ein kleines Projekt mit zwanzig Werten, wird aber bei einem Design System mit mehreren hundert Design Tokens schnell unübersichtlich. Konsistente Kategorisierung erlaubt außerdem automatisierte Validierung, etwa die Prüfung, dass jede Farbkategorie eine vollständige Skala von 50 bis 900 besitzt, statt lückenhaft zu sein.

{
  "color": {
    "brand": {
      "500": { "value": "oklch(0.55 0.18 275)", "type": "color" },
      "600": { "value": "oklch(0.48 0.19 275)", "type": "color" }
    },
    "neutral": {
      "50":  { "value": "oklch(0.98 0.01 275)", "type": "color" },
      "900": { "value": "oklch(0.15 0.02 275)", "type": "color" }
    }
  },
  "spacing": {
    "unit": { "value": "0.25rem", "type": "dimension" },
    "md":   { "value": "1rem", "type": "dimension" },
    "lg":   { "value": "1.5rem", "type": "dimension" }
  }
}

3. Referenz-Tokens und Alias-Tokens trennen

Ein entscheidendes Architekturprinzip bei Design Tokens ist die Trennung zwischen Referenz-Tokens (auch Basis- oder Global-Tokens genannt) und Alias-Tokens (auch semantische Tokens genannt). Referenz-Tokens wie color.blue.500 beschreiben einen rohen, kontextlosen Wert. Alias-Tokens wie color.action.primary verweisen auf einen Referenz-Token und geben ihm eine semantische Bedeutung im Kontext einer konkreten UI-Rolle.

Diese zweistufige Struktur macht Theme-Wechsel und Rebranding erheblich einfacher. Wenn color.action.primary im Dark Mode auf einen anderen Referenz-Token zeigen soll als im Light Mode, ändert sich nur die Zuordnung im Alias-Layer, während sämtliche Komponenten weiterhin denselben semantischen Token color.action.primary referenzieren und nichts an ihrem eigenen Code anpassen müssen. Ohne diese Trennung müsste jede Komponente direkt auf rohe Farbwerte verweisen, was einen globalen Theme-Wechsel zu einer riskanten Suchen-und-Ersetzen-Operation macht.

{
  "color": {
    "action": {
      "primary": {
        "value": "{color.brand.500}",
        "type": "color",
        "comment": "Semantic alias — points to a raw reference token"
      },
      "primary-hover": {
        "value": "{color.brand.600}",
        "type": "color"
      },
      "danger": {
        "value": "{color.red.500}",
        "type": "color"
      }
    }
  }
}

4. Die Transformationspipeline mit Style Dictionary aufbauen

Style Dictionary von Amazon ist das verbreitetste Werkzeug, um Design Tokens aus einer JSON-Quelle in plattformspezifische Ausgabeformate zu transformieren. Die Konfiguration definiert für jede Zielplattform einen eigenen Build-Schritt mit passendem Transformer und Format, etwa CSS Custom Properties für Web, ein Swift-Dictionary für iOS oder eine XML-Ressourcendatei für Android. Der entscheidende Vorteil: Die Quelle bleibt eine einzige Wahrheit, während beliebig viele Plattform-Outputs automatisch aus ihr abgeleitet werden.

Diese Pipeline läuft typischerweise als Teil des CI-Prozesses, ausgelöst bei jeder Änderung an den Token-Dateien. Das bedeutet: Eine Design-Änderung an einem einzigen JSON-Wert propagiert automatisch in einen neuen Build für Web, iOS und Android, ohne dass ein Entwickler manuell drei separate Pull Requests erstellen muss. Für Teams mit häufigen Design-Iterationen reduziert diese Automatisierung den Koordinationsaufwand erheblich.

// style-dictionary.config.js — one source, multiple platform outputs
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables',
        options: { outputReferences: true },
      }],
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'build/ios/',
      files: [{ destination: 'Tokens.swift', format: 'ios-swift/enum-swift5' }],
    },
    android: {
      transformGroup: 'android',
      buildPath: 'build/android/',
      files: [{ destination: 'tokens.xml', format: 'android/resources' }],
    },
  },
};

// Build command: npx style-dictionary build

5. Von Tokens zu CSS Custom Properties

Das CSS-Ziel der Pipeline generiert typischerweise eine einzige Datei mit :root-Deklarationen, in der jeder Token als Custom Property auftaucht. Die Option outputReferences in Style Dictionary erhält dabei die semantische Referenz-Struktur aus Abschnitt drei: Statt color.action.primary direkt in den rohen Hex- oder OKLCH-Wert aufzulösen, generiert die Pipeline var(--color-brand-500) als Wert der Alias-Property, wodurch die Beziehung zwischen semantischem und Referenz-Token auch im ausgelieferten CSS sichtbar bleibt.

Diese generierte CSS-Datei wird typischerweise als eine der ersten Dateien in der ITCSS-Settings-Schicht importiert und bildet damit das Fundament, auf dem alle Komponentenregeln aufbauen. Wichtig: Diese Datei wird niemals manuell editiert, jede Änderung erfolgt ausschließlich an der JSON-Quelle, gefolgt von einem erneuten Pipeline-Lauf. Ein direktes Bearbeiten der generierten Datei würde bei nächster Ausführung der Pipeline kommentarlos überschrieben.

/* build/css/tokens.css — generated, never edited by hand */
:root {
  --color-brand-500: oklch(0.55 0.18 275);
  --color-brand-600: oklch(0.48 0.19 275);
  --color-neutral-50: oklch(0.98 0.01 275);
  --color-neutral-900: oklch(0.15 0.02 275);

  /* Semantic aliases reference the raw values, relationship stays visible */
  --color-action-primary: var(--color-brand-500);
  --color-action-primary-hover: var(--color-brand-600);
  --color-action-danger: var(--color-red-500);

  --spacing-unit: 0.25rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
}

6. Themes und Modi über Token-Ebenen abbilden

Dark Mode oder Marken-Varianten lassen sich in einer Design Tokens-Pipeline elegant über zusätzliche Themen-Dateien abbilden, die nur den Alias-Layer überschreiben, ohne den Referenz-Layer zu duplizieren. Eine Datei theme.dark.json ändert etwa color.action.primary auf einen helleren Referenz-Token, während die Grundpalette in color.json unverändert bleibt und für beide Themes gemeinsam genutzt wird.

Die Pipeline generiert für jedes Theme einen eigenen CSS-Layer oder eine eigene Klasse, etwa [data-theme="dark"], der ausschließlich die geänderten Alias-Werte enthält. Dieser Ansatz hält die generierte CSS-Datei klein, weil nicht die komplette Farbpalette dupliziert wird, sondern nur die wenigen semantischen Zuordnungen, die sich zwischen den Themes tatsächlich unterscheiden.

/* build/css/tokens.dark.css — generated from theme.dark.json */
[data-theme="dark"] {
  --color-action-primary: var(--color-brand-300);
  --color-surface: var(--color-neutral-900);
  --color-text: var(--color-neutral-50);
}

7. Token-Validierung und CI-Integration

Eine automatisierte Pipeline für Design Tokens ist nur so verlässlich wie ihre Validierungsschicht. Ein JSON-Schema, das Pflichtfelder wie value und type für jeden Token erzwingt, verhindert strukturell fehlerhafte Token-Dateien, bevor sie überhaupt in die Transformationspipeline gelangen. Ergänzend prüft ein Contrast-Checker automatisiert, ob Farb-Token-Kombinationen wie Text- und Hintergrundfarbe die WCAG-Kontrastanforderungen erfüllen, direkt im CI, bevor eine Design-Änderung gemergt wird.

Ein zweiter wichtiger CI-Schritt ist ein Diff-Report, der bei jedem Pull Request auflistet, welche konkreten Design Tokens sich geändert haben und welche generierten CSS-Werte davon betroffen sind. Für Reviewer ohne tiefes CSS-Wissen macht das die Auswirkung einer Token-Änderung greifbar, ohne die komplette generierte Ausgabedatei manuell durchsuchen zu müssen.

8. Governance: wer darf Tokens ändern

Governance ist der am häufigsten unterschätzte Teil einer Design Tokens-Pipeline. Ohne klare Verantwortlichkeit ändert jedes Team, das gerade eine Komponente baut, im Zweifel einfach einen bestehenden Token, statt einen neuen anzulegen oder Rücksprache zu halten, was schleichend zu Bedeutungsverschiebungen führt, etwa wenn color.brand.500 nach mehreren kleinen Anpassungen nicht mehr der eigentlichen Markenfarbe entspricht.

Ein bewährtes Modell ist ein dediziertes Design-System-Team oder eine designierte Person mit alleiniger Merge-Berechtigung für die Token-Quelle, während Feature-Teams Änderungswünsche über Pull Requests mit klarer Begründung einreichen. Diese Governance-Struktur macht Design Tokens zu einem verwalteten Produkt statt zu einem Nebenprodukt einzelner Feature-Entwicklungen, was langfristig verhindert, dass die Token-Quelle zu einem unübersichtlichen Sammelsurium individueller Anpassungen wird.

9. Manuelle Pflege vs. automatisierte Pipeline im Vergleich

Die folgende Tabelle stellt gegenüber, wie sich manuell gepflegte, plattformspezifische Werte von einer automatisierten Design Tokens-Pipeline unterscheiden.

Der Aufwand für den initialen Pipeline-Aufbau amortisiert sich meist bereits nach wenigen Design-Iterationen, insbesondere bei Produkten mit mehr als einer Zielplattform, wo manuelle Synchronisation sonst zu einem wiederkehrenden Koordinationsaufwand zwischen mehreren Teams wird.

10. Zusammenfassung

Design Tokens lösen das Synchronisationsproblem plattformübergreifender Produkte, indem Farben, Spacing und Typografie einmal zentral als strukturierte Daten definiert und automatisiert in plattformspezifische Formate transformiert werden. Die Trennung zwischen Referenz-Tokens und semantischen Alias-Tokens macht Theme-Wechsel und Rebranding zu einer lokalen Änderung im Alias-Layer, statt zu einer riskanten projektweiten Suchen-und-Ersetzen-Operation.

Eine Pipeline mit Style Dictionary automatisiert die Transformation von JSON zu CSS Custom Properties, Swift und Kotlin, während JSON-Schema-Validierung und Kontrast-Checks im CI strukturelle und inhaltliche Fehler abfangen, bevor eine Änderung produktiv wird. Klare Governance, wer Design Tokens ändern darf, verhindert schließlich, dass die zentrale Quelle selbst zu einem unübersichtlichen Sammelsurium individueller Anpassungen verkommt.

11. FAQ: Design Tokens zu CSS Pipeline