DESIGN.md Generator

Du bist eine Design-Systems-Engineer. Generiere für das aktuelle Projekt eine spec-konforme DESIGN.md nach dem Format von google-labs-code/design.md (Version alpha).

Die kanonische Spec liegt lokal unter ${CLAUDE_SKILL_DIR}/reference/spec.md — lies sie zu Beginn, wenn du sie nicht im Kopf hast. Ein Skeleton-Template liegt unter ${CLAUDE_SKILL_DIR}/templates/skeleton.md.

Der Skill funktioniert auf beliebigen Projekten: WordPress-Themes (theme.json), Tailwind-Repos (v3 config oder v4 @theme {}), Plain-CSS-Projekte mit :root { --foo }, DTCG tokens.json, oder Greenfield-Projekte ohne Inputs.

Phase 1 — Discover

Identifiziere, welche Design-Inputs das Projekt hergibt. Führe die Probes parallel via Bash aus (alle in einem Block, mit || true damit ein leeres Ergebnis nicht den Block abbricht):

echo "=== theme.json ===" ; find . -maxdepth 5 -name 'theme.json' -not -path '*/node_modules/*' -not -path '*/wp-content/plugins/*' -not -path '*/vendor/*' 2>/dev/null
echo "=== tailwind.config ===" ; find . -maxdepth 4 -type f \( -name 'tailwind.config.js' -o -name 'tailwind.config.ts' -o -name 'tailwind.config.mjs' -o -name 'tailwind.config.cjs' \) -not -path '*/node_modules/*' 2>/dev/null
echo "=== DTCG tokens.json ===" ; find . -maxdepth 4 -name 'tokens.json' -not -path '*/node_modules/*' 2>/dev/null
echo "=== existing DESIGN.md ===" ; find . -maxdepth 4 -iname 'DESIGN.md' -not -path '*/node_modules/*' 2>/dev/null
echo "=== CSS files with @theme or :root ===" ; grep -rl --include='*.css' -E '(@theme[[:space:]]*\{|:root[[:space:]]*\{)' . --exclude-dir=node_modules --exclude-dir=vendor --exclude-dir=wp-content/plugins 2>/dev/null | head -20

Klassifiziere das Projekt anhand der Funde (mehrere Klassen können gleichzeitig zutreffen):

• WordPress-Theme wenn theme.json vorhanden — die Datei ist die primäre Token-Quelle (settings.color.palette, settings.typography.fontSizes, settings.spacing.spacingSizes, styles.*).
• Tailwind v3 wenn tailwind.config.{js,ts,mjs,cjs} vorhanden — Tokens stehen unter theme oder theme.extend.
• Tailwind v4 / Modern CSS wenn ein CSS-File einen @theme { }-Block hat — Tokens sind CSS-Custom-Properties mit Tailwind-v4-Namespaces (--color-*, --font-*, --text-*, --leading-*, --tracking-*, --font-weight-*, --radius-*, --spacing-*).
• Plain CSS wenn nur :root { --foo } ohne Tailwind-Namespaces — eigenes Naming-Schema, manuell mappen.
• DTCG Tokens wenn tokens.json mit $type / $value-Feldern — direkter Token-Import.
• Greenfield wenn nichts davon vorhanden ist — User nach Brand-Inputs fragen (Phase 2).

Lies die gefundenen Quellen ein. Gib dem User in 3–5 Zeilen eine Zusammenfassung dessen, was du gefunden hast, bevor du weitermachst (Token-Counts pro Gruppe, erkannter Projekt-Typ, ob bereits eine DESIGN.md existiert).

Phase 2 — Confirm scope

Nutze AskUserQuestion, um vor dem Schreiben drei Dinge zu klären (kombiniere zu einem einzigen Tool-Call mit mehreren Fragen, sofern relevant):

1. Zielpfad — wo soll die DESIGN.md landen? Default-Optionen:
   • Projekt-Root des aktuellen cwd
   • Theme-/Subprojekt-Verzeichnis falls erkannt (z.B. wp-content/themes/<name>/ bei WP-Sites mit eigenem Theme-Repo)
   • Custom-Pfad
2. Existing DESIGN.md — falls vorhanden: Overwrite / Diff (anzeigen, nicht schreiben) / Skip / In Backup-Datei umbenennen.
3. Brand-Vibe — nur falls Discovery keinen klaren Brand-Kontext liefert (kein CLAUDE.md, keine README, keine Brand-Assets): kurzer Brand-Name + 1–2 Adjektive für Tonfall (z.B. "Heritage, journalistisch, premium").

Bei klarem Discovery-Ergebnis (Tokens vollständig, CLAUDE.md mit Brand-Hinweisen vorhanden) darfst du Phase 2 für Zielpfad und Vibe überspringen und nur bei einer existierenden DESIGN.md nachfragen.

Phase 3 — Extract tokens

Mappe die gefundenen Quell-Tokens auf die DESIGN.md-Token-Gruppen. Eckpunkte:

colors

• Mindestens primary ist erforderlich. Sinnvoll: primary, secondary, tertiary, neutral, plus surface, on-surface, on-surface-variant, error wenn ableitbar.
• Wenn die Quelle nur deskriptive Slugs hat (brand-purple, accent-warm), behalte den Slug als zusätzlichen Token-Eintrag und vergib eine semantische Rolle in einem zweiten Token-Eintrag (z.B. sowohl accent-warm: "#B8422E" als auch tertiary: "{colors.accent-warm}" via Token-Reference).
• Hex-Werte in sRGB. Großschreibung beim Hex-Code spielt keine Rolle für die Spec.

typography

• Übliches Set: display, headline-lg, headline-md, headline-sm, body-lg, body-md, body-sm, label-lg, label-md, label-sm.
• Felder pro Eintrag: fontFamily (string), fontSize (px/em/rem), fontWeight (number), lineHeight (Dimension oder unitless multiplier), letterSpacing (Dimension), optional fontFeature, fontVariation.
• Bei fluiden Werten (clamp(min, ideal, max)): wähle den Mid- oder Max-Wert als Token, dokumentiere das fluide Verhalten in der Prosa unter ## Typography. (Die Spec kennt kein clamp-Primitive.)

rounded

• Map: none, xs, sm, md, lg, xl, full. Werte als Dimension (px/em/rem).
• full typischerweise 9999px oder 100%.

spacing

• Map: xs, sm, md, lg, xl, optional base, gutter, margin. Dimensionen oder unitless-Number (z.B. column-counts).
• WordPress spacingSizes-Array (20, 30, 40...) → mappe auf das xs..xl-Schema in der Reihenfolge.

components

• Optional aber empfohlen, sobald Buttons/Cards/Inputs eine erkennbare Stil-Definition haben.
• Properties pro Component-Eintrag: backgroundColor, textColor, typography, rounded, padding, size, height, width.
• Werte können Token-References sein: "{colors.primary}". Variants als separate Einträge mit -hover, -active, -pressed-Suffix.

Konsistenz-Regel: Verwende Token-References überall, wo es geht ("{colors.tertiary}" statt "#B8422E" zum zweiten Mal). Der Linter erkennt sonst Duplikate als orphaned-tokens.

Phase 4 — Compose Prose

Schreibe die 8 Markdown-Sektionen in canonical order (siehe reference/spec.md):

1. ## Overview (auch erlaubt: "Brand & Style") — Brand-Personality, Zielgruppe, emotionale Wirkung. 3–6 Sätze. Quelle: CLAUDE.md / README / Hero-Microcopy / Logo-Beschreibung.
2. ## Colors — eine Bullet-Liste mit deskriptiven Farbnamen + Hex + Anwendungs-Hinweis pro Token (z.B. **Primary (#1A1C1E):** Deep ink for headlines and core text).
3. ## Typography — Schriftauswahl, Hierarchie-Regeln, evtl. Hinweis auf fluides Skalieren.
4. ## Layout (auch: "Layout & Spacing") — Grid-Modell, Spacing-Skala, Container-Breiten.
5. ## Elevation & Depth (auch: "Elevation") — Shadow-Strategie oder erklärt, warum Flat-Design ohne Shadows.
6. ## Shapes — Corner-Radius-Philosophie.
7. ## Components — kurze Beschreibung jeder Variante (was sie ist, wann sie verwendet wird).
8. ## Do's and Don'ts — 4–8 Bullets, harte Regeln (z.B. "Do maintain WCAG AA contrast", "Don't mix rounded and sharp corners").

Tonfall: sachlich-präzise, ohne Marketing-Floskeln. Schreib auf Englisch — die Spec, alle Beispiele und die LLM-Konsumenten arbeiten auf Englisch. (Auch wenn das Projekt deutsch ist.)

Länge: ein DESIGN.md mit ~150–250 Zeilen Markdown ist normal. Werde nicht ausschweifend.

Phase 5 — Validate

Schreibe die finale Datei mit Write an den in Phase 2 bestätigten Pfad. Validiere danach via offiziellem Linter:

cd <verzeichnis-der-design-md> && npx --yes @google/design.md lint DESIGN.md

Parse das JSON-Output. Reagiere wie folgt:

• Errors (severity error, z.B. broken-ref auf nicht-existente Token-Pfade): Pflicht-Fix. Korrigiere die Datei und re-linte. Maximal 3 Iterationen, danach dem User berichten.
• Warnings (missing-primary, contrast-ratio, orphaned-tokens, `missing-typography