---
type: ressource
agent_ready: true
description: "Einstiegs- und Anwendungsguide für den maschinenlesbaren Token-Export des Designsystems Warm Navigator (Bundle-Default-Palette) mit Struktur, Alias-Syntax, Tailwind-Integration, CSS-Variablen-Generierung und Sync-Regeln, damit jeder KI-Agent und jedes Build-Tool die Tokens aus tokens.json korrekt konsumieren kann."
tags:
  - designsystem
  - tokens
  - tailwind
  - bundle
created: 2026-04-23
updated: 2026-05-19
---

# Tokens

`tokens.json` ist der maschinenlesbare Export aller Designsystem-Tokens des Bundle-Default-Palette "Warm Navigator": Farben, Typografie, Spacing, Radien, Schatten, Motion, Breakpoints, Grid, Icon-Sizes und Komponenten-Defaults. Anwender, die eine eigene Marken-Palette verwenden möchten, überschreiben den Default-Pfad über die Skill-Config der konsumierenden Skills.

## Wofür

- **Tailwind-Config generieren** (siehe unten).
- **CSS-Custom-Properties** für Nicht-Tailwind-Projekte erzeugen.
- **Figma Tokens Studio** synchronisieren (importiert JSON direkt).
- **Design-to-Code-Pipelines** mit Style Dictionary, Theo oder eigenen Scripts befüttern.
- **KI-Agenten** strukturiert die Werte abfragen lassen, statt sie aus Markdown zu parsen.

## Struktur

Das JSON folgt dem [Design Tokens Community Group](https://design-tokens.github.io/community-group/format/)-Format. Jeder Token-Knoten hat `value` und optional `description`.

```json
"color": {
  "brand": {
    "teal": { "value": "#0D9488", "description": "Primär-Akzent" }
  }
}
```

Verschachtelung ist frei, Leaf-Nodes sind Objekte mit `value`.

## Alias-Syntax

Tokens können auf andere Tokens verweisen:

```json
"text": {
  "primary": { "value": "{color.brand.deep-sea}" }
}
```

Der Resolver ersetzt `{path.to.token}` durch den Literal-Wert. Gängige Tools (Style Dictionary, Tokens Studio) beherrschen das out-of-the-box.

## Tailwind-Integration

Für ein Next.js/Astro/Vite-Projekt mit Tailwind:

```js
// tailwind.config.ts
import tokens from "./tokens/tokens.json" assert { type: "json" };

const flat = (obj: any, prefix = ""): Record<string, string> =>
  Object.entries(obj).reduce((acc, [k, v]: any) => {
    const key = prefix ? `${prefix}-${k}` : k;
    if (v && typeof v === "object" && "value" in v) acc[key] = v.value;
    else if (v && typeof v === "object") Object.assign(acc, flat(v, key));
    return acc;
  }, {} as Record<string, string>);

export default {
  theme: {
    extend: {
      colors:       flat(tokens.color),
      spacing:      flat(tokens.spacing),
      borderRadius: flat(tokens.radius),
      boxShadow:    flat(tokens.shadow),
      screens:      flat(tokens.breakpoint),
      fontFamily:   { headline: tokens.typography["font-family"].headline.value.split(", "), body: tokens.typography["font-family"].body.value.split(", ") }
    }
  }
};
```

Alias-Resolution für Tailwind vorab per Script (oder via [Style Dictionary](https://amzn.github.io/style-dictionary/)) machen, Tailwind kann keine `{…}`-Pfade auflösen.

## CSS-Custom-Properties

Für Projekte ohne Tailwind: Tokens in `:root` schreiben.

```css
:root {
  --color-brand-deep-sea: #18273A;
  --color-brand-teal:     #0D9488;
  --color-brand-gold:     #D4A853;
  --color-brand-cream:    #F8F6F2;
  --spacing-4:            16px;
  --radius-base:          8px;
  --duration-base:        250ms;
  --ease-out:             cubic-bezier(0.22, 1, 0.36, 1);
  /* … */
}
```

Ein Mini-Skript, das `tokens.json` → `tokens.css` konvertiert, liegt im Bundle unter `_lib/designsystem/tokens/_build_css.py`. Aufruf aus diesem Ordner:

```bash
python _build_css.py
```

Output ist `tokens.css` im selben Ordner. OKLCH ist primär, HEX-Werte landen automatisch im `@supports not (color: oklch(0% 0 0))`-Fallback-Block. Aliase (`{color.brand.teal}`) werden als `var(--color-brand-teal)` ausgegeben, sodass moderne Browser den OKLCH-Wert sehen und Fallback-Browser den HEX-Wert.

## Haupt-Kategorien im Überblick

| Kategorie | Enthält |
|---|---|
| `color.brand` | Deep Sea, Ocean, Warm Teal, Gold, Cream |
| `color.neutral` | 50–900 Graustufen, 50–700 warm getintet (Hue ≈ 65–80°), 800–900 Bridge-Stufen in Brand-Hue (Hue ≈ 244°) |
| `color.semantic` | success, warning, danger, info (Ampel, gemappt auf Brand) |
| `color.text`, `color.surface`, `color.border` | Rollen-basierte Aliase |
| `color.gradient` | Teal-Gold-Verlauf, Fade-Varianten |
| `typography` | font-family, font-weight, font-size, line-height, letter-spacing, text-style-Presets |
| `spacing` | 4-px-Raster von 0 bis 160 |
| `radius` | none bis full (Pill) |
| `shadow` | sm bis xl + inset-focus |
| `motion` | duration, delay, easing, reduced-motion |
| `breakpoint` | Tailwind-Standard sm/md/lg/xl/2xl |
| `container` | Max-Breiten inkl. „reading" (720 px) |
| `grid` | 12-Spalten, Gap |
| `icon` | Size-Skala + Stroke-Width 1.5 (Lucide-Default) |
| `component` | Defaults für Button, Card, Input, Tag, Divider |
| `focus-ring` | 2 px Teal, Offset 2 px |

## Neutralstufen — Hue-Bridge bei 700 → 800

Die Stufen `neutral.50` bis `neutral.700` sind warm getintet (OKLCH-Hue ca. 65–80°, abgeleitet aus Cream und Deep-Sea-Wärme). Die Stufen `neutral.800` und `neutral.900` springen bewusst auf Hue ≈ 244° und sind damit Bridge-Werte zur Brand-Identität — `neutral.900` ist als Alias auf `brand.deep-sea` gesetzt, `neutral.800` führt einen Hauch heller in dieselbe Richtung. Der Hue-Sprung zwischen Stufe 700 und 800 ist im Strip-Vergleich sichtbar, in der Praxis (Text auf Hintergrund, Border-Auftritt) fällt er nicht auf, weil 800/900 fast ausschließlich als dunkelste Anker eingesetzt werden, nicht als nächste Graustufe in einer Skala.

Wer eine durchgehend warm getintete dunkle Stufe braucht, nutzt `neutral.700`. Wer Brand-Bezug will, nutzt `neutral.900` bzw. `brand.deep-sea`. Beide nebeneinander sind kein Bug, sondern beabsichtigte Bridge.

## Versionierung

- `$meta.version` folgt [SemVer](https://semver.org/): Major bei Breaking (Farbwerte geändert, Token umbenannt), Minor bei Additiven (neuer Token, neue Kategorie), Patch bei Tippfehlern und Descriptions.
- Bei Änderung in den Tokens: `tokens.json` per Build-Script nachziehen und `$meta.date` + `$meta.version` aktualisieren.

## Sync-Regel im Bundle

Diese tokens.json ist die Default-Palette des Bundles. Anwender mit eigener Marken-Palette pflegen ihre Palette in ihrem eigenen Vault- oder Projektordner und übergeben den Pfad an konsumierende Skills per Skill-Config. Bundle-interne Updates der Default-Palette erfolgen über neue Bundle-Releases.

## Do's und Don'ts

**Do:**

- Aliase verwenden (`{color.brand.teal}`) statt Werte duplizieren.
- Neue Tokens nur hinzufügen, wenn sie in mindestens einem Design-Entscheidungs-Dokument belegt sind.
- Bei Komponenten-Defaults (`component.button.primary` etc.) nur solche Werte abbilden, die im Designsystem definiert sind.

**Don't:**

- Keine Magic Numbers ohne Token-Entsprechung in Code (`padding: 17px` verboten, muss aus Spacing-Skala kommen).
- Keine doppelten Token-Pfade (Alias vs. Literal) für denselben Wert. Entscheiden und einen wählen.
- Keine Farben außerhalb der Palette ergänzen, nur weil ein spezielles UI es verlangt. Stattdessen Palette begründet erweitern, dann JSON nachziehen.

## Verknüpfungen

- `_lib/designsystem/render.py` — CLI-Entry-Point, der diese Tokens via compose.py / compose_v.py konsumiert
- `_lib/designsystem/tokens/tokens.css` — generiertes CSS-Variablen-Pendant
- `_lib/designsystem/tokens/_build_css.py` — Build-Skript
