# Claude Code Design System: 50 Screens, ein Look > Claude Code Design System einrichten: Tokens, Größentabellen und Komponentenregeln für den Agenten, dazu Checks, die zeigen, ob 50 Screens zusammenpassen. - Autor: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI - Veröffentlicht: 16. Okt. 2026 - Kategorie: [UI mit KI-Agenten bauen](https://wingo-ui.com/de/blog/category/ai-agents) - Lesezeit: 12 Min. - Kanonische URL: https://wingo-ui.com/de/blog/claude-code-design-system - Englische Fassung: https://wingo-ui.com/blog/claude-code-design-system ## Kurz gesagt Ein Claude Code Design System legt exakte Werte dort ab, wo der Agent sie nicht übersehen kann: Farb-Tokens im CSS, eine DESIGN.md mit Tabellen für Größen, Radius und Schrift, und Komponenten, deren Props und Provider-Defaults diese Tabellen schon enthalten. Eine kurze CLAUDE.md und ein Projekt-Skill verweisen Claude Code auf die Regeln. Ein PostToolUse-Hook, der jede bearbeitete Datei per grep prüft, und ein Skript, das die Buttons auf jeder Route zählt, fangen ab, was trotzdem abweicht. 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](https://wingo-ui.com/components/button), [UIProvider](https://wingo-ui.com/components/ui-config) und [Tones](https://wingo-ui.com/components/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](https://wingo-ui.com/de/blog/category/ai-agents). ## 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](https://code.claude.com/docs/en/memory) (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`](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design) (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. `` auf jedem der 50 Screens eine Pille, und der Agent musste sich das nie merken. > Live-Demo (UIProvider): Der obere Button hat keinen Provider. Der darunter sitzt in einem Provider mit radius full und tone brand, und das Paar unten ergänzt einen verschachtelten Provider mit size sm, der Radius und Ton des äußeren Providers übernimmt. Probier sie unter [UIProvider](https://wingo-ui.com/components/ui-config) aus und installier sie mit `npx wingo-ui@latest add ui-config`. ## Schritt 4: Wie lädst du die Regeln für jede UI-Aufgabe? Mit einem Projekt-Skill. Claude Code liest Skills aus `.claude/skills//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](https://code.claude.com/docs/en/skills) 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. ```md --- 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](https://wingo-ui.com/docs/agents) 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](https://code.claude.com/docs/en/hooks) 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): ```json { "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: ```sh #!/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: ```ts // 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](https://wingo-ui.com/components/button), [UIProvider](https://wingo-ui.com/components/ui-config) und [Tones](https://wingo-ui.com/components/tones) aus diesem Tutorial sind kostenlos: ```sh 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](https://wingo-ui.com/de/blog/component-library-mcp-guide) und die [MCP-Doku](https://wingo-ui.com/docs/mcp). ## Komponenten in diesem Artikel - [Button](https://wingo-ui.com/components/button) (Free): The React button component every screen starts with: five variants, six tones, all sizes, and a loading state that never jumps. Installation: `npx wingo-ui@latest add button` - [UIProvider](https://wingo-ui.com/components/ui-config) (Free): A React config provider for Wingo UI: app-wide default props for every component, the Intl locale and a reduced-motion policy. Installation: `npx wingo-ui@latest add ui-config` - [Tones](https://wingo-ui.com/components/tones) (Free): One way to color a React component: a tone or any CSS color becomes five CSS variables every variant paints with. Installation: `npx wingo-ui@latest add tones` ## 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. --- Quelle: https://wingo-ui.com/de/blog/claude-code-design-system