Was ist design.md für Coding-Agenten?

Ich bin Dora. Letzte Woche habe ich Claude Code gebeten, einem Nebenprojekt drei neue Screens hinzuzufügen. Beim zweiten Screen hatte sich der Button-Radius verschoben, die Überschriftenschrift hatte sich still verändert, und das „sekundäre” Grau war ein anderes Grau. Gleiche Prompt-Struktur. Gleiches Modell. Gleiche Session. Der Output hörte einfach auf, sich darum zu kümmern, was vorher war.

Das ist die Reibung, die design.md für Coding-Agents zu beseitigen versucht. Es ist eine einfache Markdown-Datei, die dein Design-System in einer Form enthält, die ein KI-Agent bei jeder UI-Generierung lesen kann – nicht als einmaliger Prompt, sondern als persistenter Kontext. Stitch liest sie. Claude Code liest sie. Cursor liest sie. Alles andere, das Kontextdateien aus einem Repo-Root aufnimmt, liest sie ebenfalls.

Was design.md ist und warum Google Labs es veröffentlicht hat

Dateiformat und Design-System-Rolle

Eine DESIGN.md-Datei besteht aus zwei Schichten, die in einem Dokument gestapelt sind. Oben befindet sich YAML-Frontmatter – Farben, Typografie, Abstände, abgerundete Ecken, Komponenten – als strukturierte Tokens geschrieben. Darunter befinden sich Markdown-Prosa, die erklärt, wofür die Tokens da sind und wie man sie verwendet. Die Tokens geben einem Agent exakte Werte. Die Prosa erklärt, warum diese Werte existieren.

So sieht das Frontmatter ungefähr aus, entnommen aus der offiziellen DESIGN.md-Spezifikation auf GitHub:

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

Darunter folgen ## Übersicht, ## Farben, ## Typografie in einfachem Markdown. Die Abschnittsreihenfolge ist festgelegt – Übersicht, Farben, Typografie, Layout, Elevation & Tiefe, Formen, Komponenten, Dos and Don’ts. Abschnitte können übersprungen werden, aber die vorhandenen müssen in dieser Reihenfolge erscheinen. Doppelte Abschnittsüberschriften sind ein Fehler und lehnen die Datei ab.

Die Token-Referenzsyntax stammt aus dem W3C Design Tokens Format Module – geschweifte-Klammer-Pfade wie {colors.primary}. Referenzen müssen auf primitive Werte zeigen (keine Gruppen), außer im Komponenten-Abschnitt, wo zusammengesetzte Verweise auf Typografie-Tokens erlaubt sind. Farbwerte sind im aktuellen Spec nur SRGB-Hex. Display P3 und Oklch – beide vom W3C DTCG 2025.10 Stable Spec unterstützt – werden von DESIGN.md noch nicht unterstützt, was das Repo offen mit seinem version: alpha-Marker kennzeichnet. Wissenswert, wenn du Wide-Gamut-Tokens pflegst.

Das Format wird mit einer CLI ausgeliefert – @google/design.md auf npm. npx @google/design.md lint führt sieben Regeln gegen eine geparste Datei aus. Die zwei, auf die ich am häufigsten stoße: broken-ref (Fehler-Schweregrad) fängt Token-Referenzen ab, die nicht aufgelöst werden, und contrast-ratio (Warnung) prüft Komponenten-backgroundColor/textColor-Paare gegen das 4,5:1-Minimum von WCAG AA. Drei weitere – missing-primary, orphaned-tokens und die strukturellen Regeln – decken Probleme auf, die die meisten Teams innerhalb einer Woche nach der Bearbeitung der Datei einführen. Die CLI hat auch diff (Token-Level-Regressionen zwischen Versionen) und export (Tailwind v3 Config, Tailwind v4 @theme CSS oder W3C DTCG JSON).

Warum persistenter visueller Kontext für Coding-Agents wichtig ist

Das Problem ist simpel. Ein Agent, der UI generiert, hat keine Erinnerung an dein Design-System, es sei denn, du gibst ihm etwas Strukturiertes zum Lesen. Du kannst deine Palette in einem Prompt beschreiben, einen Button zurückbekommen, dann nach einer Karte fragen und zusehen, wie die Abstandslogik zurückgesetzt wird. Das Modell ist nicht schlecht darin, Code zu schreiben. Es hat keinen Anker.

design.md ist der Anker. Stitch übergibt sie bei jeder Generierungsanfrage als Kontext. Claude Code und Cursor nehmen sie auf die gleiche Weise auf, wie sie CLAUDE.md oder AGENTS.md aufnehmen – eine Datei im Repo-Root, die der Agent liest, bevor er antwortet. Googles Aussage in der Open-Source-Ankündigung ist, dass dies Agents erlaubt, „genau zu wissen, wofür eine Farbe ist”, anstatt Absichten aus einem Prompt zu erraten.

Ich habe dies an beiden Projekten getestet. Vorgehen: DESIGN.md in das Root-Verzeichnis legen, dieselben fünf Screens neu generieren, die vorher gedriftet waren (Landing, Pricing, Anmeldung, Dashboard, Einstellungen), dann Token-Verletzungen gegen das Frontmatter zählen. Mit der vorhandenen Datei produzierte Claude Code 5/5 Screens mit den exakten primären und tertiären Hex-Werten und dem deklarierten rounded.sm. Cursor produzierte 4/5 – das Dashboard überschrieb weiterhin rounded.sm (4px) mit rounded.md (8px) auf Karten, was die DESIGN.md-Prosa nicht explizit verboten hatte. Das Hinzufügen einer „Dos and Don’ts”-Zeile – „Kartenecken verwenden rounded.sm, niemals rounded.md” – behob dies beim nächsten Regenerieren.

Das eigentliche Problem, das es bei der KI-UI-Generierung löst

Konsistenz über Screens und Iterationen hinweg

Was in der früheren Session nicht funktionierte, war nicht die Qualität eines einzelnen Screens. Jeder einzelne Screen sah gut aus. Screen zwei wusste nicht, was Screen eins entschieden hatte. Jede Generierung startete mit einer leicht unterschiedlichen Interpretation von „deiner Marke”.

Das ist der Fehlermodus, auf den design.md abzielt. Nicht „die UI schöner machen” – sie zur gleichen UI über Generierungen hinweg machen. Die Tokens sind normativ. Wenn das Frontmatter tertiary: "#B8422E" sagt, hat der Agent keinen Spielraum, es als „ein warmes Orange” zu interpretieren. Es ist dieser Hex-Wert oder er ist falsch, und lint wird das sagen.

Für hochfrequente Workflows – fünf, zehn, zwanzig Screens pro Woche mit jemandem, der sie pflegt – ist dies wichtiger als die Erstausgabequalität. Eine Inkonsistenz pro Screen in der Größenordnung wird zu einem Bereinigungsjob. Coding-Agent-Design-Tokens, einmal in einer Datei definiert, beenden diesen Bereinigungsjob, bevor er beginnt.

Warum Prosa plus Tokens stärker ist als Tokens allein

Ich hätte diesen Teil fast abgetan. Warum Absätze schreiben über „Boston Clay ist der einzige Treiber für Interaktion”, wenn der Hex-Wert bereits im YAML steht?

Weil der Agent die Prosa verwendet, um Entscheidungen zu treffen, die die Tokens nicht abdecken. Die Tokens sagen, dass tertiary #B8422E ist. Die Prosa sagt, dass diese Farbe nur für Interaktion bestimmt ist – nicht für dekorative Akzente, nicht für Überschriften. Wenn ein Prompt mehrdeutig ist („füge ein Benachrichtigungs-Badge hinzu”), entscheidet die Prosa, ob das Badge die Interaktionsfarbe oder ein Neutralton bekommt. In meinem Cursor-Lauf oben war die fehlende Prosa-Einschränkung genau der Grund, warum das Dashboard abgedriftet ist.

Die gleiche Logik gilt für Dos and Don’ts – explizite Leitplanken wie „niemals Schlagschatten auf Karten verwenden” oder „immer Satzschreibweise für Button-Beschriftungen verwenden”. Negative Einschränkungen haben ein Gewicht, das reine Tokens nicht ausdrücken können. Das ist eine Design-Spezifikation für Agents, keine CSS-Datei.

Das Format ist nicht an Stitch gebunden. Die Spezifikation ist Apache 2.0, die CLI ist auf npm, der DTCG-Export bedeutet, dass Tokens in jedes Tool fließen, das den W3C-Standard liest, und die Community bewegt sich bereits. VoltAgents awesome-design-md-Sammlung von markeninspirierten DESIGN.md-Dateien überschritt innerhalb von Wochen nach dem Launch 71.000 GitHub-Sterne, und das design-md-GitHub-Topic listet jetzt Extraktionstools, Chrome-Erweiterungen und SKILL.md-Registries von außerhalb von Google vollständig auf. Die Übernahme ist das, was dir sagt, dass ein Format real ist.

Wer sich um design.md kümmern sollte

Um ehrlich über die Grenzen zu sein, denn design.md ist keine universelle Lösung.

Es verdient seinen Platz, wenn:

Du UI mit Coding-Agents mindestens wöchentlich generierst, über mehr als einen Screen hinaus
Du ein Design-System hast – auch ein dünnes –, das du über Generierungen hinweg erhalten möchtest
Du mit mehr als einem Agent oder Tool arbeitest und denselben Markenkontext in allen haben möchtest
Du es leid bist, „denk daran, unsere Palette ist X, Y, Z” in jeden Prompt einzufügen

Es verdient seinen Platz nicht, wenn:

Du einmalige Mockups generierst und sie verwirfst
Dein „Design-System” das ist, was der Agent diesmal produziert
Du dich in einem Figma-geführten Workflow mit einer ausgereiften DTCG-Pipeline über Style Dictionary oder ähnliches befindest – design.md ist leichter als das, was du hast, und du würdest ein Downgrade vornehmen
Du heute Wide-Gamut-Farben (Display P3, Oklch) benötigst – der aktuelle Alpha-Spec ist nur SRGB

Für KI-native Produktteams, die design.md neben anderen KI-Workflow-Dateien (CLAUDE.md, AGENTS.md) betreiben, fügt es sich sauber ein. Eine Markdown-Datei pro Anliegen. Kein Build-Schritt. Kein JSON-Schema zum Kämpfen. Die Kosten des Ausprobierens sind eine Datei im Repo-Root und ein Lint-Befehl.

Für Plattformen, die agent-gesteuerte Generierungsoberflächen aufbauen – einschließlich einheitlicher KI-Generierungsschichten, die Anfragen über mehrere Modelle routen und Markenkontext benötigen, der bei jedem Aufruf konsistent bleibt – ist design.md das Nächste, was das Ökosystem zu einem portablen Vertrag zwischen einer Marke und einem Agent hat. Laut der Google Labs-Ankündigung wurde das Format speziell entwickelt, um über Tools hinweg exportierbar und importierbar zu sein. Diese Portabilität ist der Punkt.

FAQ

Wofür wird design.md verwendet?

Es ist eine Markdown-Datei, die Coding-Agents persistenten Kontext über ein Design-System gibt – Farben, Typografie, Abstände, Komponenten sowie Prosa, die erklärt, wie man sie anwendet. Der Agent liest sie bei jeder UI-Generierung, sodass die Ausgabe über Screens und Sessions hinweg konsistent bleibt, ohne dass du in jedem Prompt Markenregeln neu spezifizieren musst.

Ist es nur für Google Stitch-Workflows?

Nein. Das Format entstand in Stitch, aber Google hat die Spezifikation unter Apache 2.0 als Open-Source veröffentlicht. Jedes KI-Tool, das Kontextdateien liest – Claude Code, Cursor, GitHub Copilot, Antigravity, Gemini CLI – kann es verwenden. Die CLI exportiert in Tailwind-Config, CSS-Variablen oder W3C DTCG JSON, sodass die Tokens auch in Nicht-Agent-Tooling fließen.

Warum benötigt KI-generierte UI eine Design-System-Datei?

Weil Modelle keine Erinnerung an deine Marke zwischen Generierungen haben. Ohne eine strukturierte KI-Design-System-Datei re-interpretiert jeder Prompt deine Designsprache von Grund auf. Mit einer wirken die Tokens als harte Einschränkungen, und die Prosa deckt Ermessensentscheidungen ab. Der Unterschied zeigt sich am deutlichsten im großen Maßstab – fünf mit design.md generierte Screens behalten ihren Stil; fünf ohne es generierte Screens driften.

Welche Teams sollten zuerst damit experimentieren?

Teams, die bereits wöchentlich UI mit Coding-Agents generieren. Einzelentwickler und kleine Produktteams, die Claude Code oder Cursor betreiben, erhalten den schnellsten Gewinn – Datei ablegen, neu generieren, die Konsistenz sehen. Größere Organisationen mit ausgereiften Figma + Style Dictionary-Pipelines sollten design.md als Ergänzung, nicht als Ersatz betrachten: es verwenden, um Agents eine verdauliche Teilmenge des bestehenden Systems zu geben.

Fazit

design.md ist kein revolutionäres Dateiformat. Es ist eine Markdown-Datei mit YAML oben. Das ist der Punkt – das Format, das LLMs am besten lesen, ist das, auf dem sie am meisten trainiert wurden, und das ist Klartext.

Was es tatsächlich tut, ist die Frage von „wie beschreibe ich mein Design in diesem Prompt” zu „wo lebt mein Design, damit jeder Agent es lesen kann” zu verschieben. Eine Datei, ein Ort, jedes Tool, das sie aufnimmt, bekommt dieselbe Antwort. Eine Sache weniger, die neu spezifiziert werden muss. Klingt klein. Summiert sich schnell.

Ich habe sie seit einer Woche in zwei Projekten. Es funktioniert. Langfristig – ob Teams diese Dateien mit der gleichen Sorgfalt wie ein echtes Design-System pflegen, oder ob sie verrotten wie READMEs verrotten – das ist noch zu verifizieren. Führe es auf einem eigenen Projekt aus. Das wird dir mehr sagen als alles, was ich sage.

Vorherige Beiträge：