DESIGN.md: Googles offener Standard für KI-Coding-Agenten

TL;DR: DESIGN.md ist eine Format-Spezifikation von Google Labs, die eine visuelle Identität für KI-Coding-Agenten maschinenlesbar beschreibt. Das Format kombiniert zwei Schichten in einer Datei: maschinenlesbare Design-Tokens im YAML-Frontmatter (die exakten Werte) und menschenlesbare Begründung im Markdown-Body (das Warum). Ursprünglich war es das interne Format von Google Stitch, seit April 2026 ist es unter Apache-2.0 quelloffen und zählt rund 23.000 GitHub-Stars. Mitgeliefert wird ein npm-CLI mit lint, diff und export (Tailwind v3/v4, W3C DTCG) inklusive WCAG-AA-Kontrastprüfung. Der Status ist Alpha (v0.3.0): Dark Mode, Animationen und Responsive Breakpoints fehlen noch.

Was ist DESIGN.md?

DESIGN.md löst ein konkretes Problem: KI-Coding-Agenten schreiben funktionierenden Code, aber das visuelle Ergebnis ist oft inkonsistent. Wie es im offiziellen Erklärvideo von Google Labs heißt, ist DESIGN.md „a text file that describes a visual identity and gives agents a persistent and structured understanding of a design system“. Statt einer flüchtigen Prompt-Anweisung bekommt der Agent ein festes, strukturiertes Referenzdokument. Der Vergleich liegt nahe: DESIGN.md verhält sich zu visuellem Design wie CLAUDE.md oder AGENTS.md zum Verhalten eines Agenten. Es ist die Design-Schicht in der entstehenden Familie der Agent-Instruktionsdateien.

Zwei Schichten: Tokens und Prosa

Das Kernkonzept sind zwei klar getrennte Schichten in derselben Datei. Im YAML-Frontmatter stehen die Design-Tokens: die normativen Werte wie Hex-Codes, Schriftgrößen oder Radien. Im Markdown-Body darunter steht die Design-Rationale: warum diese Werte existieren und wie sie anzuwenden sind. Die Spezifikation bringt es auf den Punkt: „The tokens are the normative values. The prose provides context for how to apply them.“ Genau hier liegt der entscheidende Takeaway. Ein häufiges Missverständnis ist, dass die Tokens bloße Variablen sind. Tatsächlich kodieren sie Rollen und Entscheidungen: primary ist nicht einfach „eine Farbe“, sondern die definierte Rolle für die Haupt-Tinte einer Marke. Bislang drifteten Config-Dateien wie tailwind.config.js und menschliche Styleguides als PDF oder Figma-Datei auseinander. DESIGN.md führt beides in einer Quelle zusammen.

Woher DESIGN.md kommt

DESIGN.md entstand als Referenzimplementierung für Google Stitch, Googles KI-gestütztes Tool zur UI-Generierung (vergleichbar mit Vercels v0.dev). Stitch nutzte das Format intern, um Design-Regeln zwischen Projekten zu exportieren und importieren. Im April 2026 hat Google das Format unter google-labs-code/design.md quelloffen gemacht. Der Hebel ist klar: Google versucht, einen plattformübergreifenden Standard zu setzen, bevor es jemand anders tut. Wie du Stitch praktisch mit deinem Coding-Workflow verbindest, zeigt der Guide zu Google Stitch mit Claude Code.

Wie ist eine DESIGN.md aufgebaut?

Das Token-System kennt vier primäre Typen: Color (CSS-Farben als hex, rgb, oklch oder benannt), Dimension (Maßeinheiten wie px, rem, em), Typography (Schrift-Objekte) und Token Reference (Verweise auf andere Tokens, etwa {colors.primary}). Das System ist explizit vom W3C Design Token Format inspiriert, wodurch sich Tokens leicht zu tokens.json, Figma-Variablen und Tailwind-Configs konvertieren lassen. Die acht kanonischen Abschnitte Der Markdown-Body folgt einer kanonischen Reihenfolge von acht Abschnitten: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components und Do's and Don'ts. Diese Struktur ist bewusst offen gehalten – sie liefert ein gemeinsames Vokabular, Design-Systeme dürfen aber eigene domänenspezifische Abschnitte ergänzen. Besonders der Bereich Components ist mächtig: Hier werden UI-Elemente über Sub-Token-Properties wie backgroundColor, textColor, typography, rounded, padding, size, height und width definiert. Varianten für Zustände wie hover oder active werden als eigene Komponenten-Einträge mit verknüpftem Schlüssel angelegt. Minimal-Beispiel So sieht eine reduzierte DESIGN.md aus. Zuerst die Tokens im Frontmatter: Darunter folgt die Prosa, die dem Agenten die Absicht erklärt:

Welche CLI-Werkzeuge bringt DESIGN.md mit?

Google liefert ein offizielles npm-Paket (@google/design.md) mit drei zentralen Befehlen. Das ist das eigentliche Alleinstellungsmerkmal gegenüber reiner Dokumentation, denn hier wird Design verifizierbar. Der lint-Befehl prüft strukturelle Korrektheit, findet kaputte und verwaiste Token-Referenzen und warnt, wenn der Kontrast von Text zu Hintergrund den WCAG-AA-Mindestwert von 4,5:1 unterschreitet. diff gibt Token-Änderungen als strukturiertes JSON aus und macht Design-Systeme damit versionierbar und im Code-Review überprüfbar. export wandelt die Tokens in ein Tailwind-v3-Config-Objekt (JSON), einen Tailwind-v4-Theme-Block (CSS Custom Properties) oder das W3C-DTCG-Format um.

Die drei Ebenen: AGENTS.md, SKILL.md und DESIGN.md

DESIGN.md ist Teil einer größeren Bewegung, die Agent-Instruktionen in drei nicht überlappende Schichten aufteilt. Früher landete alles unstrukturiert in einer einzigen Markdown-Datei, in der formal prüfbare Regeln (Farben) und subjektive Regeln (Tonalität) vermischt wurden. • AGENTS.md – Verhalten: Rollen, Verbote und genereller Kontext eines Agenten. Fast reiner Fließtext, weil hier Nuance gefragt ist. Mehr dazu im Guide zu Claude Managed Agents. • SKILL.md – Aufgaben: wiederverwendbare Prozeduren und Domänenwissen, ebenfalls mit YAML-Kopf und Markdown-Body. Wie das praktisch aussieht, zeigt der Beitrag zu Claude Skills 2.0. • DESIGN.md – Erscheinungsbild: ausschließlich das visuelle Design-System. Die drei sind komplementär, nicht konkurrierend. Wer bereits Spec-Driven Development betreibt, kann DESIGN.md-Tokens direkt aus den Feature-Specs referenzieren und vermeidet doppelt gepflegte Regeln.

DESIGN.md vs. Tailwind, Figma und W3C DTCG

DESIGN.md tritt nicht als Ersatz an, sondern setzt auf Interoperabilität. Die Einordnung gegenüber den etablierten Ansätzen: | Ansatz | Stärke | Schwäche | |--------|--------|----------| | DESIGN.md | Ein Format für Agent, Mensch und CI; WCAG-Check | Alpha, unvollständig, Google-getrieben | | tailwind.config.js | De-facto-Standard, CI-integrierbar | Kein „Warum“, reine Werte ohne Prosa | | Figma Tokens | Visuell, Echtzeit, im Designer-Workflow | Nur in Figma, nicht Agent-first | | W3C DTCG | Echter Standard, tool-agnostisch | JSON-only, keine Begründung | Der Mehrwert von DESIGN.md ist die Design-Rationale als Prosa zusätzlich zu den Werten – plus das WCAG-Kontrast-Checking im Linter, das die anderen Formate so nicht mitbringen.

Wo DESIGN.md an Grenzen stößt

Bei aller Dynamik: Das Format ist Alpha (v0.3.0), und die Spezifikation kann sich noch ändern. Drei Einschränkungen solltest du kennen. Lücken im Schema: Dark Mode, Animationen und Responsive Breakpoints sind noch nicht abgedeckt. Für komplexe Sprachsysteme reicht die Spezifikation allein ebenfalls nicht: Japanische Oberflächen brauchen CJK-Font-Fallbacks und Zeilenumbruchregeln (Kinsoku Shori), die erst über lokalisierte Community-Erweiterungen abgebildet werden. Grenzen der Automatisierung: DESIGN.md prüft nur formal verifizierbare Regeln wie Kontraste. Ermessensbasierte Qualitäten – Tonalität, kulturelle Nuance, „wie eröffne ich einen Artikel mit Empathie“ – lassen sich nicht als strikte Spezifikation fassen und bleiben besser in einer AGENTS.md. Grundsätzliche Skepsis: Auf Hacker News gibt es deutliche Gegenstimmen. Ein Entwickler bringt seinen Einwand so auf den Punkt: „everything I see defined here in DESIGN.md is already codified in my actual themes configs, or component files“. Ein anderer warnt, starre Design-Dokumente bremsten mehr, als sie nützten: „trying to codify design rigidly and prescriptively in docs is going to slow you down more than it's worth“. Der Kern dieser Kritik ist nicht trivial: Ein DESIGN.md, das nicht zum tatsächlichen Produkt passt, ist schlimmer als gar keins, weil der Agent dann falsche Annahmen trifft.

FAQ: Häufig gestellte Fragen zu DESIGN.md

Was ist DESIGN.md genau? Eine Format-Spezifikation von Google Labs, die ein Design-System für KI-Coding-Agenten maschinenlesbar beschreibt. Sie kombiniert Design-Tokens im YAML-Frontmatter mit einer menschenlesbaren Begründung im Markdown-Body. Ist DESIGN.md kostenlos und Open Source? Ja. Das Repository google-labs-code/design.md steht unter Apache-2.0-Lizenz und zählt rund 23.000 GitHub-Stars. Das CLI installierst du per npx @google/design.md. Ersetzt DESIGN.md meine tailwind.config.js? Nein. DESIGN.md ist auf Interoperabilität ausgelegt und kann per export direkt eine Tailwind-Config (v3 oder v4) erzeugen. Es ergänzt bestehende Token-Formate um die Design-Begründung, statt sie zu verdrängen. Was ist der Unterschied zu AGENTS.md und SKILL.md? Die drei bilden eine arbeitsteilige Familie: AGENTS.md regelt das Verhalten des Agenten, SKILL.md beschreibt wiederverwendbare Aufgaben, DESIGN.md definiert das Erscheinungsbild. Sie sind komplementär, nicht konkurrierend. Kann DESIGN.md Barrierefreiheit prüfen? Teilweise. Der mitgelieferte Linter warnt, wenn das Kontrastverhältnis von Text zu Hintergrund den WCAG-AA-Mindestwert von 4,5:1 unterschreitet. Das ist eines der echten Alleinstellungsmerkmale gegenüber reinen Token-Dateien. Sollte ich DESIGN.md jetzt schon einsetzen? Für Prototyping und konsistente UI-Generierung mit Coding-Agenten lohnt sich ein Test bereits. Wer Dark Mode, Animationen oder Responsive Breakpoints zwingend braucht, sollte den Alpha-Status (v0.3.0) im Blick behalten – diese Bereiche fehlen noch.

Fazit

DESIGN.md ist der ernsthafteste Versuch, Coding-Agenten ein konsistentes visuelles Gedächtnis zu geben: Tokens für die exakten Werte, Prosa für die Absicht, ein Linter mit WCAG-Check für die Verifikation. Der Alpha-Status und fehlende Bereiche wie Dark Mode sind reale Einschränkungen, und die Skepsis, dass Design-Dokumente veralten, ist berechtigt. Trotzdem lohnt sich der Einstieg – gerade wenn du ohnehin mit Tailwind und KI-Agenten arbeitest. Vertiefen kannst du das Thema mit dem Guide zu Google Stitch und Claude Code, dem Überblick zu Spec-Driven Development sowie den Beiträgen zu Claude Skills 2.0 und Claude Managed Agents. Verifizierte Quellen: google-labs-code/design.md (GitHub), Google Labs Erklärvideo zu DESIGN.md, npm-Paket @google/design.md, W3C Design Tokens Community Group Format.