Design Tokens, DESIGN.md und Design to Code

KI-Coding-Agenten schreiben funktionierenden Code, aber die UI, die sie erzeugen, sieht generisch aus. Jede generierte App sieht aus, als wäre sie mit denselben Standardkomponenten gebaut, weil sie es ist. Der Agent hat keinen Anker für deine Marke. Sag ihm "erstelle einen Secondary Button" und er erfindet eine Farbe. Sag ihm "mach die App dark mode" und er inspiziert jede Komponente und rät, welche Farben er ersetzen muss.

Die andere Hälfte des Problems ist Fidelity. Du entwirfst etwas in einem Designtool, übergibst es, und der Code, der zurückkommt, passt nicht. Die Abstände stimmen nicht, die Farben sind ungefähr, aber nicht richtig, die Typografie-Skala ist weg. Das Design hatte Struktur, aber der Handoff hat sie verloren.

Das sind die Probleme, die eine ganze Reihe von Tools und Formaten gerade lösen will. Der gemeinsame Nenner sind Design Tokens, und das Format, das sie zu AI-Agenten trägt, heißt DESIGN.md. Dieser Post ist, was ich gelernt habe, als ich versucht habe zu verstehen, wie die Teile zusammenpassen.

Tokens tragen Bedeutung, nicht nur Werte

Ein Design Token ist ein benannter Wert. Statt #2563EB auf einem Button zu speichern, speicherst du color.primary. Statt 8px auf einer Ecke speicherst du radius.md.

Der Unterschied ist die Intention. Wenn jemand, oder etwas, sich einen rohen Wert ansieht, sieht es nur den Wert. Ein blaues Rechteck mit 8px-Ecken. Es muss raten: Ist das der Primary Button? Wird dieses Blau woanders verwendet? Ist 8px eine bewusste Entscheidung oder eine Zahl, die jemand eingetippt hat?

Mit einem Token ist die Intention lesbar. color.primary sagt, wofür die Farbe ist. radius.md sagt, das ist Teil einer Skala, keine beliebige Zahl. Ein Entwickler, der das liest, muss nicht raten. Ein AI-Agent, der das liest, muss nicht raten.

Derselbe Token, color.primary, wird zu --color-primary in CSS, Color.primary auf iOS, theme.colors.primary in Tailwind. Eine Entscheidung, ausgedrückt in der Sprache jeder Plattform. Das meinen Leute, wenn sie Design Tokens eine Single Source of Truth nennen.

Ein Design System ist die ganze Struktur. Tokens sind die Variablen darin. Die Beziehung sieht so aus:

Design System
│
├── Foundations
│   │
│   ├── Tokens
│   │   ├── Colors
│   │   ├── Typography
│   │   └── Spacing
│   │
│   └── Themes
│       ├── Light
│       └── Dark
│
├── Components
│   ├── Button
│   ├── Card
│   └── Input
│
└── Documentation
    ├── Usage rules
    └── Examples

Es ist erwähnenswert, dass Light und Dark nicht das Design System selbst sind. Sie sind Themes darin. Tokens sind die Variablen, die Themes wechseln lassen. Komponenten konsumieren die Tokens. Das Design System ist das Ganze.

Ein Token ist nicht zum Zeichnen da

Hier hatte ich es falsch herum. Ich dachte, Tokens gingen darum, das Designtool die Dinge richtig zeichnen zu lassen. Tun sie nicht. Tokens gehen darum, die Entscheidungen hinter dem, was gezeichnet wird, zu beschreiben.

Ein Button in einem Designtool ist immer noch ein Rechteck und Text. Mit Tokens speichert das Rechteck nicht #2563EB. Es speichert eine Referenz: fill → color.primary. Die Geometrie ist dieselbe. Was sich geändert hat, ist, dass die Designdatei jetzt den Grund trägt, nicht nur das Ergebnis.

Eine Komponente bindet nicht an einen rohen Wert. Sie bindet an einen semantischen Token, der auf ein Primitiv zeigt. Ändere das Primitiv, und alles folgt nachgelagert. Das ist der ganze Sinn der Hierarchie. Eine Änderung oben propagiert überall.

Das zählt, wenn das Design in Code übergeht. Ohne Tokens reverse-engineert der Codegenerator Pixel. Er sieht ein blaues Rechteck und schreibt background: #2563EB. Mit Tokens liest er color.primary und schreibt background: var(--color-primary). Der generierte Code sieht aus wie etwas, das ein Entwickler schreiben würde, nicht ein Pixel-Dump.

Tokens reichen nicht

Eine JSON-Datei voller Tokens sagt dir die Werte. Sie sagt dir nicht, warum diese Werte existieren, wann man sie verwenden soll und wann nicht. Man kann "verwende primary nur für den Haupt-CTA" nicht in einer tokens.json-Datei ausdrücken.

Das ist die Lücke, die DESIGN.md füllt. Es kam aus Google Stitch, Googles AI-Designtool, und wurde im April 2026 open-sourced unter Apache 2.0. Der Pitch ist eine Datei, an der Wurzel deines Projekts, die einem AI-Agenten ein dauerhaftes Verständnis deines Design Systems gibt.

Eine DESIGN.md-Datei hat zwei Schichten. Oben ist YAML-Frontmatter: deine Tokens, geschrieben als strukturierte Werte. Farben, Typografie, Abstände, abgerundete Ecken, Komponenten. Darunter ist Markdown-Prosa, die erklärt, wofür die Tokens sind und wie man sie anwendet.

Die Tokens geben einem Agenten exakte Werte. Die Prosa sagt ihm, warum diese Werte existieren.

Eine Button-Komponente in DESIGN.md sieht so aus:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px

Die {colors.tertiary}-Referenzsyntax kommt aus dem W3C Design Tokens Format Module. Ändere colors.tertiary einmal, und der Button aktualisiert sich überall, wo er referenziert wird. Derselbe Standard, den Designtools wie Penpot nativ verwenden.

Acht Sektionen

Eine DESIGN.md hat acht Sektionen, in einer festen Reihenfolge:

1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

Die Do's-and-Don'ts-Sektion ist, wo die Prosa ihren Wert beweist. "Nie Drop Shadows auf Cards verwenden." "Immer Sentence Case für Button-Labels verwenden." Das sind Constraints, die reine Tokens nicht ausdrücken können. Eine JSON-Token-Datei sagt, was die Werte sind. DESIGN.md sagt, was man mit ihnen tun soll und was man vermeiden sollte.

Warum es sich durchgesetzt hat

Es liegt im Repo-Root neben README.md und CLAUDE.md / AGENTS.md. Agenten lesen bereits Markdown aus dem Projekt-Root. README.md erklärt das Projekt Menschen. CLAUDE.md und AGENTS.md sagen Agenten, wie sie sich verhalten sollen. DESIGN.md sagt ihnen, wie die UI aussehen soll.

Das awesome-design-md-Repo auf GitHub, eine Sammlung fertiger DESIGN.md-Dateien, extrahiert aus echten Produktions-Sites, überschritt 58.000 Stars innerhalb Wochen nach dem Launch. Eine Fork-Rate von 12,6 %, was bedeutet, dass etwa 1 von 8 Leuten, die es fanden, eine Datei in ihr eigenes Projekt kopiert hat. Das ist kein Bookmarking. Das ist Adoption.

Man muss nicht von null anfangen. Es gibt Kataloge. getdesign.md hat über 300 DESIGN.md-Analysen von echten Produktions-Sites. Open Design liefert 151 Design-System-Pakete. designmd.app indiziert 461. Man wählt eines, das nah an der eigenen Marke ist, und passt es an.

Die Spec ist noch alpha. Farbwerte sind nur sRGB. Wide-Gamut-Formate wie Oklch und Display P3, beide vom W3C-Standard unterstützt, sind noch nicht in DESIGN.md. Das CLI kann nach Tailwind v3/v4 und ins W3C-DTCG-Format exportieren, sodass die Tokens in die bestehende Pipeline fließen.

Wo Designtools passen

DESIGN.md ist die Source of Truth. Designtools sind, wo du die Tokens anwendest, um Screens zu machen. Penpot und Figma sind zwei Beispiele, und es gibt andere. Sie nehmen unterschiedliche Ansätze für dasselbe Konzept.

Penpot ist das erste Designtool, das das W3C Design Tokens Format Module nativ integriert. Derselbe Standard, von dem DESIGN.md's Token-Referenzen inspiriert sind. In Penpot leben Tokens in Sets, also Sammlungen verwandter Tokens. Deine Foundations gehen in ein Set: Basisfarben, Abstandswerte, Radien. Deine semantischen Tokens gehen in ein anderes: primary, success, error. Du kombinierst Sets zu Themes für verschiedene Kontexte. Light ist ein Theme. Dark ist ein Theme. Light und Dark sind keine verschiedenen Design Systems, sie sind verschiedene Themes, angewendet auf dieselben Token-Namen.

Weil Penpot nativ das W3C-Format spricht, exportieren deine Tokens im Standardformat. Keine Übersetzungsschicht.

Figma nimmt einen anderen Ansatz. Figma Variables sind Figmas native Implementierung des Token-Konzepts. Figma verwendet Collections, wo Penpot Sets verwendet, und Modes, wo Penpot Themes verwendet. Eine Figma-Collection enthält verwandte Variablen, und Modes speichern parallele Werte für verschiedene Kontexte. Aliasing baut die Primitiv- zu Semantisch- zu Komponenten-Hierarchie: ein semantischer Token wie text-primary zeigt auf ein Primitiv wie gray-900, und das Ändern des Primitivs aktualisiert alles nachgelagert.

Der Unterschied ist, dass Figmas Variablen ein proprietäres Format verwenden. Um Tokens aus Figma im W3C-Standardformat herauszubekommen, braucht man Plugins wie Tokens Studio. Penpot exportiert W3C nativ. Beide implementieren dasselbe Konzept. Einer spricht den Standard, einer spricht seinen eigenen Dialekt.

Der Punkt ist nicht, welches Tool man verwendet. Der Punkt ist, dass die Tokens, wie auch immer das Tool sie speichert, auf dieselbe Source of Truth zurückgeführt werden sollten: dein Design System, kodiert in DESIGN.md.

Design to Code

Hier verbinden sich die Teile.

Der alte Handoff war: in einem Tool designen, eine Datei exportieren, einem Entwickler übergeben, hoffen, dass er die Spec richtig liest. Der Entwickler reverse-engineered das Design aus Pixeln und rät zur Intention.

Der neue Handoff ist: kodiere dein Design System in DESIGN.md. Designe in einem Tool mit den Tokens. Dein AI-Agent liest die DESIGN.md und generiert Produktionscode, der dieselben Token-Namen verwendet.

Design system → DESIGN.md → AI agent → production code

Der Agent bekommt die exakten Werte aus den YAML-Tokens. Er bekommt die Regeln aus der Prosa. Er muss nicht raten, ob ein blaues Rechteck der Primary Button ist, weil die DESIGN.md sagt, dass button-primary colors.tertiary verwendet. Der generierte Code verwendet var(--color-tertiary), keinen hardcodierten Hex-Wert.

In der Praxis läuft der Flow in beide Richtungen. Ein neues Projekt beginnt mit den Tokens. Du definierst deine Tokens, schreibst die DESIGN.md und lässt deinen AI-Agenten die DESIGN.md aus dem Repo lesen. Der Agent lädt die Tokens dann über das CLI oder MCP ins Designtool. Penpot importiert das W3C-Format nativ. Figma braucht ein Plugin wie Tokens Studio. Das Designtool und der Agent lesen dieselbe Quelle.

Ein bestehendes Projekt geht in die andere Richtung. Du zerlegst das aktuelle Design in Tokens, standardisierst das Naming und schreibst eine DESIGN.md daraus. Dann lädst du diese Tokens ins Designtool. Wenn das Projekt überhaupt kein Design hat, nur Code, kann der AI-Agent die aktuelle Codebase lesen, das Frontend extrahieren und das Design ins Designtool verschieben. Von dort an teilen sich Designtool und Codebase dieselbe Quelle.

Die Verbindung zwischen Designtool und Agent läuft über MCP, oder über das CLI des Tools, falls es eines hat. pen.dev startet einen lokalen MCP-Server, über den sich beide Seiten verbinden.

pencil.dev (jetzt pen.dev)

pen.dev geht weiter, indem es das Designtool und den Code-Editor in eine Umgebung kollabiert. Es ist ein Design-Canvas, der innerhalb deiner IDE lebt, keine separate Anwendung. Design-Dateien (.pen) liegen im Repo neben deinem Code. Git trackt sie. Du branchst und merkst Designs genauso wie du Code branchst und merkst.

Wenn pen.dev läuft, startet es einen lokalen MCP-Server. Dein AI-Agent, ob Claude Code, Cursor, Codex oder OpenCode, verbindet sich über MCP und kann die Design-Dateien lesen und verändern. Variablen in pen.dev mappen auf CSS-Custom-Properties. Du designst visuell, der Agent generiert Code, und beide Seiten lesen dieselben Tokens.

Die Community hat Tools darum gebaut. Es gibt ein Claude-Code-Plugin namens pencil-atelier, das die visuelle Sprache einer .pen-Datei extrahiert und sie in eine design.md am Projekt-Root schreibt. Von da an liest jeder Design- und Code-Generierungsdurchlauf denselben Vertrag. Kein manuelles Neu-Briefing zwischen Sessions.

Was noch nicht gelöst ist

Atlassian hat DESIGN.md in Produktion getestet und festgestellt, dass es alles auf einmal lädt, nicht on Demand. Verglichen mit einem MCP-Server, der Kontext pro Komponente holt, verwendete DESIGN.md etwa 92 % mehr Tokens und hatte eine 2,7-fache Varianz zwischen Durchläufen. Es ist ein portabler Snapshot, kein Ersatz für eine vollständige Design-System-Pipeline. Die Spec ist alpha. Die Tools sind noch rau.

Was funktioniert, ist die Form. Du kodierst deine Design-Entscheidungen einmal, in einem Format, das sowohl Menschen als auch Agenten lesen können. Du designst in einem Tool, das dieselben Tokens verwendet. Dein Agent liest dieselbe Datei und generiert Code mit denselben Namen. Der Teil, der ersetzt wird, ist die Übersetzungsschicht, die früher eine Person mit einer Figma-Datei und einer Vermutung war.