Claude Code Design System: 50 Screens, ein Look

Am Montag hast du Claude Code um eine Einstellungsseite gebeten, am Dienstag um eine Abrechnungsseite und am Mittwoch um einen Onboarding-Flow. Jede sieht für sich gut aus. Nebeneinander haben die Buttons drei verschiedene Höhen, eine Seite hat 8px-Ecken, eine andere 12px, und auf der Abrechnungsseite taucht ein Blau auf, das du nie ausgesucht hast. Ein Claude Code Design System löst das, indem der Agent in jeder Session dieselben exakten Werte bekommt: Tokens, Größentabellen, Komponentenregeln und einen Check, der ihm sagt, wann er abgewichen ist.

In diesem Tutorial baust du das Setup für eine App mit Next.js und Tailwind CSS v4 auf. Die Beispiele nutzen Button, UIProvider und Tones von Wingo UI, weil wir dasselbe Setup in unserem eigenen Repository einsetzen. Dort regelt eine einzige Design-Datei einen Katalog mit 352 Einträgen (Stand Oktober 2026). Der Aufbau funktioniert mit jeder Komponentenbibliothek. Weitere Guides zu Agenten und UI findest du unter UI mit KI-Agenten bauen.

Warum laufen Screens aus Claude Code auseinander?

Jede Session startet ohne Erinnerung an die letzte. Wenn im Prompt nur „eine Einstellungsseite“ steht und nichts im Kontext festlegt, wie hoch ein Button ist, wählt Claude Code einen vernünftigen Wert. Die nächste Session wählt einen anderen vernünftigen Wert. Jede Entscheidung lässt sich begründen. Fünfzig davon ergeben ein Produkt, das aussieht, als hätte jemand es aus fünf Kits zusammengesetzt.

Regeln in Prosa helfen weniger, als man denkt. „Halte die Abstände einheitlich“ nennt keine Zahl, der Agent hat also nichts, was er übernehmen kann. Eine Regel wie „Buttons sind 32, 40 oder 48px hoch, Standard ist md“ gibt ihm eine.

Auch Memory-Dateien allein schließen die Lücke nicht. Die Memory-Docs von Claude Code (opens in a new tab) (Oktober 2026) beschreiben die CLAUDE.md als Kontext für Claude. Konkrete und knappe Anweisungen werden laut den Docs zuverlässiger befolgt, und für alles, was unabhängig von Claudes Entscheidung passieren muss, ist ein Hook das richtige Werkzeug. Deshalb legt dieses Setup die Werte in den Code und ergänzt Checks.

Viele installieren zuerst den Claude Code Frontend Design Skill. Er ist ein offizielles Plugin im Repository anthropics/claude-code (opens in a new tab) (Version 1.1.0, Stand Oktober 2026, von Prithvi Rajasekaran und Alexander Bricken), und seine Beschreibung nennt ihn eine Anleitung für ein unverwechselbares, bewusst gestaltetes visuelles Design. Seine Anweisungen lassen Claude als Design Lead eines Studios auftreten, für jedes Briefing eine eigene Palette und eigene Schriften wählen und vor der ersten Zeile Code einen Plan mit vier bis sechs benannten Farben schreiben. Für eine neue Landingpage mit eigener Identität ist das das richtige Briefing. Für den 37. Screen einer App, die schon eine Identität hat, ist es das falsche, und der Skill deckt die Arbeit innerhalb bestehender Tokens oder Komponenten nicht ab. Für Produkt-Screens müssen deine Regeln aus deinen eigenen Dateien kommen.

Was gehört in ein Claude Code Design System?

Fünf Bausteine, jeder an der Stelle, an der er am schwersten zu übersehen ist:

1. Tokens im CSS. Farben, Elevation und Ebenen als CSS-Variablen, Tailwind-Klassen zugeordnet. So schreibt der Agent bg-surface, und beide Themes funktionieren.
2. Eine DESIGN.md mit Tabellen. Größen, Radius pro Größe, Typo-Skala und Abstände als Zahlen, dazu die Prop-Namen, die jede Komponente nutzt.
3. Komponenten, die die Tabellen enthalten. Die Maps für Größe und Radius stecken in der Komponente. <Button size="sm"> stimmt also, ohne dass der Agent einen einzigen Pixelwert kennt.
4. Defaults im Code. App-weite Entscheidungen einmal in einem Provider gesetzt. Das kürzeste JSX, das der Agent schreiben kann, ist dann auch das richtige.
5. Checks. Ein Hook nach jeder Änderung und ein Skript über alle Routen, damit Abweichungen als Fehler beim Agenten landen.

So sieht das Projekt am Ende aus:

your-app/
├── CLAUDE.md                          # @AGENTS.md, sonst nichts
├── AGENTS.md                          # kurz: Befehle, wo was liegt, "read docs/DESIGN.md"
├── docs/DESIGN.md                     # die Tabellen
├── app/globals.css                    # die Tokens
├── app/layout.tsx                     # UIProvider-Defaults
├── .claude/skills/product-ui/SKILL.md # lädt bei jeder UI-Aufgabe
├── .claude/hooks/check-ui.sh          # läuft nach jedem Edit oder Write
├── .claude/settings.json              # registriert den Hook
└── scripts/ui-inventory.ts            # Buttons pro Route, über die ganze App

Schritt 1: Wie gibst du Claude Code deine Design Tokens?

Leg sie ins CSS, wo der Agent sie liest und der Browser sie durchsetzt. In Tailwind CSS v4 heißt das: einfache CSS-Variablen pro Theme und ein @theme inline-Block, der daraus Utilities macht. Hier eine gekürzte Fassung unserer Datei, ohne die meisten Tokens und einige Schatten-Ebenen:

:root {
  --background: oklch(1 0 0);
  --surface: #ffffff;
  --brand: #d63f00;
  --elevation-raised: 0 0 0 1px rgb(0 0 0 / 0.07), 0 1px 2px rgb(0 0 0 / 0.05);
  --z-popover: 1400;
}

.dark {
  --background: oklch(0 0 0);
  --surface: #1a1a1a;
  --elevation-raised: inset 0 1px 0 0 rgb(255 255 255 / 0.06), 0 0 0 1px rgb(255 255 255 / 0.08);
}

@theme inline {
  --color-background: var(--background);
  --color-surface: var(--surface);
  --color-brand: var(--brand);
  --shadow-raised: var(--elevation-raised);
  --z-index-popover: var(--z-popover);
}

Jetzt ist bg-surface shadow-raised in beiden Themes eine abgehobene Karte, und z-popover ist eine Ebene mit Namen. Die semantischen Namen zählen mehr als die Werte: Ein Agent, der bg-surface schreibt, kann kein falsches Grau erwischen. Den kompletten Ansatz mit Dark Mode und Kontrast-Checks findest du in Tailwind v4 Design Tokens.

Schritt 2: Was gehört in eine Claude Code DESIGN.md?

Zahlen in Tabellen, und zu jeder Regel, die willkürlich wirkt, der Grund dafür. Unsere docs/DESIGN.md beginnt mit dem Hinweis, dass die Zahlen Entscheidungen sind. Wer etwas braucht, das die Datei nicht abdeckt, soll das nächstliegende Muster übernehmen und das auch sagen. Diese eine Anweisung verhindert die meisten erfundenen Werte.

Die Größentabelle sorgt dafür, dass Screens zusammenpassen: Button, Input und Select stehen nur dann bündig nebeneinander, wenn alle drei dieselbe Tabelle nutzen:

## Größen

`size="sm" | "md" | "lg"`, Standard `md`. Jedes Control mit einer Höhe nutzt diese Tabelle.

|                  | sm                        | md                         | lg             |
| ---------------- | ------------------------- | -------------------------- | -------------- |
| Höhe             | 32px `h-8`                | 40px `h-10`                | 48px `h-12`    |
| Auf Touchscreens | 32px + 44px Trefferfläche | 44px `pointer-coarse:h-11` | 48px           |
| Padding (Button) | `px-3`                    | `px-4`                     | `px-5`         |
| Schrift          | `text-[13px]`             | `text-sm`                  | `text-[15px]`  |
| Icon             | `size-3.5`                | `size-4`                   | `size-[18px]`  |
Radius pro Größe (Prop `radius`, Standard `md`), für die Größen sm / md / lg: `md` 8 / 10 / 12px, `lg` 10 / 14 / 16px, `full` eine Pille.

## Regeln

- Jeder `tone` ist standardmäßig `neutral`. `tone="brand"` ist opt-in, höchstens einmal pro Screen, für die Hauptaktion.
- Ein Solid-Button pro Ansicht. Nebenaktionen nutzen `soft` oder `outline`.
- Farbiger Text ist `text-<tone>-soft-foreground`, nie `text-<tone>`: Füllfarben sind für Flächen abgestimmt.

Unsere DESIGN.md hat 614 Zeilen. Deshalb verlinkt die AGENTS.md sie („Read docs/DESIGN.md before building anything“), statt sie in jede Session zu importieren. Wie CLAUDE.md, AGENTS.md und Imports geladen werden, erklärt AGENTS.md vs CLAUDE.md.

Wenn du deine Tokens lieber in einem Standardformat halten willst: Die Organisation google-labs-code veröffentlicht ein offenes DESIGN.md-Format (opens in a new tab). Es besteht aus YAML-Frontmatter mit Tokens für Farben, Typografie, Rundungen und Abstände, danach folgen Markdown-Abschnitte mit der Begründung. Die zugehörige CLI (npx @google/design.md lint DESIGN.md) meldet kaputte Token-Referenzen und WCAG-Kontrastprobleme als JSON und beendet sich bei Fehlern mit Exit-Code 1. Stand Oktober 2026 ist das Format in Version alpha, rechne also mit geänderten Feldnamen.

Schritt 3: Wie halten Komponenten das Claude Code UI Design einheitlich?

Indem die Tabellen in den Komponenten selbst stecken, sodass der Agent nur noch einen Namen wählt. Claude Code UI Design wird am schnellsten einheitlich, wenn size, variant, tone und radius die einzigen offenen Entscheidungen sind. In unserem Button steckt die Größentabelle als Map in der Datei:

// 32 / 40 / 48px. bei grobem zeiger (touch) wächst md auf 44px, sm behält seinen look und bekommt eine 44px trefferfläche
const SIZES: Record<ButtonSize, string> = {
  sm: "h-8 gap-1.5 px-3 text-[13px] pointer-coarse:after:absolute pointer-coarse:after:inset-x-0 pointer-coarse:after:-inset-y-1.5",
  md: "h-10 gap-2 px-4 text-sm pointer-coarse:h-11",
  lg: "h-12 gap-2 px-5 text-[15px]",
  "icon-sm": "size-8 pointer-coarse:after:absolute pointer-coarse:after:-inset-1.5",
  icon: "size-10 pointer-coarse:size-11",
  "icon-lg": "size-12",
};

Farben laufen über eine weitere Ebene. Jede Komponente mit einem tone-Prop färbt sich über fünf CSS-Variablen ein (--tone, --tone-foreground, --tone-soft, --tone-soft-foreground, --tone-border), die Tones aus den Design Tokens setzt oder per colorVars aus einer beliebigen CSS-Farbe ableitet. Eine Regel in der DESIGN.md kann dann „tone“ sagen und muss nie eine Farbe nennen.

App-weite Entscheidungen gehören ins Root-Layout. Jede Komponente von Wingo UI liest ihre Defaults über useDefaults unter ihrem data-slot-Namen, und explizite Props haben weiterhin Vorrang:

// app/layout.tsx
import type { ReactNode } from "react";
import { UIProvider } from "@/lib/ui-config";
import "./globals.css";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UIProvider locale="en-US" defaults={{ button: { radius: "full" } }}>
          {children}
        </UIProvider>
      </body>
    </html>
  );
}

Danach ist <Button>Änderungen speichern</Button> auf jedem der 50 Screens eine Pille, und der Agent musste sich das nie merken.

Schritt 4: Wie lädst du die Regeln für jede UI-Aufgabe?

Mit einem Projekt-Skill. Claude Code liest Skills aus .claude/skills/<name>/SKILL.md. Nur die description steht die ganze Zeit im Kontext. Der Inhalt wird erst geladen, wenn Claude entscheidet, dass die Aufgabe passt, oder wenn du /product-ui tippst. Die Skills-Docs (opens in a new tab) von Anthropic empfehlen, die SKILL.md unter 500 Zeilen zu halten und Referenzmaterial in eigene Dateien auszulagern. Das passt zu einem Design System: Der Skill ist die Checkliste, die DESIGN.md die Referenz.

---
name: product-ui
description: Regeln für jeden Screen, jede Seite, jedes Formular, jeden Dialog und jede Komponente dieser App, beim Bauen und beim Ändern. Vor jedem UI-Code und vor jedem Review eines Screens nutzen.
---

# Product UI

Diese App hat ein einziges Design System. Halte dich daran; erfinde nie einen Wert.

1. Lies die Abschnitte von docs/DESIGN.md, die du brauchst: Tokens, Größen, Radius, Typo und Abstände, Props.
2. Bau aus components/ui. Konfiguriere über Props (size, variant, tone, radius, classNames), bevor du Klassen ergänzt.
3. Wiederhole keine app-weiten Defaults (sie liegen im UIProvider in app/layout.tsx). Übergib ein Prop nur dort, wo eine Instanz abweicht.
4. Nur semantische Farbklassen: bg-background, bg-surface, bg-card, bg-popover, bg-foreground/5, text-foreground, text-muted-foreground, border-border.
5. Ein Solid-Button pro Ansicht. tone="brand" höchstens einmal pro Screen, für die Hauptaktion.
6. Deckt DESIGN.md etwas nicht ab, übernimm das nächstliegende bestehende Muster und nenn es in deiner Zusammenfassung.
7. Bevor du fertig bist: Führ `npm run ui:inventory` aus und behebe jeden Befund.

Nutzt du Wingo UI, schreibt npx wingo-ui@latest agents install claude die Datei .claude/skills/wingo-ui/SKILL.md mit der bibliothekseigenen Fassung dieser Regeln, dazu .mcp.json und einen markierten Block in der CLAUDE.md. Die Tools get_design_rules und get_theme_tokens des MCP-Servers liefern die aktuellen Regeln und CSS-Variablen. Die Doku zu Coding-Agenten listet jede Datei, die der Befehl schreibt.

Schritt 5: Wie prüfst du, ob Claude Code das Design System eingehalten hat?

Mit zwei Checks: einem pro Datei, direkt nach jeder Änderung, und einem über die ganze App, bevor du die Arbeit für fertig erklärst. Einheitliche UI mit KI-Agenten hängt an diesem Schritt. Eine Regel, die der Agent überspringt, kommt so noch in derselben Session als Fehler zu ihm zurück, statt eine Woche später in deinem Review.

Jede bearbeitete Datei mit einem Hook prüfen

Ein PostToolUse-Hook läuft nach jedem Edit oder Write. Er bekommt den Tool-Aufruf als JSON auf stdin, mit dem Pfad in tool_input.file_path. Die Änderung ist zu diesem Zeitpunkt schon passiert, Exit-Code 2 kann sie also nicht blockieren. Laut der Hooks-Referenz (opens in a new tab) gibt Claude Code dann aber die stderr-Ausgabe des Hooks an Claude weiter, und Claude korrigiert die Datei. Exit-Code 0 verbirgt stderr vor Claude. Registrier den Hook in .claude/settings.json (das Array args startet das Skript direkt ohne Shell, was die Docs für Pfade mit ${CLAUDE_PROJECT_DIR} empfehlen):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-ui.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Das Skript durchsucht die bearbeitete Datei per grep nach Werten außerhalb des Systems. Das Muster ist aus dem Drift-Check am Ende unserer eigenen DESIGN.md übernommen, ergänzt um Hex- und Paletten-Farben:

#!/usr/bin/env bash
# .claude/hooks/check-ui.sh: meldet werte außerhalb von docs/DESIGN.md in der datei, die claude gerade bearbeitet hat
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in *.tsx) ;; *) exit 0 ;; esac
# der quellcode der bibliothek behält hex-farben als überschreibbare prop-defaults
case "$file" in */components/ui/*|*/components/blocks/*) exit 0 ;; esac

colors='#[0-9a-fA-F]{6}|-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}'
system='rounded-(sm|md|lg|xl)([^-]|$)|bg-(accent|secondary)([^-]|$)|z-[0-9]|text-(destructive|brand|success|warning|info)([^-]|$)'

if hits=$(grep -nE "$colors|$system" "$file"); then
  echo "Abweichung vom Design System in $file:" >&2
  echo "$hits" >&2
  echo "Nutze die Tokens, Größen- und Radius-Tabellen aus docs/DESIGN.md oder ein Prop der Komponente." >&2
  exit 2
fi
exit 0

Mach das Skript mit chmod +x .claude/hooks/check-ui.sh ausführbar; es braucht jq. Jedes Muster steht für eine Regel: Paletten-Klassen umgehen die Tokens, rounded-lg und Co. liegen außerhalb der Radius-Tabelle, z-50 überspringt die benannten Ebenen, und text-destructive nutzt eine Füllfarbe als Textfarbe, die auf einer dunklen Karte unter das WCAG-AA-Niveau fällt.

Jede Route inventarisieren

Der grep-Check erkennt weder eine Seite mit vier Solid-Buttons noch einen Screen, auf dem jede Aktion orange ist. Das gerenderte DOM schon. Unser Button schreibt seine Entscheidungen in Attribute (data-slot="button", data-variant, data-tone, data-size), also kann ein kurzes Playwright-Skript sie auf jeder Route zählen:

// scripts/ui-inventory.ts: npx tsx scripts/ui-inventory.ts (bei laufendem dev-server)
import { chromium } from "playwright";

const BASE = process.env.BASE_URL ?? "http://localhost:3000";
const ROUTES = ["/", "/dashboard", "/settings", "/billing", "/onboarding"];

async function main() {
  const browser = await chromium.launch();
  const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
  const findings: string[] = [];

  for (const route of ROUTES) {
    await page.goto(BASE + route, { waitUntil: "networkidle" });
    const buttons = await page.$$eval('[data-slot="button"]', (els) =>
      els
        .filter((el) => el.getClientRects().length > 0)
        .map((el) => ({
          variant: el.getAttribute("data-variant") ?? "",
          tone: el.getAttribute("data-tone") ?? "",
          size: el.getAttribute("data-size") ?? "",
        })),
    );

    const solid = buttons.filter((b) => b.variant === "solid").length;
    const brand = buttons.filter((b) => b.tone === "brand").length;
    const custom = buttons.filter((b) => b.tone === "custom").length;
    const sizes = [...new Set(buttons.map((b) => b.size))].join(", ");

    console.log(`${route}: ${buttons.length} Buttons, ${solid} solid, ${brand} brand, Größen ${sizes || "keine"}`);
    if (solid > 1) findings.push(`${route}: ${solid} Solid-Buttons, die Regel ist einer pro Ansicht`);
    if (brand > 1) findings.push(`${route}: ${brand} Brand-Buttons, brand ist für die eine Hauptaktion`);
    if (custom > 0) findings.push(`${route}: ${custom} Buttons mit einem eigenen color-Prop`);
  }

  await browser.close();
  if (findings.length > 0) {
    console.error(findings.join("\n"));
    process.exit(1);
  }
}

main();

Installier die Abhängigkeiten mit npm i -D playwright tsx und npx playwright install chromium und ergänze "ui:inventory": "tsx scripts/ui-inventory.ts" in der package.json, damit der Skill den Befehl nennen kann. Die Regel „ein Solid-Button“ gilt pro Ansicht. Eine Seite mit offenem Dialog kann also zu Recht durchfallen. Nimm diese Zeile als Anlass zum Hinschauen, und schränk ROUTES oder den Selektor ein, wenn eine Seite eine Ausnahme verdient. Jede Komponente von Wingo UI trägt einen data-slot. Select, Badge, Toggle und Tabs schreiben zusätzlich data-size und data-variant, das Skript lässt sich also mit einem anderen Selektor auf sie erweitern. Prüf die Datei der Komponente, bevor du eine neue zählst: Input zum Beispiel schreibt kein data-size.

Schau dir die Screens danach selbst an. Mach von jeder Route Screenshots bei 390px und 1440px Breite, im Light und im Dark Mode, und leg sie nebeneinander. Eine Tabelle mit Zahlen verrät dir nicht, dass zwei Empty States verschiedene Icons nutzen.

Wo fängst du an?

Fang mit der Größentabelle an. Schreib sie in docs/DESIGN.md, lass einen Projekt-Skill darauf verweisen und ergänze den Hook. Ab dem nächsten Screen bekommt Claude Code für jeden Radius außerhalb der Tabelle, jeden rohen z-index und jede Paletten-Farbe einen Fehler. Verschieb danach die Defaults, die du ständig wiederholst, in den Provider, und lass das Inventar vor jedem Merge laufen.

Button, UIProvider und Tones aus diesem Tutorial sind kostenlos:

npx wingo-ui@latest add button ui-config tones

Für die Serverseite dieses Setups, bei der der Agent echte Props nachschlägt, statt sie zu raten, lies den Guide zum MCP-Server für Komponentenbibliotheken und die MCP-Doku.

Häufige Fragen

Wie bringe ich Claude Code dazu, mein Design System einzuhalten?

Leg die Werte dort ab, wo Claude Code sie nicht übersehen kann: Farb-Tokens in deinem CSS, exakte Tabellen in einer DESIGN.md, auf die ein Projekt-Skill verweist, und app-weite Defaults im Code über einen Provider. Ergänze dann einen PostToolUse-Hook, der jede bearbeitete Datei prüft, damit Claude Abweichungen noch in derselben Session gemeldet bekommt.

Soll ich den Claude Code Frontend Design Skill für Produkt-Screens nutzen?

Nutz ihn für neue Seiten, die einen eigenen Look brauchen. Seine Anweisungen verlangen pro Briefing eine eigene Palette und eigene Schriften, also genau das Gegenteil von dem, was Screen 37 eines bestehenden Produkts braucht. Für Produktarbeit gilt deshalb deine eigene DESIGN.md.

Was gehört in eine DESIGN.md für Claude Code?

Exakte Tabellen, die ein Agent übernehmen kann: Flächen und Textstufen, die Größentabelle (Höhe, Padding, Schrift, Icon pro Größe), der Radius pro Größe, die Typo-Skala, die Abstandsstufen und die Prop-Namen deiner Komponenten. Regeln ohne Zahlen wie „halte die Abstände einheitlich“ geben dem Agenten nichts, was er übernehmen kann.

Wie prüfe ich, ob KI-generierte Screens einheitlich sind?

Lass auf jeder bearbeiteten Datei ein grep nach Werten außerhalb des Systems laufen (Hex-Farben, Paletten-Klassen, Radien außerhalb der Tabelle, rohe z-index-Werte) und ein Browser-Skript, das die Buttons jeder Route nach Variante, Ton und Größe zählt. Schau dir danach Screenshots bei 390px und 1440px Breite in beiden Themes an.

Reicht eine CLAUDE.md allein?

Nein. Laut den Memory-Docs von Anthropic behandelt Claude die CLAUDE.md als Kontext, und für alles, was unabhängig von Claudes Entscheidung passieren muss, verweisen die Docs auf Hooks. Defaults im Code und Checks nach jeder Änderung greifen, egal was das Modell wählt.