DESIGN.md – Design Contract Workflow

design-md · DESIGN.md Design Contract Workflow

Design-Entscheidungen aus verstreuten Styles extrahieren und in einer DESIGN.md zusammenführen – einem Design Contract, den sowohl AI-Agents als auch Menschen lesen können. Dieses Skill deckt den gesamten Kreislauf ab:

Recherche (optional mit Internet) → Extraktion (extract) → Generierung (scaffold) → Anwendung in Code → Verifikation (verify) → CI-Gate

DESIGN.md ist ein von Google Stitch eingeführtes Konzept: Eine reine Text-Design-System-Dokumentation im Projektstammverzeichnis, die sicherstellt, dass die UI-Ausgabe jedes AI-Coding-Agents visuell konsistent bleibt. AGENTS.md regelt „wie gebaut wird“, DESIGN.md regelt „wie es aussieht“.

Verzeichnisstruktur

Pfad	Zweck
scripts/wcag.py	WCAG-2.1-Kontrast-Engine: Parst tokens.css / design-tokens.json, berechnet Paare automatisch gemäß Konvention (Text 4.5:1, UI 3:1), Exit-Code kann direkt als CI-Gate verwendet werden
scripts/extract.py	Extrahiert Design-Token-Entwürfe von einer beliebigen URL (Farbhierarchie / Font-Stacks / Border-Radius), produziert tokens-draft.json + DESIGN.draft.md-Gerüst
scripts/scaffold.py	Generiert auf Knopfdruck aus einem Token-JSON: tokens.css (Dual-Form-Tokens) + tailwind.extend.js + preview.html (visuelles Verzeichnis) + Contrast-Report
scripts/fetch_ref.py	Holt Referenz-DESIGN.md aus awesome-design-md (84 Marken, raw → gh API Dual-Channel-Fallback)
scripts/research.py	DeepSeek Search/Fetch Internet-Recherche (kostenpflichtig, standardmäßig deaktiviert: erfordert explizite Zustimmung des Benutzers und --yes-billing; Key wird aus lokaler Datei / Umgebungsvariable gelesen, niemals ausgegeben)
references/spec.md	DESIGN.md-Dateispezifikation: Frontmatter + YAML-Tokens + 11 Abschnitte + Formatierungsregeln
references/lessons.md	Sammlung von Lessons Learned: Dual-Form-Tokens, Alpha-Verdünnungsfalle, Accent-Aufteilung, Data Contracts (aus realen Produktionsaudits)
references/research.md	DeepSeek Search/Fetch API-Verwendung + awesome-design-md Referenzbibliotheksverzeichnis (84 Slugs)
references/verify.md	Verifikations-Checkliste + CI-Vorlage (npm script / GitHub Actions)
templates/design-tokens.example.json	Direkt ausführbares Eingabebeispiel (Dual-Theme, alle AA-Bestanden, einfach anpassen)

Schnellstart

# 0) Umgebung: python3 ≥ 3.9, nur Standardbibliothek
python3 scripts/wcag.py --help

# 1) Recherche (optional): Token-Entwurf von einer Referenzseite extrahieren
python3 scripts/extract.py --url https://example.com --out-dir ./design-draft
#    → design-draft/tokens-draft.json + design-draft/DESIGN.draft.md

# 2) Ein bekanntes Marken-DESIGN.md als Referenz holen (als Inspiration, nicht zum Kopieren)
python3 scripts/fetch_ref.py --list                 # Alle 84 Slugs anzeigen
python3 scripts/fetch_ref.py --slug linear.app      # → ./DESIGN.reference-linear.app.md

# 2b) (Optional) DeepSeek Internet-Recherche – kostenpflichtig (5 ¥ / 1000 erfolgreiche Requests), standardmäßig deaktiviert:
#     Nur ausführen, wenn der Benutzer explizit zugestimmt hat; Key wird von lokaler Datei bereitgestellt, niemals in Chat/Logs
python3 scripts/research.py --yes-billing check     # Key verifizieren (liest standardmäßig %USERPROFILE%\.deepseek\api_key)
python3 scripts/research.py --yes-billing search --query "fintech dashboard design site:dribbble.com" --count 8

# 3) Vollständiges Token-Projekt generieren (Eingabe: Ihr abgestimmtes Token-JSON)
python3 scripts/scaffold.py --tokens my-tokens.json --out ./design-out
#    → tokens.css / design-tokens.json / tailwind.extend.js / preview.html / contrast-report.txt

# 4) Verifikation (eigenständig oder in CI)
python3 scripts/wcag.py --tokens ./design-out/tokens.css     # CSS-Eingabe
python3 scripts/wcag.py --tokens ./design-out/design-tokens.json   # JSON-Eingabe
python3 scripts/wcag.py --pair "#E6E9EF:#0A0C10:4.5"         # Einzelfarbpaar-Schnelltest

Standard-Workflow (Ausführungsreihenfolge für den Agenten)

1. Anforderungen ermitteln: Projektstatus lesen (gibt es DESIGN.md / Tokens / Komponentenbibliothek?), Themenrichtung klären (Dark-First? Markenfarben? Branche – Finance/DevTools/Medical…).
2. Recherchieren (optional): Methoden aus references/research.md nutzen – DeepSeek Search für Referenzseiten (kostenpflichtig und standardmäßig deaktiviert: Benutzer zuerst über Kosten informieren und explizite Zustimmung einholen, erst dann --yes-billing verwenden; ohne Zustimmung immer internes Crawling), DeepSeek Fetch / internes Crawling zum Umwandeln der Seite in Markdown für detaillierte Analyse; 1–3 branchenspezifische DESIGN.md aus awesome-design-md holen.
3. Extrahieren/Entwerfen: extract.py erzeugt Entwurf → gemäß references/spec.md 11-Abschnitts-Struktur manuell/Agent Rollen zuweisen (z. B. „#5e6ad2 200 mal vorkommend“ → „Primäre Markenfarbe für CTA und Fokus-Ringe“).
4. Generieren: Zu einem korrekten Token-JSON zusammenstellen → scaffold.py produziert das vollständige Projekt (inkl. Vorschauseite für den Benutzer).
5. Anwenden: tokens.css / Tailwind-Mapping ins Projekt einbinden; Komponenten gemäß DESIGN.md §4 Komponentenregeln implementieren.
6. Verifizieren: wcag.py komplett grün + references/verify.md Checkliste Punkt für Punkt abarbeiten; Gate in CI einbinden (siehe verify.md-Vorlage).
7. Iterieren: Jede Farbänderung → wcag.py erneut ausführen, nicht nach Augenmaß; Design-Entscheidungsänderungen in DESIGN.md zurückschreiben (mit Versionsvermerk).

Harte Regeln (unbedingt einhalten)

1. Kontrast nicht nach Augenmaß: Jede Farbänderung erfordert wcag.py. Text ≥4.5:1, UI-Steuerelemente/Rahmen ≥3:1.
2. Dual-Form-Tokens: Jede Farbe gleichzeitig als --x (hex) und --x-rgb (Kanäle) ausgeben, sonst funktionieren Tailwind-Transparenz-Modifikatoren stillschweigend nicht (siehe lessons.md #1).
3. Keine Alpha-Verdünnung (bg-{warn}/10) für helle Hintergründe – helle Hintergründe müssen eigenständige Tokens sein (--warn-soft). Erfahrungsgemäß verschlechtert Verdünnung den Kontrast in hellen Themes.
4. Markenfarben in zwei Stufen aufteilen: --accent (Text/Links) und --accent-solid (Vollflächige Buttons). Derselbe Wert kann unmöglich gleichzeitig „helle Schrift auf dunklem Hintergrund“ und „dunkler Hintergrund unter weißer Schrift“ mit ≥4.5:1 erfüllen.
5. Interaktive Ränder mit --border-strong (3:1), --border nur für dekorative Trennlinien.
6. Known Gaps ehrlich kennzeichnen: Nicht extrahierte Aspekte (Formular-Fehlerzustand, helle Variante, private Font-Substitutionen) in DESIGN.md vermerken, nicht Vollständigkeit vorgeben.
7. Referenz ≠ Kopie: awesome-design-md analysiert öffentliche CSS-Merkmale von Marken; beim Zitieren deren „Methoden“ (Hierarchie, Rhythmus, Abwägungen) lesen, nicht die Markenidentität vortäuschen; bei kommerziellen Projekten Rechte an Logos und Schriftlizenzen beachten.

Sicherheit

• Niemals API-Keys ausgeben. Key-Auflösungsreihenfolge: --key-file → Umgebungsvariable DEEPSEEK_API_KEY → Umgebungsvariable DEEPSEEK_API_KEY_FILE → Standarddatei %USERPROFILE%\.deepseek\api_key (empfohlen: Benutzer erstellt sie selbst im Terminal, Key durchläuft nicht den Chat/Logs). research.py maskiert die gesamte Ausgabe mit sk-***.
• Kostenschutz (standardmäßig deaktiviert, Stand 2026-10): DeepSeek Search/Fetch sind direkt abrechnende APIs (je 5 ¥ / 1000 erfolgreiche Requests; Account-Level Search 100 QPS / Fetch 25 QPS). research.py verweigert ohne --yes-billing (und wenn die Umgebungsvariable DEEPSEEK_BILLING_CONSENT nicht 1 ist) die Ausführung (exit 3) – der Agent muss dem Benutzer zuerst die Kosten erklären und explizite Zustimmung einholen, bevor das Flag gesetzt wird; OpenCode usw. nutzungsbasierte Umgebungen gelten standardmäßig als nicht zugestimmt.
• Ohne konfigurierten Key wird nicht angenommen, dass „Internet zwingend erforderlich“ ist – extract.py verwendet lokales urllib-Crawling, DeepSeek ist nur eine Ergänzung.
• Crawling respektiert robots und Zugriffsraten; extract.py crawlt standardmäßig maximal 5 Stylesheets, max. 512 KB pro Datei.

Beziehungen zu anderen Fähigkeiten

• awesome-design-md (VoltAgent, MIT): Analyse-Sammlung von 84 echten DESIGN.md-Dateien. Dieses Skill bietet fetch_ref.py für den sofortigen Zugriff; es ist die „Referenzmaterial-Bibliothek“, dieses Skill ist die „Workflow-Engine“.
• DeepSeek Search/Fetch: https://api.deepseek.com/v1/tools/search|fetch. Echtzeit-Websuche und Inhaltsabruf für die Design-Recherche-Phase (mit site:/lang:/after:-Syntax). Nutzungsbasiert (5 ¥ / 1000 erfolgreiche Requests – nur „Rückgabe 200 und nicht-leeres Ergebnis“ wird abgerechnet; Fehler/Timeout/leere Ergebnisse sind kostenlos). Account-Level Ratenlimit Search 100 QPS / Fetch 25 QPS (Überschreitung gibt 429 zurück, research.py führt automatische Backoff-Retrys durch). Dieses Skill bietet scripts/research.py als Wrapper (Key niemals ausgegeben; standardmäßig deaktiviert – erfordert explizite Zustimmung des Benutzers und --yes-billing, siehe §Sicherheit).
• Google Stitch offizieller Linter (optional): npx @google/design.md lint DESIGN.md.