Doku

Was ist DESIGN.md?

DESIGN.md ist eine Klartextdatei, die ein Designsystem für KI-Agenten beschreibt. Das YAML-Frontmatter oben enthält die exakten Design-Tokens: Farben, Typografie, Abstände, abgerundete Ecken und Komponenten. Der Markdown-Teil darunter erklärt, wie und warum sie angewendet werden. Menschen und Agenten können die Datei lesen, bearbeiten und durchsetzen.

README.md erklärt, was ein Projekt ist. AGENTS.md sagt Coding-Agenten, wie es gebaut wird. DESIGN.md sagt ihnen, wie es aussehen und sich anfühlen soll, damit die Screens, die ein Agent erzeugt, eine Palette, eine Schriftskala und eine Komponentensprache teilen, statt auseinanderzudriften.

Woher DESIGN.md kommt

Google hat DESIGN.md mit Google Stitch eingeführt, seinem KI-Designtool, als Design-Gegenstück zu AGENTS.md. Google Labs veröffentlicht das Format als offene Spezifikation im Repository google-labs-code/design.md unter der Lizenz Apache 2.0. Die DESIGN.md-Spezifikation ist als Alpha gekennzeichnet, rechne also damit, dass sich das Format noch ändert, während es reift.

Dasselbe Repository liefert ein npm-Paket, @google/design.md, mit einem lint-Befehl, der Struktur, fehlerhafte Token-Referenzen und WCAG-Kontrast prüft, und einem diff-Befehl, der zwei Versionen einer Datei Token für Token vergleicht.

Aufbau einer DESIGN.md-Datei

Jede DESIGN.md-Datei hat zwei Ebenen. Das YAML-Frontmatter enthält maschinenlesbare Design-Tokens wie exakte Farbwerte, Schrifteigenschaften, Abstandsskalen und Token-Referenzen für Komponenten. Der Markdown-Teil liefert die für Menschen lesbare Begründung des Designs.

Die Spezifikation behandelt die Tokens als verbindliche Werte und den Text als Kontext für ihre Anwendung. Tokens geben Agenten exakte Werte. Der Text erklärt ihnen, warum es diese Werte gibt und wie sie über alle Screens hinweg einheitlich eingesetzt werden.

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

Die acht kanonischen Abschnitte

Der Markdown-Teil nutzt ##-Überschriften. Abschnitte können wegfallen, wenn sie nicht relevant sind, aber vorhandene Abschnitte sollten dieser Reihenfolge folgen. Eine doppelte Überschrift macht die Datei ungültig; unbekannte Abschnitte bleiben erhalten.

Overview (auch Brand & Style). Look and Feel in wenigen Sätzen: Stimmung, Dichte, Persönlichkeit.
Colors. Jeder Farb-Token und seine Rolle, etwa für primäre Aktionen oder Seitenflächen.
Typography. Schriftfamilien und die Schriftskala, von großen Display-Überschriften bis zu kleinen Labels.
Layout (auch Layout & Spacing). Die Abstandsskala, das Raster, Inhaltsbreiten und Spaltenabstände.
Elevation & Depth (auch Elevation). Wie sich Flächen voneinander abheben: Schatten, Rahmen, Tönungen.
Shapes. Eckenradien und weitere Formregeln.
Components. Buttons, Eingabefelder, Karten und andere Atome, mit ihren Tokens und Zuständen.
Do's and Don'ts. Die Regeln, die ein Agent nicht brechen sollte.

Ein kompakter Markdown-Teil mit allen kanonischen Abschnitten in der richtigen Reihenfolge. Passe den Inhalt an dein Produkt an, behalte Überschriften und Reihenfolge bei.

## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

Design-Tokens und Schema

DESIGN.md bettet Design-Tokens als YAML-Frontmatter am Anfang der Datei ein. Der Frontmatter-Block beginnt mit einer Zeile, die genau --- enthält, und endet mit demselben Trennzeichen.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Übliche Stufennamen sind xs, sm, md, lg, xl und full, aber jeder beschreibende Schlüssel ist gültig. Abstands-Tokens stehen im YAML unter spacing: und werden im Layout-Abschnitt des Markdown-Teils beschrieben.

Token-Typen

Farbe: Jeder gültige CSS-Farbwert. Hex in der Form #RRGGBB ist der empfohlene Standard, zum Beispiel "#1A1C1E".
Dimension: Zahl mit der Einheit px, em oder rem. Beispiele:48px,-0.02em.
Token-Referenz: In geschweiften Klammern, verweist auf einen Wert im YAML-Baum. Beispiel:{colors.primary}.
Typografie: Ein zusammengesetztes Objekt mit Schrifteigenschaften wie Familie, Größe, Gewicht, Zeilenhöhe und Laufweite. Siehe Typografie-Eigenschaften.

Typografie-Eigenschaften

fontFamily: Der Name der Schriftfamilie.
fontSize: Die Schriftgröße als Dimension.
fontWeight: Numerische Schriftstärke wie 400 oder 700.
lineHeight: Eine Dimension oder ein Faktor ohne Einheit. Werte ohne Einheit werden empfohlen.
letterSpacing: Anpassung der Laufweite als Dimension.
fontFeature: Konfiguriert font-feature-settings.
fontVariation: Konfiguriert font-variation-settings.

Token-Referenzen

Eine Token-Referenz steht in geschweiften Klammern und enthält einen Objektpfad zu einem anderen Wert im YAML-Baum. Bei den meisten Token-Gruppen sollte die Referenz auf einen einfachen Wert zeigen statt auf eine Gruppe. Im Abschnitt für Komponenten sind Referenzen auf zusammengesetzte Werte wie Typografie-Stufen erlaubt.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Komponenten

Der Abschnitt für Komponenten enthält Stilvorgaben für Komponenten-Atome wie Buttons, Chips, Listen, Eingabefelder, Checkboxen, Radiobuttons und Tooltips. Designsysteme können weitere Komponenten definieren, die für ihren Produktbereich wichtig sind.

Varianten für Hover-, Active- oder Pressed-Zustände werden als eigene Komponenteneinträge mit verwandten Schlüsselnamen definiert, etwa button-primary-hover.

backgroundColor: Farbe
textColor: Farbe
typography: Typografie
rounded: Dimension
padding: Dimension
size: Dimension
height: Dimension
width: Dimension

Empfohlene Token-Namen

Diese Namen sind Empfehlungen, keine Pflicht. Sie bieten sinnvolle Standards für Einheitlichkeit über Systeme hinweg.

Farben: primary, secondary, tertiary, neutral, surface, on-surface, error

Typografie: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Rundungen: none, sm, md, lg, xl, full

Wie KI-Agenten DESIGN.md nutzen

Leg die DESIGN.md ins Stammverzeichnis deines Repositorys, neben README.md und AGENTS.md. Jeder Agent mit Dateizugriff kann sie lesen, aber die meisten laden sie nicht von selbst. Verweise darauf in den Anweisungen, die dein Agent ohnehin liest, oder nenne sie im Prompt, wenn du nach UI-Arbeit fragst. Ein kurzer Hinweis reicht:

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.

Claude Code: Liest Dateien in deinem Repo und lädt beim Start CLAUDE.md. Füge dort eine Zeile hinzu, die auf DESIGN.md verweist, oder erwähne die Datei in deinem Prompt.
Cursor: Füge DESIGN.md zum Chat-Kontext hinzu oder verweise in einer Projektregel darauf, damit sie für jede UI-Anfrage gilt.
GitHub Copilot: Verweise in der Copilot-Anweisungsdatei deines Repositorys auf DESIGN.md oder hänge sie im Chat an, wenn du nach UI-Arbeit fragst.
Google Stitch: Hier hat das Format angefangen. Stitch nutzt eine DESIGN.md, damit erzeugte Screens eine Palette, eine Schriftskala und eine Komponentensprache teilen.

Der Agent übernimmt dann exakte Werte aus den Tokens (den Hex-Wert für einen primären Button, die Größe eines body-md-Labels) und entscheidet anhand des Texts, wo sie hingehören.

DESIGN.md vs. AGENTS.md vs. README.md

Die drei Dateien liegen nebeneinander und beantworten unterschiedliche Fragen. DESIGN.md ersetzt AGENTS.md nicht; beide arbeiten zusammen.

Datei	Geschrieben für	Beantwortet
`README.md`	Menschen, die das Projekt nutzen oder dazu beitragen	Was ist das und wie starte ich es?
`AGENTS.md`	Coding-Agenten	Wie baue, teste und ändere ich diesen Code?
`DESIGN.md`	Coding- und Design-Agenten	Wie soll die Oberfläche aussehen und sich anfühlen?

Echte DESIGN.md-Beispiele

Am schnellsten verstehst du das Format, wenn du ein paar echte Dateien liest. Jede dieser Galerie-Seiten zeigt eine DESIGN.md, die aus der öffentlichen Website der Marke extrahiert wurde, mit Farbpalette und Schriftprobe. Es sind keine offiziellen Markenrichtlinien.

Alle DESIGN.md-Beispiele ansehen

So bekommst du eine DESIGN.md

Schreib sie von Hand. Starte mit der Spezifikation und den Beispielen oben und prüfe die Datei dann mit dem kostenlosen DESIGN.md-Validator oder dem lint-Befehl von Google.
Starte mit einem Beispiel. Kopiere eine Datei aus der Galerie und passe Tokens und Text an dein Produkt an.
Erzeuge sie aus einer Live-Website. Füge eine öffentliche URL in Design Extractor ein. Das Tool rendert die Website in einem Browser und liefert eine DESIGN.md mit ihren Farben, Typografie, Abständen und Komponenten, die der Spezifikation oben folgt. Die Seite zum DESIGN.md-Generator erklärt, was du bekommst. Dieselbe Extraktion läuft auch über die Chrome-Erweiterung und aus deinem Agenten über den MCP-Server.

FAQ

Fragen zu DESIGN.md

Kurze Antworten zum DESIGN.md-Format, zu seiner Herkunft und zur Nutzung mit KI-Agenten.

Eine DESIGN.md ist eine Klartextdatei, die ein Designsystem für KI-Agenten beschreibt. Das YAML-Frontmatter oben enthält die exakten Tokens (Farben, Typografie, Abstände, abgerundete Ecken und Komponenten), und der Markdown-Teil darunter erklärt, wie und warum sie angewendet werden. Agenten lesen die Tokens für die Werte und den Text für die Absicht.

Google hat DESIGN.md mit Stitch eingeführt, seinem KI-Designtool. Google Labs veröffentlicht die Spezifikation auf GitHub (google-labs-code/design.md) unter der Lizenz Apache 2.0. Das Format ist als Alpha gekennzeichnet, rechne also mit Änderungen, während es reift.

AGENTS.md sagt Coding-Agenten, wie sie ein Projekt bauen und daran arbeiten: Befehle, Konventionen, Tests. DESIGN.md sagt ihnen, wie das Produkt aussehen und sich anfühlen soll: Farben, Schrift, Abstände, Formen und Komponenten. README.md richtet sich an die Menschen, die das Projekt nutzen oder dazu beitragen. Viele Repos führen alle drei nebeneinander.

Leg sie ins Stammverzeichnis des Repositorys, neben README.md und AGENTS.md, damit Agenten mit Dateizugriff sie finden. Verweise dann in den Anweisungen darauf, die dein Agent ohnehin lädt, etwa AGENTS.md, CLAUDE.md, eine Cursor-Regel oder deine Copilot-Anweisungen, oder erwähne sie im Prompt, wenn du nach UI-Arbeit fragst.

Nein. Die Spezifikation erlaubt es, Abschnitte wegzulassen, die nicht passen, aber die vorhandenen sollten der kanonischen Reihenfolge folgen: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Eine Abschnittsüberschrift darf nicht doppelt vorkommen, und unbekannte Abschnitte bleiben erhalten, statt abgelehnt zu werden.

Das npm-Paket @google/design.md von Google hat einen lint-Befehl, der Struktur, fehlerhafte Token-Referenzen und WCAG-Kontrast prüft. Design Extractor bietet außerdem einen kostenlosen DESIGN.md-Validator, der Struktur und Tokens in deinem Browser prüft und eine Vorschau der Datei zeigt, ohne sie hochzuladen.

Schreib sie von Hand nach der Spezifikation, kopiere eine aus einer Galerie echter Beispiele als Ausgangspunkt oder erzeuge eine aus der Live-Website. Design Extractor nimmt eine öffentliche URL, rendert die Website in einem Browser und liefert eine DESIGN.md mit ihren Farben, Typografie, Abständen und Komponenten, bereit für dein Repo.

Willst du eine für eine Website, die dir gefällt?

Füge eine öffentliche URL ein und erhalte ihre DESIGN.md.

Website extrahieren

Token-Typen

Typografie-Eigenschaften

Token-Referenzen

Komponenten

Empfohlene Token-Namen

Fragen zu DESIGN.md

Was ist eine DESIGN.md-Datei?

Wer hat das DESIGN.md-Format entwickelt?

Was ist der Unterschied zwischen DESIGN.md und AGENTS.md?

Wohin gehört DESIGN.md in meinem Projekt?

Brauche ich alle acht Abschnitte?

Wie prüfe ich, ob eine DESIGN.md gültig ist?

Wie bekomme ich eine DESIGN.md für eine bestehende Website?