Communitygithub.com

ux-md-generator

Generieren, extrahieren, prüfen, Vorschau anzeigen, differenzieren und validieren von UX.md v1 Strukturspezifikationen für UI/UX.

Was ist ux-md-generator?

Der UX.md Generator und Strukturprüfer (v1) dient als strukturelles Gegenstück zu DESIGN.md und AGENTS.md. Während DESIGN.md visuelle Token (Farben, Typografie, Radien, Schatten, Abstände) definiert, legt UX.md das strukturelle Skelett und die Interaktionsregeln einer Anwendung fest – inklusive App Shell, räumliches Budget, Scroll- und Z-Index-Eigentümerschaft, Seitenarchetypen, Routenerreichbarkeitsgraph, URL-Statuspersistenz, Overlay-Entscheidungsmatrix, 4-Zustands-View-Vertrag sowie Formular- und Mutationsergonomie. Das Skill umfasst sechs reine Node.js-Skripte (extract-ux.mjs, generate-ux.mjs, validate-ux.mjs, scaffold-ux.mjs, preview-ux.mjs, diff-ux.mjs) und kann in vier Betriebsmodi (Synthese, Extraktion aus Referenz, Audit & Reverse Engineering, Evolution) eingesetzt werden. Es eignet sich für die Initialisierung neuer Frontend/UI-Projekte, das Extrahieren von UX-Mustern aus Referenzprodukten, das Prüfen bestehender Codebasen auf Layout-Abweichungen sowie das Hinzufügen neuer Routen und Ansichten. Das Tool läuft auf Basis einer pipeline mit drei Phasen (deterministische Extraktion, domänenspezifische Synthese der 12 Abschnitte, maschinelle Validierung) und stellt sicher, dass KI-Codierungsagenten konsistent nach strikten, quantifizierten Regeln arbeiten.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

SkriptZweckBeispielverwendung
scripts/extract-ux.mjsDurchsucht package.json, AGENTS.md, DESIGN.md und Quellrouten (src/app, src/pages) in strukturiertes JSONnode .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json
scripts/generate-ux.mjsErstellt ein 12-teiliges UX.md basierend auf einem Archetyp, Produktvoreinstellung (--preset linear) oder ux-scan.jsonnode .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md
scripts/validate-ux.mjsFührt 16 deterministische Struktur- und --check-code-Linterregeln (Routenparität, Primitive, tote Handler, falsche Z-Indexe) ausnode .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
scripts/scaffold-ux.mjsGeneriert ux-contract.css-Custom-Properties und React/TypeScript-Layout-Primitive (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) aus UX.mdnode .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux
scripts/preview-ux.mjsErstellt einen eigenständigen, responsiven ux-preview.html-Interaktiv-Wireframe-Simulatornode .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html
scripts/diff-ux.mjsVergleicht zwei UX.md-Dateien auf Abweichungen bei Routen, Archetypen, Budgets oder Schwellwertennode .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json

Betriebsmodi

  1. Synthese (Greenfield / init): Führt extract-ux.mjs + generate-ux.mjs aus, um das initiale UX.md aus dem Projektkontext und DESIGN.md zu erstellen, und passt dann Routen, Archetypen und Domänenregeln an.
  2. 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).
  3. Audit und Reverse Engineering (bestehende Codebasis): Führt extract-ux.mjs aus, um vorhandene Routen (src/app/**, src/pages/**, src/routes/**) zu erkennen, strukturelle Abweichungen zu ermitteln und ein einheitliches UX.md zu generieren.
  4. 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

  1. Führe node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . aus (oder prüfe package.json, AGENTS.md und DESIGN.md direkt), um die Ziellaufzeit, Authentifizierungsgrenzen, vorhandene Routen und DESIGN.md-Breakpoints zu erkennen.
  2. Lade resources/archetype-taxonomy.md und bestätige:
    • platform_profile: web-app | mobile-native | desktop-app | terminal-tui
    • archetype: b2b-saas-workspace | ai-chat-canvas | analytics-dashboard | ecommerce-storefront | developer-tool
  3. Optionales Seed des UX.md via:
    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 0 bis 11 in 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 (Mermaid flowchart LR, Routenerreichbarkeitstabelle und Zustandspersistenzmatrix)
    • ## 5. Overlay- und Feedback-Entscheidungsmatrix (Feldanzahl und px-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, >= 44x44px Touch-Ziele mit >= 8px Abstand, 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 einen Einstiegsauslöser als auch einen Exit-/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

  1. Prüfe das generierte UX.md anhand von resources/quality-checklist.md ([UX-01] bis [UX-16]).
  2. Führe das automatisierte Linter-Skript aus:
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. Behebe alle gemeldeten error- oder warning-Ergebnisse und wiederhole die Ausführung, bis der Validator mit 0 errors beendet wird.

Verwandte Skills