Design-Token-System in der Praxis: 5 Muster für skalierbare Theme- und Multi-Brand-Architektur

前端工程

Design Tokens: Die Atomare Infrastruktur von Design-Systemen

Der größte Schmerzpunkt in Design-Systemen ist nicht fehlende Komponenten—es ist Theme-Wechsel durch Überschreibungen, Markenerweiterungen durch Duplizierung und Dark Mode durch Patches. Design Tokens abstrahieren Designentscheidungen wie Farben, Abstände und Typografie in plattformunabhängige Schlüssel-Wert-Paare und ermöglichen „einmal definieren, überall konsumieren". 2026 hat die W3C Design Token Specification den Candidate Recommendation-Status erreicht, Style Dictionary 4.0+ unterstützt Multi-Plattform-Output, und Design Tokens sind zur Standardinfrastruktur für Design-Systeme geworden.

Dieser Artikel durchläuft 5 Kernmuster und deckt die gesamte Pipeline von Token-Schichtung → Theme-Wechsel → Multi-Brand → Build-Pipeline → Laufzeitdynamik ab.

Kernkonzepte

Konzept Beschreibung
Design Token Atomare Repräsentation einer Designentscheidung als Schlüssel-Wert-Paar
Globaler Token Rohe globale Werte, z.B. blue-500: #3b82f6
Alias-Token Semantischer Alias, z.B. primary: {blue-500}
Komponenten-Token Token auf Komponentenebene, z.B. button-primary-bg: {primary}
Theme Eine Sammlung von Token-Werten, z.B. Hell-/Dunkel-Theme
Multi-Brand Dasselbe Design-System unterstützt mehrere Marken-Token-Sets
Style Dictionary Token-Kompilierungstool mit Multi-Plattform-Output
W3C DTCG Design Token Community Group Spezifikation

Problemanalyse: 5 Herausforderungen in Design-Token-Systemen

  1. Token-Schichtungs-Chaos: Unklare Grenzen zwischen globalen/semantischen/Komponenten-Schichten, übermäßig lange Referenzketten
  2. Theme-Wechsel-Performance: Laufzeit-Theme-Wechsel verursacht Repaint-Flackern
  3. Multi-Brand-Erweiterung: Große Token-Unterschiede zwischen Marken, komplexe Vererbung
  4. Build-Output: Unterschiedliche Ausgabeformate über Plattformen (CSS/JS/Swift/Kotlin)
  5. Design-Zusammenarbeit: Designer nutzen Figma, Entwickler nutzen Code—Token-Sync ist schwierig

Schritt für Schritt: 5 Design-Token-Muster

Muster 1: Dreischichtige Token-Architektur

// tokens/global/color.json
{
  "color": {
    "blue": {
      "100": { "value": "#dbeafe", "type": "color" },
      "500": { "value": "#3b82f6", "type": "color" },
      "900": { "value": "#1e3a8a", "type": "color" }
    },
    "gray": {
      "50": { "value": "#f9fafb", "type": "color" },
      "900": { "value": "#111827", "type": "color" }
    },
    "red": {
      "500": { "value": "#ef4444", "type": "color" }
    },
    "green": {
      "500": { "value": "#22c55e", "type": "color" }
    }
  }
}

// tokens/semantic/color.json
{
  "color": {
    "primary": { "value": "{color.blue.500}", "type": "color" },
    "primary-hover": { "value": "{color.blue.600}", "type": "color" },
    "background": { "value": "{color.gray.50}", "type": "color" },
    "surface": { "value": "#ffffff", "type": "color" },
    "text": { "value": "{color.gray.900}", "type": "color" },
    "text-secondary": { "value": "{color.gray.500}", "type": "color" },
    "error": { "value": "{color.red.500}", "type": "color" },
    "success": { "value": "{color.green.500}", "type": "color" },
    "border": { "value": "{color.gray.200}", "type": "color" }
  }
}

// tokens/component/button.json
{
  "button": {
    "primary": {
      "bg": { "value": "{color.primary}", "type": "color" },
      "bg-hover": { "value": "{color.primary-hover}", "type": "color" },
      "text": { "value": "#ffffff", "type": "color" },
      "border-radius": { "value": "{radius.md}", "type": "borderRadius" },
      "padding-x": { "value": "{spacing.4}", "type": "spacing" },
      "padding-y": { "value": "{spacing.2}", "type": "spacing" }
    },
    "secondary": {
      "bg": { "value": "{color.surface}", "type": "color" },
      "text": { "value": "{color.primary}", "type": "color" },
      "border": { "value": "{color.border}", "type": "color" }
    }
  }
}

Muster 2: Theme-Wechsel (Hell/Dunkel)

// tokens/semantic/color.dark.json
{
  "color": {
    "primary": { "value": "{color.blue.400}", "type": "color" },
    "background": { "value": "{color.gray.900}", "type": "color" },
    "surface": { "value": "#1f2937", "type": "color" },
    "text": { "value": "{color.gray.50}", "type": "color" },
    "text-secondary": { "value": "{color.gray.400}", "type": "color" },
    "border": { "value": "{color.gray.700}", "type": "color" }
  }
}

/* Build-Output: tokens.css */
:root {
  --color-primary: #3b82f6;
  --color-background: #f9fafb;
  --color-surface: #ffffff;
  --color-text: #111827;
  --color-border: #e5e7eb;
  --button-primary-bg: var(--color-primary);
  --button-primary-text: #ffffff;
}

[data-theme="dark"] {
  --color-primary: #60a5fa;
  --color-background: #111827;
  --color-surface: #1f2937;
  --color-text: #f9fafb;
  --color-border: #374151;
  --button-primary-bg: var(--color-primary);
}

// Theme-Wechsler
type Theme = 'light' | 'dark' | 'system';

class ThemeManager {
  private mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
  private listeners: Set<(theme: Theme) => void> = new Set();

  init() {
    const saved = localStorage.getItem('theme') as Theme | null;
    if (saved && saved !== 'system') {
      this.apply(saved);
    } else {
      this.apply(this.mediaQuery.matches ? 'dark' : 'light');
    }
    this.mediaQuery.addEventListener('change', (e) => {
      if (this.getStored() === 'system') {
        this.apply(e.matches ? 'dark' : 'light');
      }
    });
  }

  setTheme(theme: Theme) {
    localStorage.setItem('theme', theme);
    if (theme === 'system') {
      this.apply(this.mediaQuery.matches ? 'dark' : 'light');
    } else {
      this.apply(theme);
    }
    this.listeners.forEach((fn) => fn(theme));
  }

  private apply(mode: 'light' | 'dark') {
    document.documentElement.setAttribute('data-theme', mode);
  }

  private getStored(): Theme {
    return (localStorage.getItem('theme') as Theme) || 'system';
  }

  onChange(fn: (theme: Theme) => void) {
    this.listeners.add(fn);
    return () => this.listeners.delete(fn);
  }
}

Muster 3: Multi-Brand-Token-Vererbung

// brands/brand-a/tokens.json
{
  "color": {
    "primary": { "value": "#3b82f6", "type": "color", "$extensions": { "brand": "A" } },
    "primary-hover": { "value": "#2563eb", "type": "color" }
  },
  "typography": {
    "font-family": { "value": "Inter, sans-serif", "type": "fontFamily" },
    "heading-weight": { "value": "700", "type": "fontWeight" }
  },
  "radius": {
    "base": { "value": "8px", "type": "borderRadius" }
  }
}

// brands/brand-b/tokens.json
{
  "color": {
    "primary": { "value": "#8b5cf6", "type": "color", "$extensions": { "brand": "B" } },
    "primary-hover": { "value": "#7c3aed", "type": "color" }
  },
  "typography": {
    "font-family": { "value": "Poppins, sans-serif", "type": "fontFamily" },
    "heading-weight": { "value": "600", "type": "fontWeight" }
  },
  "radius": {
    "base": { "value": "4px", "type": "borderRadius" }
  }
}

// Marken-Wechsler
type Brand = 'brand-a' | 'brand-b';

async function switchBrand(brand: Brand) {
  const brandCSS = await fetch(`/tokens/${brand}.css`).then((r) => r.text());
  let style = document.getElementById('brand-tokens') as HTMLStyleElement;
  if (!style) {
    style = document.createElement('style');
    style.id = 'brand-tokens';
    document.head.appendChild(style);
  }
  style.textContent = brandCSS;
  document.documentElement.setAttribute('data-brand', brand);
  localStorage.setItem('brand', brand);
}

Muster 4: Style-Dictionary-Build-Pipeline

// style-dictionary.config.mjs
import StyleDictionary from 'style-dictionary';

StyleDictionary.registerTransform({
  name: 'size/pxToRem',
  type: 'value',
  matcher: (token) => token.type === 'spacing' || token.type === 'fontSize',
  transformer: (token) => {
    const base = 16;
    const val = parseFloat(token.value);
    return `${val / base}rem`;
  },
});

StyleDictionary.registerTransformGroup({
  name: 'custom/css',
  transforms: [
    'attribute/cti',
    'name/kebab',
    'time/seconds',
    'size/pxToRem',
    'color/css',
  ],
});

const config = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'custom/css',
      buildPath: 'dist/css/',
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          options: { outputReferences: true },
        },
      ],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [
        {
          destination: 'tokens.js',
          format: 'javascript/es6',
        },
        {
          destination: 'tokens.d.ts',
          format: 'typescript/es6-declarations',
        },
      ],
    },
    json: {
      transformGroup: 'json',
      buildPath: 'dist/json/',
      files: [
        {
          destination: 'tokens.json',
          format: 'json',
        },
      ],
    },
    ios: {
      transformGroup: 'ios-swift-separate',
      buildPath: 'dist/ios/',
      files: [
        {
          destination: 'DesignTokens.swift',
          format: 'ios-swift/class.swift',
          className: 'DesignTokens',
        },
      ],
    },
    android: {
      transformGroup: 'android',
      buildPath: 'dist/android/',
      files: [
        {
          destination: 'design_tokens.xml',
          format: 'android/resources',
        },
      ],
    },
  },
};

export default config;

# Alle Plattformen bauen
npx style-dictionary build

# Token-Änderungen beobachten
npx style-dictionary build --watch

Muster 5: Laufzeit-Dynamische Tokens

// runtime-token-engine.ts
interface TokenValue {
  value: string;
  type: string;
  description?: string;
}

class RuntimeTokenEngine {
  private tokens: Map<string, TokenValue> = new Map();
  private subscribers: Map<string, Set<(value: string) => void>> = new Map();

  loadFromCSS() {
    const styles = getComputedStyle(document.documentElement);
    const allVars = Array.from(document.styleSheets)
      .flatMap((sheet) => {
        try {
          return Array.from(sheet.cssRules);
        } catch {
          return [];
        }
      })
      .filter((rule) => rule instanceof CSSStyleRule)
      .flatMap((rule: CSSStyleRule) => {
        const props: string[] = [];
        for (let i = 0; i < rule.style.length; i++) {
          const prop = rule.style[i];
          if (prop.startsWith('--')) {
            props.push(prop);
          }
        }
        return props;
      });

    const uniqueVars = [...new Set(allVars)];
    uniqueVars.forEach((v) => {
      const val = styles.getPropertyValue(v).trim();
      if (val) {
        this.tokens.set(v, { value: val, type: 'unknown' });
      }
    });
  }

  setToken(name: string, value: string) {
    const varName = name.startsWith('--') ? name : `--${name}`;
    document.documentElement.style.setProperty(varName, value);
    this.tokens.set(varName, { value, type: 'unknown' });
    this.notify(varName, value);
  }

  getToken(name: string): string | undefined {
    const varName = name.startsWith('--') ? name : `--${name}`;
    return getComputedStyle(document.documentElement)
      .getPropertyValue(varName)
      .trim();
  }

  subscribe(name: string, callback: (value: string) => void) {
    const varName = name.startsWith('--') ? name : `--${name}`;
    if (!this.subscribers.has(varName)) {
      this.subscribers.set(varName, new Set());
    }
    this.subscribers.get(varName)!.add(callback);
    return () => this.subscribers.get(varName)?.delete(callback);
  }

  private notify(name: string, value: string) {
    this.subscribers.get(name)?.forEach((fn) => fn(value));
  }
}

Fallstrick-Leitfaden

Fallstrick 1: Token-Referenzketten Zu Tief

// ❌ Falsch: 5-schichtige Referenzkette, schwer zu debuggen
{
  "btn-bg": { "value": "{button.primary.bg}" },
  "button.primary.bg": { "value": "{color.primary}" },
  "color.primary": { "value": "{blue.500}" }
}

// ✅ Richtig: Innerhalb von 3 Schichten halten
{
  "button-primary-bg": { "value": "{color.primary}" },
  "color.primary": { "value": "#3b82f6" }
}

Fallstrick 2: Hartkodierte Farbwerte

/* ❌ Falsch: Hartkodierte Farben */
.card { background: #ffffff; border: 1px solid #e5e7eb; }

/* ✅ Richtig: Token-Variablen verwenden */
.card { background: var(--color-surface); border: 1px solid var(--color-border); }

Fallstrick 3: Theme-Wechsel-Flackern

<!-- ❌ Falsch: Theme nach JS-Laden gesetzt, verursacht Flackern -->

<!-- ✅ Richtig: Inline-Skript blockiert Rendering -->
<script>
  (function() {
    const theme = localStorage.getItem('theme');
    if (theme === 'dark' || (!theme && matchMedia('(prefers-color-scheme: dark)').matches)) {
      document.documentElement.setAttribute('data-theme', 'dark');
    }
  })();
</script>

Fallstrick 4: Komponenten-Token-Überbeanspruchung

// ❌ Falsch: Ein Token für jede Komponenteneigenschaft erstellen
{
  "card-padding-top": { "value": "{spacing.4}" },
  "card-padding-right": { "value": "{spacing.4}" },
  "card-padding-bottom": { "value": "{spacing.4}" },
  "card-padding-left": { "value": "{spacing.4}" }
}

// ✅ Richtig: Semantische Tokens wiederverwenden
{
  "card-padding": { "value": "{spacing.4}" }
}

Fallstrick 5: Token-Typ-Validierung Ignorieren

// ❌ Falsch: Keine Typvalidierung, Farb-Token erhält Abstandswert
// ✅ Richtig: Zur Build-Zeit validieren
StyleDictionary.registerFilter({
  name: 'isValidColor',
  matcher: (token) => {
    if (token.type === 'color') {
      return /^#([0-9a-f]{3}){1,2}$/i.test(token.value) ||
             token.value.startsWith('{');
    }
    return true;
  },
});

Fehlerbehebung

# Fehlermeldung Ursache Lösung
1 Reference not found: {color.xxx} Token referenziert nicht existierenden Schlüssel Referenzpfad-Rechtschreibung prüfen
2 Circular reference detected Token-Kreisreferenz Kreisreferenzkette brechen
3 Invalid token value Ungültiges Token-Wertformat Farb-/Abstandsformat validieren
4 CSS variable not applied Selektor-Spezifität überschrieben CSS-Variablen-Selektor-Spezifität erhöhen
5 Theme flash on load Theme-Init nach Rendering Inline-Blockierungsskript zum Theme-Setzen
6 Style Dictionary build failed Token-Dateiformatfehler JSON-Syntax und $extensions prüfen
7 Token not found in output Token nicht von Quelle gematcht Source-Glob-Pfad prüfen
8 Platform output mismatch Inkonsistente Transform-Regeln transformGroup-Konfiguration vereinheitlichen
9 Figma sync conflict Figma-Tokens nicht synchron mit Code Token Studio für bidirektionalen Sync verwenden
10 Runtime token override fails Laufzeit-Override ohne Wirkung CSS-Variablen-Priorität und Scope prüfen

Erweiterte Optimierung

  1. Token-Studio-Integration: Figma-Plugin für bidirektionalen Design-Code-Token-Sync
  2. Token-Versionierung: Semantisches Versioning + automatische Changelog-Generierung
  3. A/B-Test-Tokens: Laufzeit-dynamischer Token-Wechsel für visuelles A/B-Testing
  4. Token-Lint: ESLint-Plugin zur Erkennung hartkodierter Design-Werte im Code
  5. Token-Dokumentationsseite: Automatisch generierte visuelle Token-Dokumentation

Vergleich

Dimension CSS-Variablen Design Tokens Tailwind-Konfiguration CSS-in-JS-Theme
Plattform-Support Nur Web Web/iOS/Android Nur Web Nur Web
Typsicherheit ❌ ✅ ✅ ✅
Theme-Wechsel ✅ ✅ ✅ ✅
Multi-Brand Manuell Native Unterstützung Konfigurationswechsel Konfigurationswechsel
Design-Zusammenarbeit ❌ ✅ Figma-Sync ❌ ❌
Build-Output CSS CSS/JS/Swift/Kotlin CSS/JS JS

Zusammenfassung: Design-Token-Systeme sind die Schlüsselinfrastruktur für die Evolution von Design-Systemen von „Komponentenbibliotheken" zu „Designsprachen". Die dreischichtige Token-Architektur (global → semantisch → Komponente) kombiniert mit Style-Dictionary-Multi-Plattform-Output etabliert eine Single Source of Truth für Designentscheidungen. 2026 wird die reifende W3C-DTCG-Spezifikation die Token-Standardisierung vorantreiben und Multi-Brand- und Laufzeit-Dynamik-Tokens zu Standardfunktionen für Enterprise-Design-Systeme machen.

Empfohlene Online-Tools

Probiere diese browser-lokalen Tools aus — keine Registrierung erforderlich →

#Design Token#设计系统#主题切换#CSS变量#2026#前端工程