Was ist DESIGN.md? Das Format, der Inhalt und die häufigsten Fehler

DESIGN.md begann bei Google Labs als Format hinter Stitch, einem Tool zur UI-Generierung. Google hat die Spezifikation als Open Source veröffentlicht, und die Spec liegt nun auf GitHub. Sie verbreitete sich schnell über Google hinaus: Atlassian veröffentlichte einen Bericht über Tests zu portablem Design-Kontext in der Praxis, und es entstand ein entsprechendes Katalog-Ökosystem.

Das .md steht schlicht für Markdown. Die Datei hat keine spezielle Syntax, kein zu validierendes Schema und keinen Build-Schritt. Das ist beabsichtigt: Ein Agent liest sie genau so, wie er jede andere Datei in Ihrem Repository liest.

Ein Coding-Agent, der eine UI erstellen soll, muss die visuellen Werte irgendwoher beziehen. Fehlt eine Quelle, nutzt er die Standardwerte der Library, weshalb KI-generierte Produkte oft gleich aussehen. Man kann Werte in einem Prompt angeben, aber Prompts existieren innerhalb einer Konversation, und Konversationen verlieren an Präzision, je länger sie werden.

Eine Datei verliert nicht an Präzision. Das ist der Kern des Mechanismus, und alles andere am Format leitet sich daraus ab.

Statt zu mutmaßen, haben wir Stichproben gezogen. Wir haben 299 DESIGN.md-Dateien aus dem Root-Verzeichnis via GitHub-Code-Suche extrahiert und analysiert. Das erste Ergebnis war überraschend und rückt alles andere in ein neues Licht.

Innerhalb dieser 72 echten Visual-Design-Dateien ist das Bild konsistent. Die mittlere Dateigröße liegt bei 1.337 Wörtern auf 263 Zeilen – es handelt sich also nicht um bloße Entwürfe; hier steckt echte Arbeit drin. Diese Arbeit fließt jedoch in dieselben drei Abschnitte, während dieselben vier konsequent ausgelassen werden.

Farbe und Typografie sind nahezu universell. Radius, Elevation, Ikonografie und Barrierefreiheit sind selten. Und ein Versäumnis wiegt schwerer als all diese, da es unsichtbar bleibt, bis jemand einen Schalter umlegt.

Von den 72 analysierten Visual-Design-Dateien enthalten 50 keinerlei Dark Mode: keinen .dark-Block, kein prefers-color-scheme, keinen zweiten Satz an Werten. Das sind 69%.

Dies ist die folgenschwerste Lücke in der gängigen Praxis, und sie führt zu stillen Fehlern. Im Light Mode sieht alles korrekt aus. Sobald ein Nutzer jedoch das Theme umschaltet, muss der Agent jeden Dark-Mode-Wert spontan erfinden: einen Hintergrund, der nie ausgewählt wurde, einen Vordergrund, dessen Kontrast nie geprüft wurde, und einen Akzent, der verblasst, weil niemand die Chroma für einen dunklen Untergrund erhöht hat.

## Color

### Light
--background: oklch(0.98 0.006 85)
--foreground: oklch(0.22 0.014 85)
--card:       oklch(1 0 0)
--muted-foreground: oklch(0.48 0.012 85)
--primary:    oklch(0.52 0.13 152)
--border:     oklch(0.90 0.008 85)

### Dark
--background: oklch(0.17 0.010 85)   /* not pure black */
--foreground: oklch(0.95 0.006 85)   /* not pure white */
--card:       oklch(0.22 0.010 85)   /* raised, not shadowed */
--muted-foreground: oklch(0.70 0.010 85)
--primary:    oklch(0.68 0.16 152)   /* higher chroma to survive the dark ground */
--border:     oklch(0.30 0.010 85)

Nur 6% der analysierten Dateien verwenden OKLCH. Der Wechsel lohnt sich hier insbesondere deshalb, weil der Helligkeitskanal wahrnehmungsuniform ist. So kann ein Farbton geändert werden, ohne jedes Kontrastpaar erneut prüfen zu müssen.

Die folgenschwerste Entscheidung in der Datei ist die Benennung nach *Rolle* statt nach Farbton. --primary sagt einem Agenten, wo der Wert hingehört; --blue-600 nicht. Rollen ermöglichen es ihm, Ihr System auch in Situationen korrekt anzuwenden, die Sie nie vorhergesehen haben, und sie überstehen ein Rebranding.

86% der analysierten Dateien verwenden keine semantischen Rollennamen. Sie listen Hex-Werte auf oder benennen Farben nach ihrem Farbton. Das ist der Unterschied zwischen einer Datei, die ein Agent auf eine nie beschriebene Komponente anwenden kann, und einer Datei, aus der er nur kopieren kann. Die semantische Token-Ebene leistet hier die eigentliche Arbeit.

Benennen Sie die Schriftfamilien, die Schriftschnitte, das Tracking und die Skalierungsschritte. Ein häufiger Fehler ist die Formulierung *eine Serifenschrift für Überschriften, eine Sans-Serif für den Fließtext*. Dies ist eine Anweisung, die der Agent selbst auflösen muss – und er wird dies jedes Mal anders tun.

## Typography

Heading: "Fraunces", serif — 600, tracking -0.02em
Body:    "Inter", sans-serif — 400, line-height 1.6
Mono:    "JetBrains Mono" — 400, tabular figures in tables

Scale: 0.8125 / 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem
H1 uses 3rem at 1.05 line-height; body copy never exceeds 68ch.

Eine Spacing-Skala, ein Radius, der mit der Elementgröße variiert, und zwei oder drei Elevationsstufen, die auf einer gemeinsamen Lichtquelle basieren. Der Radius wird nur in 21% der Dateien abgedeckt und die Elevation in 26%. Deshalb weisen so viele generierte UIs an jedem Element unabhängig von der Größe den gleichen 0.5rem Eckenradius auf.

## Spacing
Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96px
Section rhythm: 96px desktop, 64px mobile.

## Radius
sm 0.25rem (inputs) · md 0.5rem (buttons) · lg 0.875rem (cards) · xl 1.25rem (modals)

## Elevation
0 flush — use a border, no shadow
1 cards — 0 1px 2px rgb(0 0 0 / 0.06)
2 dropdowns — 0 4px 12px rgb(0 0 0 / 0.08)
Dark mode: raise the surface, do not deepen the shadow.

Tokens sagen einem Agenten, welche Werte zu verwenden sind. Sie sagen jedoch nichts darüber aus, was zu tun ist, wenn er auf eine Komponente stößt, die in Ihrer Datei nie erwähnt wurde. Motive und Verbote schließen diese Lücke; sie entscheiden darüber, ob eine Datei die Ausgabe präzise einschränkt oder sie lediglich einfärbt.

76% der Dateien enthalten keine Verbote und 57% keine Motive. Dies sind die zwei am einfachsten zu schreibenden Abschnitte und gleichzeitig die zwei am häufigsten fehlenden.

## Motifs
- Hairline rules separate sections; no boxed cards on marketing pages.
- Numerals are tabular everywhere they can be compared.
- One accent per screen. If two things compete, one becomes muted.

## Don't
- No gradient text, ever.
- No shadow on a flush surface — use --border.
- Never hardcode a hex. If a role is missing, add the role.

Definieren Sie die Primitiven, die am stärksten zur Identität beitragen: Buttons, Inputs und Cards inklusive ihrer Zustände. Sie müssen nicht jede Komponente aufführen. Die Ikonografie ist der kürzeste Abschnitt der Datei und in der Praxis mit 10% am seltensten: Benennen Sie die Icon-Library, die Strichstärke, die Größenschritte und geben Sie eine Zeile zur Bildbehandlung an.

Neben den fehlenden Abschnitten zeigt sich in über der Hälfte des Korpus ein Fehlerbild: Es wird ein Adjektiv verwendet, wo eigentlich ein Wert stehen sollte.

54 % der von uns gemessenen Dateien enthalten mindestens ein vages Adjektiv anstelle einer Entscheidung. Die häufigsten waren *clean* (39 % der Dateien), *modern* (36 %) und *professional* (22 %), gefolgt von *generous whitespace*, *elegant* und *beautiful*. Zudem enthalten 44 % der Dateien an keiner Stelle einen konkreten Abstands- oder Größenwert.

1. Adjektive statt Werte. Der häufigste Fehler, der in über der Hälfte der Dateien auftritt.
2. Dark mode vergessen. In 69 % der Fälle, und er scheitert lautlos.
3. Farben nach Farbton statt nach Rolle benannt. In 86 % der Fälle, und es führt zu Problemen, sobald der Agent auf eine Komponente trifft, die Sie nicht beschrieben haben.
4. Keine Verbote. In 76 % der Fälle. Verbote werden zuverlässiger befolgt als Präferenzen.
5. Ein Abschnitt mit der Anweisung „nutzen Sie Ihr Urteilsvermögen“. Schlimmer als gar kein Abschnitt, da er genau die Entscheidungsfreiheit zurückgibt, die der Rest der Datei eigentlich einschränken sollte.

Platzieren Sie sie im Repository-Root, direkt neben AGENTS.md. Der Root-Ordner ist entscheidend: Eine DESIGN.md, die in docs/ verschachtelt ist, ist ein Dokument für Menschen, während Agenten, die nach der Konvention suchen, im Root nachsehen.

Referenzieren Sie sie dann in einer Zeile in Ihren Agent-Anweisungen, damit sie entdeckt wird, anstatt nur zufällig gefunden zu werden. Sie ist ein Geschwisterelement zu diesen Dateien und kein Konkurrent: die vier Dateien erfüllen unterschiedliche Aufgaben.

# AGENTS.md

## Design
Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md.

AGENTS.md ist die umfassendere Konvention für Agent-Anweisungen und wird von einer wachsenden Anzahl von Tools gelesen. DESIGN.md enthält den visuellen Vertrag; AGENTS.md verweist darauf.

Dies ist der Teil, den jeder andere Erklärer weglässt. Eine DESIGN.md ist nur so gut wie die Schnittstelle, die sie erzeugt, und die obigen Abschnitte sind keine Illustration. Sie sind die serialisierte Form des untenstehenden Kits.

Wenn Sie sie manuell schreiben, sind die zwei Abschnitte, die Sie zwingend bearbeiten sollten, der Dark mode und die Verbote. Der Korpus zeigt eindeutig, dass dies die Punkte sind, die Menschen überspringen, und sie entscheiden darüber, ob die Datei überhaupt Einschränkungen vorgibt.