UX.md Generator und Strukturprüfer (v1)
Übersicht
Während DESIGN.md visuelle Tokens (Farben, Typografie, Radien, Schatten, Abstandsskala) festlegt, definiert UX.md das strukturelle Skelett und die Interaktionsregeln einer Anwendung.
Ohne UX.md treiben KI-Codierungsagenten im Laufe der Sitzungen auseinander: Sie mischen Containerbreiten, verschieben primäre CTAs, wechseln willkürlich zwischen Modals und Drawern, lassen leere oder Fehlerzustände aus, verlieren Filterstatus beim F5-Refresh und führen Sackgassenrouten ein.
Dieses Skill arbeitet in vier Modi und nutzt eine Drei-Phasen-Pipeline, die auf sechs null-Abhängigkeit-Node.js-Skripten in scripts/ basiert.
Gebündelte CLI-Skripte
| Skript | Zweck | Beispielverwendung |
|---|---|---|
scripts/extract-ux.mjs | Durchsucht package.json, AGENTS.md, DESIGN.md und Quellrouten (src/app, src/pages) in strukturiertes JSON | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | Erstellt ein 12-teiliges UX.md basierend auf einem Archetyp, Produktvoreinstellung (--preset linear) oder ux-scan.json | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | Führt 16 deterministische Struktur- und --check-code-Linterregeln (Routenparität, Primitive, tote Handler, falsche Z-Indexe) aus | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | Generiert ux-contract.css-Custom-Properties und React/TypeScript-Layout-Primitive (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) aus UX.md | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | Erstellt einen eigenständigen, responsiven ux-preview.html-Interaktiv-Wireframe-Simulator | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | Vergleicht zwei UX.md-Dateien auf Abweichungen bei Routen, Archetypen, Budgets oder Schwellwerten | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
Betriebsmodi
- Synthese (Greenfield /
init): Führtextract-ux.mjs+generate-ux.mjsaus, um das initialeUX.mdaus dem Projektkontext undDESIGN.mdzu erstellen, und passt dann Routen, Archetypen und Domänenregeln an. - Extraktion aus Referenz (Referenzprodukt oder URL): Extrahiert die räumliche Hülle, Interaktionsregeln, Tastaturkürzel und Seitenarchetypen aus einem benannten Referenzprodukt (z. B. Linear, ChatGPT Canvas, Stripe Dashboard, Shopify oder Supabase).
- Audit und Reverse Engineering (bestehende Codebasis):
Führt
extract-ux.mjsaus, um vorhandene Routen (src/app/**,src/pages/**,src/routes/**) zu erkennen, strukturelle Abweichungen zu ermitteln und ein einheitlichesUX.mdzu generieren. - Evolution (Feature-Erweiterung / Routensynchronisation):
Aktualisiert Abschnitt 3 (Seitenarchetypen) und Abschnitt 4 (Navigation, Routengraph & URL-Persistenz) bei neuen Seiten oder Workflows und überprüft die Parität mit
validate-ux.mjs UX.md --check-code.
Drei-Phasen-Generierungspipeline
Phase 1: Deterministische Extraktion und Archetyp-Klassifizierung
- Führe
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .aus (oder prüfepackage.json,AGENTS.mdundDESIGN.mddirekt), um die Ziellaufzeit, Authentifizierungsgrenzen, vorhandene Routen undDESIGN.md-Breakpoints zu erkennen. - Lade resources/archetype-taxonomy.md und bestätige:
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- Optionales Seed des
UX.mdvia:node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<Projektname>" --output UX.md
Phase 2: Domänenspezifische 12-Abschnitt-Synthese
Lade resources/ux-md-format.md, resources/layout-primitives.md und resources/writing-style-guide.md. Passe UX.md im Repository-Stammverzeichnis mit folgendem an:
- YAML-Frontmatter: Vollständige Konfiguration (
spec_version: "1.0",shell_budget,z_index_scale,thresholds,layout_primitives). - Abschnitte
0bis11in sequenzieller Reihenfolge:## 0. Produkt- und Domänentopologie## 1. Räumliche Architektur und App Shell(ASCII-Wireframe und Viewport-Budget-Tabelle)## 2. Scroll-, Viewport- und Z-Index-Vertrag## 3. Kernseiten-Archetypen (Blaupausen)(mit### Archetyp: <ArchetypID>-Überschriften)## 4. Navigation, Routengraph und URL-Persistenz(Mermaidflowchart LR, Routenerreichbarkeitstabelle und Zustandspersistenzmatrix)## 5. Overlay- und Feedback-Entscheidungsmatrix(Feldanzahl undpx-Schwellwerte)## 6. Obligatorische Ansichtszustände (4-Zustands-Matrix)(Loading,Empty,Error,Populated)## 7. Mutations-, Formular- und Berechtigungsergonomie(isDirty-Schutz, 2-stufige destruktive Regeln, 3-Wege-Berechtigungstore)## 8. Real-Daten-Stress, Dichte und Abschneidung(einzelner Listenskalierungsmodus,min-w-0 truncate,--Platzhaltertoken für leere Zellen,tabular-nums)## 9. Responsives Reflow und Eingabe-Choreografie(Collaps-Reihenfolge,>= 44x44pxTouch-Ziele mit>= 8pxAbstand, Tipp-Äquivalente für Hover-Interaktionen, Safe-Area-Scroll-Padding)## 10. Obligatorische Layout-Primitive (Code-Vertrag)(<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>)## 11. Projekt-Dos, Don'ts und Agenten-Prompt-Leitfaden
Schreibbeschränkungen:
- Keine vagen Adjektive: Verwende nicht "kleines Formular", "sauberes Layout", "langsame Anfrage" oder "intuitive Navigation" ohne explizite Zahlen (
<= 4 Felder,1280px,>= 150ms). Siehe resources/anti-patterns.md. - Keine Sackgassen: Jede Route in Abschnitt 4 verweist auf eine gültige
<ArchetypID>aus Abschnitt 3 und definiert sowohl einenEinstiegsauslöserals auch einenExit-/Abbruch-Fallback. - Erzwinge Layout-Primitive: Stelle sicher, dass alle Routen die 4 obligatorischen Layout-Primitive (
<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>) aus Abschnitt 10 verwenden.
Phase 3: Gegenprüfung und maschinelle Validierung
- Prüfe das generierte
UX.mdanhand von resources/quality-checklist.md ([UX-01]bis[UX-16]). - Führe das automatisierte Linter-Skript aus:
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - Behebe alle gemeldeten
error- oderwarning-Ergebnisse und wiederhole die Ausführung, bis der Validator mit0 errorsbeendet wird.