DESIGN.md: dein Designsystem für Codex.

DESIGN.md ist eine einfache Textdatei, die KI-Agenten dein Designsystem beschreibt: exakte Farben, Schriften, Abstände und Komponenten, dazu die Begründung dahinter. Leg sie in dein Repository, und Codex gestaltet jeden neuen Screen in derselben visuellen Sprache.

Aktualisiert am 2. November 2026 · 8 Min. Lesezeit

Was ist DESIGN.md?

DESIGN.md ist ein offenes Format von Google Labs, mit dem du Coding-Agenten eine visuelle Identität beschreibst. Es stammt aus Google Stitch, steht unter der Apache-2.0-Lizenz, und die Spezifikation ist noch als alpha gekennzeichnet. Rechne also mit Änderungen.

Eine DESIGN.md-Datei hat zwei Ebenen:

• Design-Tokens in YAML. Exakte, maschinenlesbare Werte: Farben, Typografie, Eckenradien, Abstände und Komponentenstile. Die Tokens sind die verbindlichen Werte.
• Fließtext in Markdown. Die Begründung: wie sich das Produkt anfühlen soll, wann welche Farbe zum Einsatz kommt und was zu vermeiden ist. Der Text sagt dem Agenten, wie er die Tokens anwenden soll.

Ohne eine solche Datei wählt ein Agent bei jedem neuen Screen einen neuen Blauton und einen neuen Button-Stil. Mit ihr passt der fünfzigste Screen zum ersten.

Was in eine DESIGN.md gehört

Die Tokens können im YAML-Frontmatter am Anfang der Datei stehen oder in yaml-Codeblöcken innerhalb der einzelnen Abschnitte. Das Schema kennt fünf Token-Gruppen:

Der Fließtext ist in ##-Abschnitte gegliedert. Jeder Abschnitt ist optional, aber die vorhandenen sollten in dieser Reihenfolge stehen: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components und Do’s and Don’ts. Die Abschnittsnamen gibt das Format vor, deshalb bleiben sie auf Englisch.

Ein vollständiges Beispiel

Diese DESIGN.md beschreibt die Lese-App von unserer Seite mit Prompts für mobile Apps. Speichere sie als DESIGN.md im Stammverzeichnis deines Repositorys.

---
version: alpha
name: Pagely
description: Calm, bookish UI for a reading-habit app.
colors:
  primary: '#1F3D2B'
  on-primary: '#FAF6EE'
  secondary: '#E8735A'
  tertiary: '#F2C14E'
  neutral: '#FAF6EE'
  surface: '#FFFFFF'
  on-surface: '#1F2A22'
typography:
  headline-lg:
    fontFamily: Georgia
    fontSize: 32px
    fontWeight: 400
    lineHeight: 1.15
  body-md:
    fontFamily: system-ui
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
  label-caps:
    fontFamily: system-ui
    fontSize: 13px
    fontWeight: 500
    letterSpacing: 0.12em
rounded:
  md: 16px
  lg: 22px
  full: 9999px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: '{colors.primary}'
    textColor: '{colors.on-primary}'
    rounded: '{rounded.md}'
    padding: 18px
---

## Overview

Quiet, warm, and bookish, like a café with good light. Screens feel spacious and
unhurried; one clear next step per screen.

## Colors

- **Primary (#1F3D2B):** Deep forest green for primary actions and the streak card.
- **Secondary (#E8735A):** Coral for progress and small highlights only.
- **Tertiary (#F2C14E):** Warm yellow for streak and goal indicators.
- **Neutral (#FAF6EE):** Cream background for every screen, never pure white.

## Typography

Georgia for headlines gives a literary voice. System UI for everything else keeps
body text crisp. Labels are uppercase with wide letter spacing.

## Layout

24px side margins on phones. Spacing follows an 8px scale. Primary actions sit in
the lower half of the screen, within thumb reach.

## Elevation & Depth

No heavy shadows. Depth comes from white cards with a 1px warm border on the cream
background.

## Shapes

Soft and rounded: 16px for buttons and inputs, 22px for cards.

## Components

Primary buttons are full-width, deep green, 18px padding. One primary button per screen.

## Do's and Don'ts

- Do keep text contrast at WCAG AA or better.
- Do use coral sparingly: progress bars and one highlight per screen.
- Don't use pure black or pure white.
- Don't put more than two type sizes in a single card.

So hält sich Codex daran

Codex liest AGENTS.md automatisch: Es beginnt im Stammverzeichnis des Repositorys und arbeitet sich bis zu dem Ordner vor, in dem du gerade arbeitest. Nach DESIGN.md sucht Codex nicht von selbst, deshalb verweist du in AGENTS.md darauf:

## Design

- Before any UI work, read DESIGN.md and use only its tokens.
- If a screen needs a value that DESIGN.md doesn't define, ask before inventing one.
- After editing DESIGN.md, run `npx @google/design.md lint DESIGN.md` and fix any errors.

Danach fragst du wie gewohnt nach Screens. Wenn du die Datei im Prompt erwähnst, ist es eindeutig:

Gestalte gemäß DESIGN.md den Screen [Einstellungen] als eine eigenständige HTML-Datei in 390×844. Verwende nur Farben, Schriftgrößen, Radien und Abstände aus DESIGN.md und sag mir, falls du etwas gebraucht hast, das dort nicht definiert ist.

Eine DESIGN.md mit Codex schreiben

Von Hand musst du die Datei selten schreiben. Wenn es dein Produkt schon gibt, lass Codex sie aus deinem Code ableiten:

Lies unsere Tailwind-Konfiguration, das globale CSS und die fünf am häufigsten verwendeten Komponenten und schreib dann eine DESIGN.md ins Stammverzeichnis des Repositorys. Führe zuerst `npx @google/design.md spec` aus und halte dich an dieses Format: Tokens im YAML-Frontmatter, danach die Abschnitte Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components und Do's and Don'ts. Verwende nur Werte, die im Code vorkommen. Führe zum Schluss `npx @google/design.md lint DESIGN.md` aus und behebe alle Fehler.

Bei einem neuen Produkt startest du mit einer Richtung, die dir gefällt, etwa einem Mockup, das du auf einem Canvas abgenommen hast, oder einem Referenz-Screenshot:

Hier ist das Screen-Design, das wir abgenommen haben [Screenshot anhängen oder HTML-Datei nennen]. Schreib eine DESIGN.md, die Farben, Schrift, Abstände, Eckenradien und Button-Stil festhält, mit einer kurzen Overview, wie es wirken soll, und fünf Do's and Don'ts. Halte dich an das DESIGN.md-Format aus `npx @google/design.md spec`.

Das Kommandozeilen-Tool @google/design.md prüft mit lint außerdem Kontrastverhältnisse und kaputte Token-Verweise, vergleicht mit diff zwei Versionen und macht mit export aus deinen Tokens ein Tailwind-Theme oder W3C-Design-Tokens.

DESIGN.md vs. SKILL.md vs. AGENTS.md

Diese drei Dateien liegen oft im selben Repository und erfüllen unterschiedliche Aufgaben:

Sie ergänzen sich gut. Ein Design-Skill kann sagen „Lies DESIGN.md, bevor du etwas gestaltest“, und AGENTS.md stellt sicher, dass das auch ohne den Skill passiert. Mehr zu Skills findest du in Codex-Plugins vs. Skills.

Wo du Beispiele findest

Die Open-Source-Sammlung awesome-design-md enthält DESIGN.md-Dateien, die die Designsysteme bekannter Websites beschreiben, jeweils mit Vorschauseite. Daran lernst du gut, wie andere Farbe, Schrift und Komponenten beschreiben. Nutze sie als Vorlage für die Struktur, nicht, um die Marke eines anderen Unternehmens zu kopieren.

Häufige Fragen

Ist DESIGN.md ein offizieller Standard?

Es ist eine offene Spezifikation von Google Labs, die Google Stitch verwendet und die auf GitHub veröffentlicht ist. Die Spezifikation ist noch im Alpha-Stadium, und laut eigener Dokumentation wird sich das Format noch ändern.

Unterstützt Codex DESIGN.md?

Codex kann jede Datei in deinem Repository lesen und befolgen. Eine spezielle Einstellung gibt es nicht: Verweise wie oben gezeigt in AGENTS.md oder in deinem Prompt auf DESIGN.md.

Ersetzt DESIGN.md Figma oder ein Designsystem?

Nein. Es ist eine Textzusammenfassung deines Designsystems, die Agenten lesen können. Teams, deren maßgebliche Quelle in Figma oder im Code liegt, können DESIGN.md daraus erzeugen und aktualisieren, wenn sich das System ändert.

Weiterlesen

• Die besten Codex-Skills für UI-DesignSkills, die Codex Geschmack geben, und wie du einen für dein eigenes Designsystem schreibst.
• Prompts für das UI-Design mobiler AppsPrompts, die ein Designsystem Screen für Screen zum Einsatz bringen.