UX.md Generator and Structural Auditor (v1)
Overview
While DESIGN.md specifies visual tokens (colors, typography, radii, shadows, spacing scale), UX.md specifies the structural skeleton and interaction rules of an application.
Without UX.md, AI coding agents drift across sessions: mixing container widths, moving primary CTAs, alternating arbitrarily between modals and drawers, omitting empty or error states, losing filter state on F5 refresh, and introducing dead-end routes.
This skill operates across four modes using a three-phase pipeline backed by six zero-dependency Node.js scripts in scripts/.
Bundled CLI Scripts
| Script | Purpose | Example Usage |
|---|---|---|
scripts/extract-ux.mjs | Scans package.json, AGENTS.md, DESIGN.md, and source routes (src/app, src/pages) into structured JSON | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | Scaffolds a 12-section UX.md from an archetype, product preset (--preset linear), or ux-scan.json | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | Runs 16 deterministic structural and --check-code linter rules (route parity, primitives, dead handlers, rogue z-indexes) | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | Generates ux-contract.css custom properties and React/TypeScript layout primitives (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) from UX.md | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | Generates a standalone, responsive ux-preview.html interactive wireframe simulator | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | Compares two UX.md files for route, archetype, budget, or threshold regressions | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
Operating modes
- Synthesize (greenfield /
init): Runsextract-ux.mjs+generate-ux.mjsto scaffold the initialUX.mdfrom the project context andDESIGN.md, then customizes the routes, archetypes, and domain rules. - Extract from reference (reference product or URL): Extracts the spatial shell, interaction rules, keyboard shortcuts, and page archetypes from a named reference product (for example Linear, ChatGPT Canvas, Stripe Dashboard, Shopify, or Supabase).
- Audit and reverse-engineer (existing codebase):
Runs
extract-ux.mjsto discover existing routes (src/app/**,src/pages/**,src/routes/**), detects structural drift, and generates a unifiedUX.md. - Evolve (feature addition / route sync):
Updates Section 3 (Page Archetypes) and Section 4 (Navigation, Route Graph & URL Persistence) whenever new pages or workflows are added, verifying parity with
validate-ux.mjs UX.md --check-code.
Three-phase generation pipeline
Phase 1: Deterministic extraction and archetype classification
- Run
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(or inspectpackage.json,AGENTS.md, andDESIGN.mddirectly) to detect the target runtime, authentication boundary, existing routes, andDESIGN.mdbreakpoints. - Load resources/archetype-taxonomy.md and confirm:
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- Optionally seed
UX.mdvia:node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<Project Name>" --output UX.md
Phase 2: Domain-specific 12-section synthesis
Load resources/ux-md-format.md, resources/layout-primitives.md, and resources/writing-style-guide.md. Tailor UX.md at the repository root with:
- YAML frontmatter: Complete configuration (
spec_version: "1.0",shell_budget,z_index_scale,thresholds,layout_primitives). - Sections
0through11in sequential order:## 0. Product & Domain Topology## 1. Spatial Architecture & App Shell(ASCII wireframe and viewport budget table)## 2. Scroll, Viewport & Z-Index Contract## 3. Core Page Archetypes (Blueprints)(using### Archetype: <ArchetypeID>headings)## 4. Navigation, Route Graph & URL Persistence(Mermaidflowchart LR, route reachability table, and state persistence matrix)## 5. Overlay & Feedback Decision Matrix(field-count andpxthresholds)## 6. Mandatory View States (4-State Matrix)(Loading,Empty,Error,Populated)## 7. Mutation, Form & Permission Ergonomics(isDirtyguard, 2-tier destructive rules, 3-way permission gates)## 8. Real-Data Stress, Density & Truncation(single list-scaling mode,min-w-0 truncate,-empty-cell placeholder token,tabular-nums)## 9. Responsive Reflow & Input Choreography(collapse order,>= 44x44pxtouch targets with>= 8pxgap, tap equivalents for hover interactions, safe-area scroll padding)## 10. Mandatory Layout Primitives (Code Contract)(<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>)## 11. Project Do's, Don'ts & Agent Prompt Guide
Writing constraints:
- Zero vague adjectives: Do not write "small form", "clean layout", "slow request", or "intuitive navigation" without explicit numbers (
<= 4 fields,1280px,>= 150ms). See resources/anti-patterns.md. - Zero dead ends: Every route in Section 4 references a valid
<ArchetypeID>from Section 3 and defines both anEntry Triggerand anExit / Cancel Fallback. - Enforce layout primitives: Ensure all routes compose the 4 mandatory layout primitives (
<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>) defined in Section 10.
Phase 3: Cross-audit and machine validation
- Audit the generated
UX.mdagainst resources/quality-checklist.md ([UX-01]through[UX-16]). - Run the automated linter script:
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - Resolve any reported
errororwarningfindings and re-run until the validator exits with0 errors.