DESIGN.md begann bei Google Labs als Format hinter Stitch, dessen 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 Schema zur Validierung 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 alle anderen Aspekte des Formats leiten sich daraus ab.

Statt zu mutmaßen, haben wir Stichproben gezogen. Wir haben 299 DESIGN.md-Dateien aus dem Root-Verzeichnis via GitHub Code Search 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 Dateilänge beträgt 1.337 Wörter 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.

Farben 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 Coding-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 Hintergrund 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* – eine Anweisung, die der Agent selbst auflösen muss und dies jedes Mal anders tun wird.

## 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 denselben 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 sind der Unterschied zwischen einer Datei, die das Ergebnis einschränkt, und einer, die es 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 benötigen nicht jede einzelne Komponente. Die Ikonografie ist der kürzeste Abschnitt der Datei und in der Praxis mit 10% am seltensten vertreten – 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 wiederkehrendes Problem: die Verwendung von Adjektiven an Stellen, an denen ein Wert stehen müsste.

54 % der untersuchten Dateien enthalten mindestens ein vages Adjektiv anstelle einer konkreten Entscheidung. Am 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 Wert für Abstände oder Größen.

1. Adjektive statt Werte. Der häufigste Fehler, in über der Hälfte der Dateien.
2. Dark Mode fehlt. In 69 % der Fälle, was zu stillschweigenden Fehlern führt.
3. Farben nach Farbton statt nach Rolle benannt. In 86 % der Fälle; dies führt zu Problemen, sobald der Agent auf eine Komponente stößt, die nicht beschrieben wurde.
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 ein fehlender Abschnitt, da er genau den Ermessensspielraum zurückgibt, den der Rest der Datei eigentlich einschränken sollte.

Legen Sie sie im Root-Verzeichnis des Repositories neben der AGENTS.md ab. Der Speicherort ist entscheidend: Eine DESIGN.md, die in docs/ verschachtelt ist, ist ein Dokument für Menschen; Agents, die nach dieser Konvention suchen, schauen im Root-Verzeichnis nach.

Referenzieren Sie die Datei anschließend in einer Zeile in Ihren Agent-Instruktionen, damit sie gezielt gefunden und nicht nur zufällig entdeckt wird. Sie ist eine Ergänzung zu diesen Dateien, kein Ersatz – 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 allgemeinere Konvention für Agent-Instruktionen und wird von einer wachsenden Anzahl an Tools gelesen. Die DESIGN.md enthält den visuellen Vertrag; die AGENTS.md verweist darauf.

Dies ist der Teil, den fast jede andere Anleitung auslässt. Eine DESIGN.md ist nur so gut wie das Interface, das sie hervorbringt. Die oben genannten Abschnitte sind keine bloße Illustration – sie sind die serialisierte Form des unten stehenden Kits.

Wenn Sie die Datei manuell schreiben, sind der Dark Mode und die Verbote die zwei Abschnitte, die Sie sich unbedingt durcharbeiten sollten. Der Korpus zeigt eindeutig, dass dies die Bereiche sind, die am häufigsten übersprungen werden – und genau sie entscheiden darüber, ob die Datei tatsächlich eine verbindliche Vorgabe darstellt.