Foundations: Design-Tokens — Invisible Minidocs

Farben, Größen, Typografie, Radien, Schatten, Ebenen, Motion — Tokens sind die unterste Schicht, weil ALLES auf ihnen steht: ändert sich ein Token, ändern sich alle Bausteine, alle Seiten, alle Kanäle gleichzeitig — ohne dass irgendjemand eine Definition oder Seite anfasst.

Warum drei Ebenen — und nicht einfach eine Farbliste?

Eine flache Variablenliste beantwortet nicht die Frage, was passieren darf. Die drei Ebenen trennen Wert, Bedeutung und lokale Stellschraube:

Ebene	Beispiel	Wer ändert sie?	Wer konsumiert sie?
1. Referenz `tokens.reference.json`	`palette.green.500 = #16895f`	Design-System-Pflege — selten. Volle Skalen, damit Ebene 2 immer einen passenden Wert findet.	NUR Ebene 2 und lokale Komponenten-Tokens.
2. Semantik `tokens.semantic.json`	`color.action.primary = {palette.green.500}`	Themes und Target-Schichten — sonst niemand. Die Begriffe selbst sind systemweit stabil.	Alle Bausteine, alle Kanäle — die gemeinsame Sprache.
3. Komponente im CSS der Definition	`--button-radius: var(--radius-control)`	Der Autor der Definition — und Kompositionen per Token-Override.	Nur die eigene Definition. Macht Varianten billig.

Aufloesungskette

Baustein-CSS:   border-radius: var(--button-radius)          (Ebene 3, lokal)
     └── --button-radius: var(--radius-control)   (zeigt auf Ebene 2)
              └── --radius-control: var(--radius-md)   ← HIER überschreiben Themes/Targets
                       └── --radius-md: 8px             (Ebene 1, roher Wert)

Themes und Target-Schicht — zwei Achsen, gleiche Mechanik

Theme ([data-theme="…"]) = WESSEN Marke: Branding, Dark/Light. Ein Theme ist eine kleine JSON-Datei mit Overrides — 1000 Kunden-Themes sind 1000 kleine Variablen-Blöcke, kein CSS-Rebuild der Bausteine.
Target-Schicht ([data-target="…"]) = WO es läuft: Dichte und Ergonomie pro Kanal. Sie gewinnt bei Konflikt über das Theme (Ergonomie schlägt Marke).

Beides kombiniert sich frei: acmes Portal (Theme) im Desktop (Target) bekommt acmes Farben in Desktop-Dichte — ohne dass irgendwo ein Sonderfall programmiert ist.

Wem gehören die Tokens? Die Eigentums-Hierarchie

Drei Eigentümer, dieselbe Sprache:

Stufe	Was
System-Semantik	Die BEGRIFFE (`color.action.primary`, `radius.overlay` …) — global, eine Wahrheit. Kein Projekt erfindet eigene Begriffe, sonst zerbricht die Austauschbarkeit der Bausteine. (`definitions/foundations/`)
Projekt-Theme	Die WERTE eines Projekts — seine Design-Identität, gern als Dark/Light-Paar. Darf eigene Roh-Werte mitbringen (das Docs-Theme bringt sein Navy mit, ohne die globale Palette anzufassen). (`definitions/themes/`)
Kunden-Theme	Eine ABGELEITETE Kopie pro Kunde: Kunde A stellt sein `color.action.primary` um, und NUR sein Portal kippt — Kunde B und das Projekt-Theme bleiben unberührt. (Die Vorlagen-Mechanik dazu gehört zum CMS-Produkt, das Eigentums-Modell gilt unabhängig davon.)

Der Token-Compiler: streng, damit nichts still kaputtgeht

build/tokens.mjs validiert die komplette Kette und bricht bei jedem Fehler ab: unbekannte Aliasse, Namens-Kollisionen, Overrides auf nicht existierende Begriffe. Ein Tippfehler im Token-Namen ist ein Build-Fehler — nie ein stiller Darstellungsfehler beim Kunden.

Artefakt	Zweck
`cache/tokens.css`	Die EINE Laufzeit-Wahrheit auf jeder Seite: Basis-Schicht + alle Variablen + [data-theme]- und [data-target]-Blöcke
`cache/tokens.tailwind.css`	@theme-Mapping für den Bausteine-Build — Utilities bleiben Token-treu, Themes wirken zur Laufzeit
`cache/tokens.json`	Modell für PHP: Token-Browser, Token-Validierung

Der Render-Cache publizierter Seiten enthält den Token-Build-Stand im Cache-Key — ein Token-Update invalidiert automatisch alle betroffenen Seiten.

Regeln (Definition of Done für Token-Arbeit)

✔ Bausteine konsumieren semantische Tokens (direkt oder über Ebene 3) — nie Roh-Werte, nie Palette für Bedeutungs-Entscheidungen
✔ Themes/Targets überschreiben NUR Ebene 2 — nie Referenz-Werte, nie Komponenten-Tokens fremder Bausteine
✔ Neue Begriffe (Ebene 2) sind eine Systementscheidung — selten, bewusst, mit Namenskonvention gruppe.kontext.rolle
✔ Projekt-Farbwelten kommen als Theme mit Roh-Werten, NICHT als neue Palette-Einträge
⚠ Einzige dokumentierte Ausnahme: breakpoint.*-Tokens werden über Tailwind-Varianten konsumiert — CSS erlaubt kein var() in Media Queries (→ Responsive)

Werkzeug: Token-Browser. Gepflegt werden Tokens in den JSON-Quellen unter definitions/foundations/ + definitions/themes/.