Wie man eine DESIGN.md generiert (und was sie ist)

Eine DESIGN.md liegt neben dem Code und beschreibt das beabsichtigte Design in einer Form, die für einen Agenten operationalisierbar ist. Coding-Agenten implementieren UIs zwar gut, neigen aber ohne Art Direction dazu, auf einen neutralen Hausstil zurückzugreifen. Der Name hat sich mittlerweile zu einem kleinen Ökosystem entwickelt: Google Labs hat eine Format-Spezifikation für DESIGN.md open-sourced (vom Stitch-Team, Apache 2.0, noch in der Version alpha), die innerhalb weniger Monate zehntausende GitHub-Stars erhielt. Deren Spezifikation kombiniert maschinenlesbare Tokens im YAML-Frontmatter mit einer für Menschen lesbaren Begründung in Prosa und liefert eine CLI mit, die Dateien validiert und Exporte für Tailwind sowie das W3C Design-Token-Format ermöglicht.

Diese Struktur – exakte Werte plus schriftliche Intention in einer Datei – ist genau die Schlussfolgerung, die auch dieser Leitfaden vertritt. Dabei ist es wichtig, präzise zu unterscheiden, was die Spezifikation leistet und was nicht. Ein Format gibt lediglich vor, wo die Tokens und die Prosa platziert werden. Es erstellt nicht das Designsystem selbst: Die Tokens müssen weiterhin aus einer Quelle stammen, und die Motive, Don'ts sowie Regeln zur Seitenstruktur müssen weiterhin von jemandem festgelegt werden. Katalog-Websites sammeln fertige DESIGN.md-Dateien; die unten beschriebenen Generierungsansätze erstellen eine aus einem tatsächlichen System. Das ist der Unterschied zwischen einer Datei, die lediglich validiert, und einer Datei, die das Ergebnis eines Agenten verändert.

Eine DESIGN.md benötigt mehr als nur eine Farbliste. Agenten brauchen zudem Anweisungen zu Layout, Abständen, der Behandlung von Komponenten und den Details, die ein Design von einem anderen unterscheiden. Ein nützliches Briefing widmet den Großteil des Textes diesen Entscheidungen.

Ein vollständiges Briefing deckt das gesamte System ab, nicht nur die Tokens. Die von Identity Forge generierte DESIGN.md ist in folgende Abschnitte unterteilt:

• Overview: Was das Design ist, für wen es ist und welches Gefühl es vermitteln soll, in ein bis zwei Sätzen.
• Colors: Die semantischen Tokens als CSS-Variablen, bereit zum Einfügen in die globals.css, für Light- und Dark-Mode. Semantische Farb-Tokens erklärt.
• Typography: Die Schriftkombination, Skalierung, Laufweite und Gewichte sowie ein fertiges Next.js-Font-Setup.
• Layout: Basis-Abstände, Container-Breite und Kompositionsregeln.
• Elevation & Depth: Das Schattensystem (oder der bewusste Verzicht darauf).
• Shapes: Eckradien pro Element (Buttons, Cards, Inputs, Badges) und die Behandlung von Rahmen.
• Components: Wie Kernkomponenten behandelt werden sollen, inklusive eines Beispiels.
• Page Structure & Layout: Wie ganze Seiten komponiert werden; hier wird verhindert, dass die KI generische Ergebnisse liefert.
• Personality & References: Die Tonalität und die Referenzpunkte hinter dem Design.
• Distinctive Motifs: Die charakteristischen Elemente, die reproduziert werden sollen; „sie definieren das Design ebenso sehr wie die Tokens“.
• Do's & Don'ts: Die Regeln, die sicherstellen, dass die generierte UI innerhalb der Designwelt bleibt.
• Agent Rules: Explizite Anweisungen für den Coding-Agenten selbst.

Die obige Liste beschreibt, was ein vollständiges Briefing abdeckt. Es ist wichtig zu wissen, inwiefern veröffentlichte Dateien davon abweichen, da diese Lücke konsistent ist und genau zeigt, welche Abschnitte bei einer manuellen Erstellung priorisiert werden sollten.

Es wurden 299 DESIGN.md-Dateien aus öffentlichen Repositories und Verzeichnissen analysiert: echte Dateien, die erstellt wurden, um Coding-Agents Design-Richtlinien zu geben. 72 davon waren spezifische Dateien für das visuelle Design.

Stellt man die letzten zwei Zeilen gegenüber, ist das Muster unverkennbar. Typografie wird in 83 % der Dateien erwähnt, aber in 44 % der Dateien wird keine einzige Größe angegeben. Dies sind Dokumente, die über Typografie sprechen, ohne zu sagen, wie groß die Elemente sein sollen.

Die Zahlen zu den Adjektiven erklären den Rest. „Clean“ erscheint in 39 % dieser Dateien und „modern“ in 36 %. Beides sind Begriffe, die ein Modell erfüllt, indem es das Zentrum seiner Trainingsverteilung produziert – genau die generische Ausgabe, die durch die Datei eigentlich verhindert werden sollte.

Das einzige Unterscheidungsmerkmal zwischen einem Briefing, das die Ausgabe verändert, und einem, das dies nicht tut: Kann ein Satz gegen einen gerenderten Screen geprüft werden? Wenn nicht, ist er reine Dekoration.

Jeder Eintrag in der rechten Spalte kann durch das Betrachten eines Screens oder durch Greppen des Codes verifiziert werden. Jeder Eintrag in der linken Spalte kann durch fast alles erfüllt werden, was bedeutet, dass er keinerlei Einschränkung darstellt.

Drei Eigenschaften entscheiden darüber, ob ein Verbot greift oder ignoriert wird.

Die dritte Zeile wird am häufigsten übersehen. Ein Verbot ohne Alternative öffnet eine Lücke, die das Modell aus derselben Trainingsverteilung füllt, der man eigentlich entkommen wollte. Jedes "niemals X" benötigt ein "stattdessen Y".

Wenn Sie die Datei manuell schreiben, anstatt sie zu generieren, ist dies eine solide Ausgangsstruktur. Sie ist bewusst kurz gehalten. Ein Briefing, das niemand im Kopf behalten kann, konkurriert mit der eigentlichen Aufgabe um die Aufmerksamkeit des Modells. Etwa 400 Zeilen sind eine praktikable Obergrenze; dieses Skelett liegt deutlich darunter.

# DESIGN.md

## Overview

A dense internal tool for operations staff who work in it for hours.
Quiet, information-first. Nothing here has to convince anyone of anything.

## Don'ts

- No gradients
- No drop shadows — elevation is a surface step plus a 1px border
- No font-weight above 600
- No colour value outside the tokens in globals.css
- No border-radius above 12px
- No decorative use of the state colours

## Colours

Defined as semantic roles in globals.css, light and dark.
Do not restate values here — read them from that file.

- `--primary` — primary buttons and active nav state ONLY.
  Never on text, borders, backgrounds or gradients.
- `--muted-foreground` — secondary and supporting text only.
- `--border` — structural edges and dividers.
- `--destructive` / `--success` / `--warning` — reserved for state.

## Typography

Family: Inter (variable). Weights 400 and 600 only.
Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48.
Tracking: -0.02em at 32px and above, 0 below, +0.02em on 12px caps.
Hierarchy comes from size and colour, never from weight above 600.

## Spacing & density

Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64. No other values.
Controls: 8–12px padding. Table rows: 32px. Section gap: 32px.

## Elevation

A surface step plus a 1px `--border`. Never a box-shadow.

## Shapes

Controls 6px. Cards and panels 12px. Nothing above 12px.

## Composition

One primary action per section.
Related controls share a group; unrelated ones are separated by a full step.
Tables are never nested inside cards.

## Motifs

Section headings carry a 2px `--primary` rule on the left edge.
Numeric columns are always tabular-nums and right-aligned.
Empty states are a single line of `--muted-foreground` text, never an illustration.

## Agent rules

Read this file before writing or editing any UI.
Match the nearest existing component in this repo rather than inventing a
new pattern. If no similar component exists, say so before writing one.

Zwei Aspekte dieser Datei lohnt es sich zu kopieren, selbst wenn Sie alles andere ändern. Die Verbote stehen an zweiter Stelle, noch vor allem, was sie modifizieren könnten; so stößt ein Modell beim Lesen von oben nach unten zuerst auf die Einschränkungen und dann auf die Erlaubnisse. Zudem verweist der Farbabchnitt auf die globals.css, anstatt Werte zu wiederholen: Sobald ein Hex-Wert an zwei Stellen existiert, wird einer aktualisiert und der andere nicht, und das Modell wird selbstbewusst die veraltete Kopie verwenden.

Eine DESIGN.md ist nur so gut wie das System dahinter. Unten sehen Sie das kostenlose ambient-sage Kit: die Tokens, Schriften und Behandlungen, die in der DESIGN.md beschrieben werden, live gerendert:

1. 1

   CLI: DESIGN.md + Tokens in das Repo schreiben

   Der schnellste Weg. Wählen Sie einen Kit-Slug aus der Galerie und wenden Sie ihn an; Sie erhalten eine committed DESIGN.md sowie eine passende Tokens-Datei.

   Copy

   identityforge apply ambient-sage

2. 2

   MCP: Den Agent abrufen lassen

   Nach der Installation des MCP-Servers ruft der Agent get_design_md(slug) auf, um das vollständige Briefing zu lesen, und apply_theme, um es zu schreiben. Installation für Ihr Tool:

   Copy

   npx --yes identityforge@latest install --client claude-code

3. 3

   shadcn: Die in der DESIGN.md referenzierten Tokens installieren

   Wenn Sie nur die Werte benötigen, installiert der Registry-Eintrag die CSS-Variablen des Kits direkt.

   Copy

   npx shadcn add https://identityforge.io/r/ambient-sage.json

Identity Forge generiert die DESIGN.md und die Tokens aus demselben Kit, sodass der Text die Werte im Stylesheet beschreibt. Wie sich dies von der manuellen Anpassung eines DESIGN.md-Katalogeintrags unterscheidet, finden Sie unter Identity Forge vs getdesign.md.

Die Datei zu schreiben und einfach davon auszugehen, dass sie funktioniert, führt dazu, dass Teams das Problem erst drei Wochen später bemerken. Vier Prüfungen, beginnend mit der einfachsten.

1. 1

   Nach literalen Farbwerten greppen

   Wenn der Agent semantischen Rollen folgt, sollten außerhalb der Token-Datei keine Hex-Werte vorkommen. Dies ist das schnellste mögliche Signal.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Suchen Sie mittels Grep nach den untersagten Schriftschnitten (Weights)

   Beim Schriftschnitt kehrt die Hierarchie oft unbemerkt zum Standard zurück; dies ist das früheste Anzeichen dafür, dass eine Einschränkung nicht beachtet wird.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Fordern Sie denselben Screen zweimal in separaten Sessions an

   Die Konsistenz über mehrere Sessions hinweg ist der eigentliche Test. Wenn zwei Durchläufe bei Abständen, Radien oder der Hierarchie signifikant voneinander abweichen, zeigt der Diff genau an, welcher Abschnitt im Brief fehlt.

4. 4

   Erstellen Sie zuerst einen Screen im Dark Mode

   Wenn der Dark Mode abgeleitet statt definiert wurde, zeigt sich dies hier: tote Schatten, schlammige Mittelgrautöne, ein greller Akzent. Es ist weitaus kostengünstiger, dies beim ersten Screen zu finden als beim zwanzigsten.

Die ersten beiden gehören in die CI. Ein Check, der einen Pull Request aufgrund eines rohen Hex-Werts ablehnt, leistet mehr für die langfristige Konsistenz als jede Menge Prosa – zu demselben Schluss kam Salesforce mit dem SLDS-Linter.