# Design-Tokens: eine Quelle der Wahrheit für Farbe und Schrift

[Canonical HTML page](https://gradiently.design/de/guide/design-tokens)

Eine Markenfarbe, die in vierzig Dateien steht, driftet auseinander. Ein Token lebt an einem Ort, und jede Plattform liest von dort. So strukturierst du Design-Tokens, benennst sie dauerhaft und bringst sie in Code und Designtools.

## The short version

- Design-Tokens sind benannte, plattformneutrale Werte für Designentscheidungen wie Farben, Schriftfamilien, Größen, Abstände, Radien, Schatten und Animationszeiten.
- Die meisten Token-Systeme nutzen drei Ebenen: Primitive Tokens enthalten Rohwerte, semantische Tokens beschreiben einen Zweck, und Komponententokens wenden Zwecke auf bestimmte Teile an.
- Das Format der W3C Design Tokens Community Group speichert Tokens als JSON mit den Eigenschaften $value und $type und verweist mit geschweiften Klammern auf andere Tokens.
- Werkzeuge wie Style Dictionary verwandeln eine Token-Datei in CSS Custom Properties, JavaScript sowie iOS- und Android-Ressourcen.
- Dark Mode und mehrere Marken werden zu einer Frage des Austauschs der Werte hinter semantischen Tokens, während Komponenten unverändert bleiben.

**Design-Tokens** sind benannte Werte für jede Designentscheidung, die eine Marke wiederholt: Farben, Schriften, Schriftgrößen, Abstände, Eckenradien, Schatten und Animationszeiten. Statt `#5b21b6` in ein Stylesheet, eine Figma-Datei und eine iOS-App zu tippen, definierst du `color.brand.700` einmal, in einer Datei, und erzeugst daraus das Format jeder Plattform. Änderst du das Token, aktualisiert sich jedes Produkt gleichzeitig. Diese eine Quelle der Wahrheit ist der ganze Sinn.

## So sieht ein Design-Token aus

Ein Token hat einen Namen, einen Wert und einen Typ. Das Format der [W3C Design Tokens Community Group](https://www.w3.org/community/design-tokens/) schreibt sie als JSON, mit Eigenschaften, die mit einem Dollarzeichen beginnen, damit sie nicht mit Gruppennamen kollidieren.

```json
{
  "color": {
    "violet": {
      "100": { "$type": "color", "$value": "#ede9fe" },
      "500": { "$type": "color", "$value": "#8b5cf6" },
      "700": { "$type": "color", "$value": "#6d28d9" },
      "900": { "$type": "color", "$value": "#4c1d95" }
    },
    "ink": { "$type": "color", "$value": "#14121f" },
    "paper": { "$type": "color", "$value": "#faf8ff" }
  },
  "font": {
    "heading": { "$type": "fontFamily", "$value": ["Fraunces", "Georgia", "serif"] },
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 10, "unit": "px" } }
  },
  "duration": {
    "quick": { "$type": "duration", "$value": { "value": 160, "unit": "ms" } }
  }
}
```

Primitive Tokens im Format der Community Group. Gruppen lassen sich frei verschachteln; der Pfad, etwa color.violet.700, wird zum Namen des Tokens.

- color.violet.100: #ede9fe
- color.violet.500: #8b5cf6
- color.violet.700: #6d28d9
- color.violet.900: #4c1d95
- color.ink: #14121f
- color.paper: #faf8ff

Die Farbtokens von oben als Farbfelder. Das sind Rohzutaten: Noch sagt nichts, welche davon ein Button oder eine Überschrift ist.

## Primitive, semantische und Komponententokens

Eine flache Liste von Farben ist eine Palette, kein System. Die Struktur, die über Jahre hält, hat drei Ebenen, die jeweils auf die darunter verweisen. Komponenten berühren nie Rohwerte; sie fragen nach einem Zweck.

| Ebene | Beispielname | Wert | Ändert sich, wenn |
| --- | --- | --- | --- |
| Primitiv | `color.violet.700` | `#6d28d9` | Die Palette neu gestaltet wird |
| Semantisch | `color.action.primary` | `{color.violet.700}` | Eine Rolle zu einer anderen Farbe wechselt |
| Semantisch | `color.text.default` | `{color.ink}` | Dark Mode, eine neue Marke |
| Komponente | `button.primary.background` | `{color.action.primary}` | Eine Komponente eine Ausnahme braucht |

Verweise in geschweiften Klammern sind Aliase. Änderst du color.violet.700, folgt jedes Token, das darauf zeigt.

```json
{
  "color": {
    "action": {
      "primary": { "$type": "color", "$value": "{color.violet.700}" },
      "primary-hover": { "$type": "color", "$value": "{color.violet.900}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.ink}" },
      "on-action": { "$type": "color", "$value": "{color.paper}" }
    },
    "surface": {
      "page": { "$type": "color", "$value": "{color.paper}" },
      "tint": { "$type": "color", "$value": "{color.violet.100}" }
    }
  }
}
```

Semantische Tokens beschreiben, wofür eine Farbe da ist. In dieser Ebene sollten Designer und Entwickler miteinander sprechen.

Viele Teams hören bei zwei Ebenen auf, primitiv und semantisch, und fügen Komponententokens nur dort hinzu, wo eine Komponente wirklich abweicht. So bleibt die Datei klein genug, um sie zu verstehen.

## Design-Tokens so benennen, dass sie halten

Namen überleben Werte. Ein Token namens `color.purple` bricht an dem Tag, an dem die Marke zu Petrol wechselt; ein Token namens `color.action.primary` übersteht das. Benenne semantische Tokens nach ihrer Rolle und halte primitive Namen beschreibend für den Wert.

### Namen, die schlecht altern

- `color.purple` für Buttons verwendet
- `text.dark`, das im Dark Mode hell ist
- `spacing.16` als Layoutregel verwendet
- `blue2`, `blueNew`, `blueFinal`
- `hero.gradient.lisa`, nach einer Person benannt

### Namen, die halten

- `color.action.primary`
- `color.text.default`
- `space.section`, das auf `{space.16}` zeigt
- Eine nummerierte Skala wie `blue.100` bis `blue.900`
- `gradient.hero` mit seinen Stopps als Tokens

Wähle ein Muster, etwa Kategorie, dann Rolle, dann Variante, dann Zustand, und halte es in deinem [Markenstyleguide](https://gradiently.design/de/guide/brand-style-guide) fest. Einheitliche Benennung zählt mehr als die Frage, welches Muster du wählst.

## Von der Token-Datei zu CSS und Apps

Die Token-Datei wird nicht so ausgeliefert, wie sie ist. Ein Build-Schritt verwandelt sie in das, was jede Plattform braucht. Style Dictionary ist das am weitesten verbreitete Open-Source-Werkzeug dafür, und andere lesen dasselbe Format. Für das Web sind das meist CSS Custom Properties.

```css
:root {
  --color-violet-100: #ede9fe;
  --color-violet-700: #6d28d9;
  --color-violet-900: #4c1d95;
  --color-ink: #14121f;
  --color-paper: #faf8ff;

  --color-action-primary: var(--color-violet-700);
  --color-text-default: var(--color-ink);
  --color-surface-page: var(--color-paper);

  --font-heading: Fraunces, Georgia, serif;
  --radius-control: 10px;
  --duration-quick: 160ms;
}

.button {
  background: var(--color-action-primary);
  color: var(--color-paper);
  border-radius: var(--radius-control);
  transition: background var(--duration-quick) ease;
}
```

Erzeugte Ausgabe. Aliase werden zu var() Verweisen, sodass die semantische Ebene bis in den Browser erhalten bleibt. Siehe [CSS-Variablen für Themes](https://gradiently.design/de/guide/css-custom-properties-theming).

Nutzt du Tailwind v4, ist der `@theme`-Block selbst eine Token-Ebene: Jede `--color-*`-Variable wird zu Utilities. [Tailwind Farben](https://gradiently.design/de/guide/tailwind-colors) zeigt, wie du eine Token-Skala dort einbindest. Dieselbe Datei kann auch Swift-Konstanten und Android-Ressourcen erzeugen, und genau dort zahlen sich Tokens für Teams mit mehreren Plattformen aus.

## Dark Mode und mehrere Marken

Weil Komponenten nur semantische Tokens lesen, ist ein Theme einfach ein anderes Set an Werten für diese Ebene. Der Dark Mode definiert `color.text.default` und `color.surface.page` neu; eine zweite Marke definiert `color.action.primary` neu. An den Komponenten ändert sich nichts.

```css
@media (prefers-color-scheme: dark) {
  :root {
    --color-text-default: #e9e5f5;
    --color-surface-page: #0b0a14;
    --color-action-primary: var(--color-violet-500);
  }
}

[data-brand="harbour"] {
  --color-action-primary: #0f766e;
}
```

Zwei Überschreibungen, keine Änderungen an Komponenten. Auch Verläufe verdienen eigene dunkle Werte; [Verläufe im Dark Mode](https://gradiently.design/de/guide/dark-mode-gradients) erklärt, wie du sie abstimmst.

> **Tokens in Designtools** Figma Variables unterstützen Sammlungen und Modi, die sich sauber auf primitive und semantische Tokens sowie helles und dunkles Theme abbilden lassen. Behalte die Token-Datei als Quelle und synchronisiere ins Designtool, nicht umgekehrt, sonst widersprechen sich beide innerhalb eines Monats.

## Design-Tokens einführen

1. **Bestand aufnehmen** Sammle jede Farbe, Schriftgröße und jeden Abstand, die im Einsatz sind. Rechne mit Duplikaten, die sich um eine Hex-Ziffer unterscheiden.
2. **Primitive definieren** Reduziere sie auf klare Skalen. Farbskalen in OKLCH aufzubauen hält die Stufen gleichmäßig; siehe [OKLCH erklärt](https://gradiently.design/de/guide/oklch-explained).
3. **Die semantische Ebene ergänzen** Benenne Rollen: Text, Fläche, Rahmen, Aktion, Rückmeldung. Lass jede auf ein Primitiv zeigen.
4. **Den Build automatisieren** Erzeuge CSS und App-Ressourcen im Build aus der Datei, nie von Hand.
5. **Es absichern** Prüfe per Linter auf rohe Hex-Werte in Komponenten, damit neuer Code vom ersten Tag an Tokens nutzt.

Tokens halten das Produkt einheitlich, aber Marken driften auch in den Grafiken, die außerhalb entstehen: Beiträge, Folien, Banner. Ein Gradiently-Markenkit hält dieselben Entscheidungen fest, deine Farbpaletten, Überschrift- und Fließtextschriften, Logos und Stimme, sodass Designs aus dem Studio dazu passen. Und weil Gradiently in ChatGPT, Claude und anderen Assistenten funktioniert, die Remote-MCP-Server unterstützen, kann ein Assistent mit einem eingeschränkten API-Schlüssel markengerechte Designs aus demselben Arbeitsbereich erstellen. [Markenkonsistenz](https://gradiently.design/de/guide/brand-consistency) behandelt die größere Gewohnheit.

## FAQ

### Was sind Design-Tokens?

Benannte Werte für Designentscheidungen wie Farben, Schriften, Abstände, Radien und Bewegung, gespeichert in einer plattformneutralen Datei und übersetzt in CSS, App-Code und Variablen im Designtool.

### Was ist der Unterschied zwischen primitiven und semantischen Tokens?

Primitive Tokens enthalten Rohwerte, etwa `color.violet.700`. Semantische Tokens beschreiben einen Zweck, etwa `color.action.primary`, und zeigen auf ein Primitiv.

### Sind Design-Tokens dasselbe wie CSS-Variablen?

Nein. Tokens sind die Quelle, gespeichert in einem neutralen Format wie JSON; CSS Custom Properties sind eine daraus erzeugte Ausgabe, neben Ausgaben für andere Plattformen.

### Gibt es ein Standardformat für Design-Tokens?

Die W3C Design Tokens Community Group veröffentlicht ein JSON-Format mit $value, $type und Aliasen in geschweiften Klammern, das Werkzeuge wie Style Dictionary lesen können.

### Wie gehen Design-Tokens mit dem Dark Mode um?

Komponenten lesen semantische Tokens, und ein dunkles Theme liefert andere Werte für diese Tokens, sodass Komponenten keine Änderungen brauchen.