DESIGN.md: KI-UI-Inkonsistenz beheben

Problem: Claude Code hat starken lokalen Kontext und schwachen Produkt-Kontext. Es kennt die Datei, die es bearbeitet. Es weiß nicht, wie dein Produkt aussehen soll. Zwischen Sessions verdunstet dein Design-System. Buttons erscheinen, wo Links sein sollten. Empty States fehlen. Eine Farbe, die in einer Komponente #E07850 war, wird in der nächsten zu orange-400.

Quick Win: Lege eine design.md-Datei im Projekt-Root ab und referenziere sie aus CLAUDE.md. Deine Design-Werte reisen mit der Codebase. Jede Session startet mit denselben Constraints im Kontext.

Was design.md wirklich ist

Eine design.md-Datei ist ein Design-System als Plain-Text. Keine spezielle Syntax. Kein Tooling erforderlich. Farben, Abstände, Typografie, Komponenten-Regeln und Interaktionszustände, in lesbarem Markdown geschrieben.

Google Stitch hat das Format im März 2026 eingeführt und es als Interoperabilitäts-Infrastruktur positioniert, ähnlich wie README.md eine universelle Konvention wurde. Die awesome-design-md-Collection auf GitHub erreichte bis April 2026 62.300 Sterne und enthält 60+ Brand-Design-Systeme im Format: Stripe, Linear, Supabase, Vercel, Notion und andere.

Die Idee ist einfach. Claude Code liest Dateien. Wenn das Design-System eine Datei ist, liest Claude Code das Design-System.

Warum Sessions ohne sie driften

Claude Code lädt Kontext am Anfang jeder Session. Es liest CLAUDE.md, scannt geöffnete Dateien und baut ein Bild deines Projekts auf. Ohne eine explizite Design-Datei gibt es nichts, das UI-Entscheidungen an eine einzige Wahrheitsquelle bindet.

Du hast die Primärfarbe vielleicht irgendwo in einem Kommentar beschrieben. Oder eine Tailwind-Klasse in einer Komponente. Claude liest was es zuerst öffnet und extrapoliert von dort. Drei Sessions später ist deine UI eine Sammlung von Vermutungen.

Eine design.md-Datei in CLAUDE.md ändert den Input. Werte sind explizit, nicht inferiert. Jede Session öffnet mit derselben Wahrheitsquelle im Kontext.

design.md von Google Stitch holen

Google Stitch ist ein UI-Design-Tool von Google Labs, gestartet auf Google I/O im Mai 2025. Es läuft auf Gemini 2.5 Pro, lebt unter stitch.withgoogle.com und ist während der Labs-Phase kostenlos (Google-Konto, keine Warteliste, 350 Generierungen pro Monat im Free-Tier). Der design.md-Export kam mit Stitch 2.0 am 18. März 2026.

Der Workflow zum Generieren deiner Datei:

1. Geh zu stitch.withgoogle.com. Klick den Tab Web (nicht App). Wähle das höchste verfügbare Pro-Modell.
2. Lade optional einen Referenz-Screenshot deiner aktuellen UI oder ein Inspirationsbild hoch.
3. Schreib ein Brief, das deine Marke beschreibt: Farben, Ton, Komponentenstil, was das Produkt tut.
4. Iteriere im Gespräch, bis der Output deiner Absicht entspricht.
5. Klick Export, wähle DESIGN.md, speichere die Datei in deinem Projekt-Root.

Stitch baut eine strukturierte Datei, die Farb-Tokens, typografische Skala, Abstands-Einheiten, Komponentenmuster und Zustandsdefinitionen (hover, focus, active, disabled) abdeckt. Der Output ist portabel. Er funktioniert mit Claude Code, Cursor, Windsurf oder jedem Tool, das Dateien liest.

CLAUDE.md mit der Datei verknüpfen

design.md im Root zu platzieren reicht nicht. Ohne explizite Anweisungen in CLAUDE.md behandelt Claude die Datei als Referenzmaterial, das es konsultieren kann. Mit expliziten Anweisungen behandelt Claude die Werte als Constraints, denen es folgen muss.

Der Block, der funktioniert:

## Design System
This project uses a design system defined in `design.md` at the project root.
Always refer to this file when generating or modifying any UI component.
- Use only colors, fonts, and spacing values defined in design.md.
- Do not invent new values or use defaults from any framework.
- Match component states (hover, focus, active, disabled) to the patterns in design.md.
- Follow the typographic scale and weight assignments in design.md.
@design.md

Der @design.md-Import am Ende injiziert den gesamten Dateiinhalt beim Session-Start. Die vier Bullet-Points verwandeln eine passive Referenz in aktive Constraints. Beide Teile sind wichtig. Der Import allein gibt Claude ein Dokument. Die Anweisungen geben Claude eine Regel.

Den Anschluss vor dem Bauen verifizieren

Nach dem Aktualisieren von CLAUDE.md, bestätige, dass Claude die Werte korrekt geladen hat:

Frag Claude: What primary color is defined in design.md?

Wenn es den richtigen Hex-Wert zurückgibt, funktioniert der Import. Wenn es zögert oder rät, prüfe, ob @design.md am Ende des Blocks steht und der Dateipfad genau stimmt (case-sensitive auf Linux).

Führe diesen Check am Anfang jeder Session mit UI-Arbeit durch. Er dauert zehn Sekunden und fängt einen fehlenden Import ab, bevor er zum Drift-Problem wird.

Eine Tailwind-Enforcement-Schicht hinzufügen

CLAUDE.md ist Kontext. Tailwind ist Enforcement. Die beiden arbeiten zusammen.

Übersetze deine design.md-Token-Werte in tailwind.config.js. Wenn Claude bg-blue-500 statt bg-primary schreibt, schlägt der Build fehl. Das ist das korrekte Verhalten. Ein Typfehler zur Build-Zeit schlägt einen visuellen Widerspruch, den du beim vierten Screen bemerkst.

Ein minimaler Config-Block für eine Zwei-Farben-Marke sieht so aus:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#E07850',
        'primary-dark': '#C5613A',
        surface: '#1A1A1A',
        'surface-elevated': '#1E1B18',
        text: '#FFFFFF',
        'text-muted': '#999999',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
}

Jeder Wert in design.md sollte einen benannten Token in dieser Config haben. Claude schreibt dann Tokens, keine Rohwerte. Der Build fängt alles ab, was durchrutscht.

Sechs Fehlermodi

Das sind die Arten, wie das Setup in der Praxis bricht.

Zu früh exportieren. Stitch generiert Platzhalterfarben und fehlende Zustände, wenn dein Brief dünn ist. Iteriere bis der Output vollständig ist, bevor du exportierst. Lücken in design.md werden zu Lücken in Claudes Constraints.

Vage CLAUDE.md-Anweisungen. Der Import allein reicht nicht. Die vier Bullet-Points im obigen Block verwandeln ein Dokument in ein Regelset. Ohne sie liest Claude die Datei und entscheidet dann, wie viel es davon befolgt.

Keine Tailwind-Übersetzung. Drift, der in einem visuellen Review nach vier Screens entdeckt wird, kostet mehr als ein Build-Fehler, der nach einer Komponente gefunden wird. Füge die Config-Schicht hinzu, bevor du anfängst zu bauen.

design.md nicht in der Versionskontrolle. Wenn sie nicht im Repo ist, startet ein neuer Clone oder ein neues Teammitglied ohne Design-System. Committe die Datei, sobald du sie erstellst.

Veraltete Datei nach dem Redesign. Wenn du die Marke änderst, exportiere neu aus Stitch. Eine design.md, die die Farben des letzten Quartals beschreibt, ist schlimmer als gar keine Datei: Sie gibt Claude zuversichtlich falsche Antworten.

Kontext-Fäulnis in langen Dateien. Informationen in der Mitte eines langen Kontextfensters werden weniger zuverlässig abgerufen als Informationen am Anfang oder Ende. Halte design.md unter 2.000 bis 3.000 Tokens. Teile nach Kategorie auf (Farbe, Typografie, Abstände, Komponenten), wenn die Datei über diesen Umfang wächst.

Alternativen zu Stitch

Stitch ist der schnellste Weg zu einer vollständigen design.md, aber vier andere Ansätze funktionieren.

Manuelle Extraktion aus DevTools. Öffne Chrome DevTools, inspiziere Schlüsselelemente (Buttons, Überschriften, Cards), kopiere das berechnete CSS in Claude, dann frag: Turn this into a design system as a markdown file. Fünf Minuten. Funktioniert gut für bestehende Produkte, bei denen du den aktuellen Zustand erfassen musst, statt ein neues System zu definieren.

awesome-design-md auf GitHub. Die Collection unter github.com/VoltAgent/awesome-design-md hat ab April 2026 60+ Brand-Design-Systeme im DESIGN.md-Format. Wenn du etwas baust, das an eine bestehende Markenästhetik angelehnt ist, starte von einer Referenz und bearbeite sie, statt von Grund auf neu zu generieren.

Figma MCP. Claude Code verbindet sich direkt durch MCP mit Figma und liest Design-Tokens in Echtzeit. Eine Fallstudie von Parallel HQ meldete 62% weniger Design-Inkonsistenzen und 78% bessere Workflow-Effizienz über sechs Monate. Der Tradeoff ist Authentifizierungsaufwand. Stitch exportiert eine selbst enthaltene Datei; Figma MCP erfordert eine Live-Verbindung und Token-Management.

Von einer URL extrahieren. Stitch akzeptiert öffentliche URLs als Input. Füge eine saubere Marketing-Site-URL ein und Stitch liest den visuellen Stil. Funktioniert gut für saubere öffentlich zugängliche Seiten, hat Schwierigkeiten mit authentifizierten Dashboards.

Claude Design vs. design.md

Claude Design startete am 17. April 2026, betrieben von Opus 4.7 mit einem neuen 2.576px-Vision-Modus. Es erstellt visuelle Arbeit durch Konversation und produziert ein Handoff-Bundle innerhalb des Anthropic-Ökosystems. Ein EdTech-Unternehmen berichtete, dass Seiten, die auf anderen Tools 20+ Prompts benötigten, in Claude Design nur 2 brauchten.

Der Unterschied zum design.md-Workflow liegt in der Portabilität. Claude Design produziert Artefakte, die an den Anthropic-Stack gebunden sind. Eine design.md von Stitch ist eine Plain-Datei, die mit jedem Tool funktioniert, das Dateien liest: Claude Code, Cursor, Windsurf oder ein benutzerdefiniertes Build-Skript.

Claude Design ist schneller, wenn du im Anthropic-Ökosystem bleibst. design.md ist besser, wenn du willst, dass das Design-System mit der Codebase reist, versionskontrolliert neben dem Code, den es regelt.

Was du bekommst

Eine Datei im Repo-Root. Vier Zeilen in CLAUDE.md. Benannte Tokens in tailwind.config.js.

Jede Session öffnet mit denselben Design-Constraints im Kontext. Jeder Build schlägt bei Rohwerten fehl, statt Drift akkumulieren zu lassen. Jeder Screen, den Claude berührt, folgt denselben Regeln wie der letzte.

Design-Konsistenz ist kein Review-Prozess. Sie ist eine Datei.

Häufige Fragen

Was ist design.md in Claude Code?

design.md ist eine Plain-Text-Datei in deinem Projekt-Root, die dein Design-System definiert: Farben, Typografie, Abstände, Komponenten-Regeln und Interaktionszustände. Wenn sie in CLAUDE.md mit dem @design.md-Import referenziert wird, lädt Claude Code diese Werte beim Session-Start und behandelt sie als Constraints statt Vorschläge, wodurch jeder Screen sitzungsübergreifend konsistent bleibt.

Wie verwende ich design.md mit Claude Code?

Exportiere eine design.md-Datei von Google Stitch oder schreibe eine manuell, platziere sie in deinem Projekt-Root, dann füge einen ## Design System-Block in CLAUDE.md ein, der den @design.md-Import und vier Bullet-Point-Regeln enthält. Übersetze schließlich deine Token-Werte in tailwind.config.js, damit der Build bei jedem Rohwert fehlschlägt, der das System umgeht.

Ist Google Stitch kostenlos?

Ja, während der Google Labs-Phase. Der Free-Tier unter stitch.withgoogle.com umfasst 350 Generierungen pro Monat mit Zugang zu allen Kernfeatures und erfordert nur ein Google-Konto ohne Warteliste. Stitch 2.0, das den design.md-Export einführte, startete am 18. März 2026. Die Preisgestaltung kann sich ändern, wenn Stitch die Labs-Phase verlässt.

Was ist das awesome-design-md-Repo?

awesome-design-md ist eine GitHub-Collection, die von VoltAgent unter github.com/VoltAgent/awesome-design-md gepflegt wird. Sie enthält 60+ fertige DESIGN.md-Dateien, die an echten Brand-Design-Systemen orientiert sind, darunter Stripe, Linear, Supabase, Vercel und Notion. Du kannst eine direkt als Startpunkt in dein Projekt einfügen und sie an deine Marke anpassen, statt von Grund auf neu zu generieren.

Wie verhindere ich, dass Claude Code mein Design-System ignoriert?

Zwei Dinge sind zusammen, nicht separat, erforderlich. Erstens: Füge den @design.md-Import am Ende des Design-Blocks in CLAUDE.md hinzu, damit die Dateiinhalte beim Session-Start geladen werden. Zweitens: Füge explizite Bullet-Point-Regeln über dem Import hinzu, die Claude anweisen, nur Werte aus der Datei zu verwenden und keine neuen zu erfinden. Der Import allein gibt Claude ein Dokument; die Regeln geben Claude eine Einschränkung.

design.md vs. Figma MCP: Was ist besser für Claude Code?

Sie lösen dasselbe Problem unterschiedlich. Figma MCP verbindet Claude in Echtzeit mit Figma, gibt ihm Zugang zu Live-Design-Tokens und Komponenten, erfordert aber Authentifizierungs-Setup und eine persistente Verbindung. Eine design.md von Stitch ist eine selbst enthaltene Datei, die offline funktioniert, mit dem Repo reist und neben deinem Code versionskontrolliert wird. Figma MCP eignet sich für Teams, die tief in Figma stecken; design.md eignet sich für Solo-Builder, die null Infrastruktur wollen.