ux-md
README.md
# UX.md
<p align="center">
<img src="./assets/hero.svg?v=2" alt="UX.md: Structural UI/UX specification, CLI linter, MCP server, and AI agent skill" width="100%" />
</p>
<p align="center">
<a href="https://github.com/SolidStateNetwork/ux.md/actions/workflows/validate.yml"><img src="https://github.com/SolidStateNetwork/ux.md/actions/workflows/validate.yml/badge.svg" alt="UX.md Spec & Linter CI" /></a>
<a href="docs/spec.md"><img src="https://img.shields.io/badge/Specification-v1.0-0284c7" alt="Spec v1.0" /></a>
<a href="schema/ux-md.schema.json"><img src="https://img.shields.io/badge/JSON_Schema-2020--12-0369a1" alt="JSON Schema Draft 2020-12" /></a>
<a href="skills/ux-md-generator/SKILL.md"><img src="https://img.shields.io/badge/Agent_Skill-ux--md--generator-0f172a" alt="Agent Skill" /></a>
<a href="scripts/mcp-server.mjs"><img src="https://img.shields.io/badge/MCP_Server-stdio-0369a1" alt="MCP Server" /></a>
<a href="llms.txt"><img src="https://img.shields.io/badge/llms.txt-ready-1e293b" alt="llms.txt" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-334155" alt="MIT License" /></a>
</p>
`UX.md` is a structural UI/UX format specification, zero-dependency CLI toolkit (`extract`, `generate`, `validate`, `scaffold`, `preview`, `diff`), Model Context Protocol (MCP) server, and installable AI agent skill.
While `AGENTS.md` defines engineering rules and `DESIGN.md` defines visual tokens (the skin), `UX.md` defines the application skeleton and interaction contracts: app shells, viewport budget math, scroll and z-index ownership, page archetypes, route reachability graphs, URL state persistence, 4-state view matrices, and mandatory code layout primitives.
---
## Why `UX.md` exists (skin vs. skeleton)
Giving an AI coding agent a `DESIGN.md` ensures every screen uses the right colors, fonts, and border radii. Across multi-session prompts, however, the interface still fractures structurally:
- **Session 1** builds `/issues` with a `1280px` container, places `+ New Issue` in the top-right header, edits items in a right-hand slide-over drawer, and renders a geometry-matched skeleton loader.
- **Session 2** builds `/cycles` with an `896px` container, places the creation button underneath the table, opens a centered modal for an 8-field form, and renders plain `"Loading..."` text.
- **Session 3** omits empty and error states, stores active filters in local `useState` (so pressing `F5` or Browser `Back` resets the screen), and renders an `Export` button wired to `onClick={() => {}}`.
| File standard | Role | What it governs |
| :--- | :--- | :--- |
| **`AGENTS.md`** | **Brain & governance** | Module boundaries, build and test commands, dependency rules, security constraints |
| **`DESIGN.md`** | **Skin & visual tokens** | Color palette, typography scale, border radii, shadows, spacing units, motion curves |
| **`UX.md`** | **Skeleton & behavior** | App shell geometry, page archetypes, route graph, modal vs. drawer thresholds, 4-state view matrix (`Loading / Empty / Error / Populated`), URL state persistence, and code layout primitives |
<p align="center">
<img src="./assets/triad-workflow.svg?v=3" alt="UX.md three-phase pipeline: Phase 1 Extract, Phase 2 Synthesize, Phase 3 Enforce and Scaffold" width="100%" />
</p>
---
## Quickstart
### 1. Install the agent skill (`ux-md-generator`)
Works with Claude Code, Antigravity / Gemini CLI, Cursor, OpenCode, OpenAI Codex, and GitHub Copilot:
```bash
npx skills add SolidStateNetwork/ux.md --skill ux-md-generator --copy -y
```
### 2. Run the zero-dependency CLI (`npx ux-md`)
All commands run on Node.js 20+ with zero external npm dependencies:
```bash
# 1. Initialize UX.md from an archetype, product preset (--preset linear | chatgpt-canvas | stripe-dashboard | shopify-storefront | supabase-studio), or repo scan
npx ux-md init --preset linear --project "Acme Workspace"
# 2. Scan an existing repository (framework, DESIGN.md tokens, and source routes)
npx ux-md extract . --output ux-scan.json
# 3. Validate UX.md against 16 structural and live code-contract rules
npx ux-md validate UX.md --strict --check-code
# 4. Scaffold CSS custom properties + React/TypeScript layout primitives (<AppShell>, <PageHeader>, <PageSection>, <DataStateBoundary>)
npx ux-md scaffold UX.md --out-dir src/components/ux
# 5. Render an interactive HTML wireframe & breakpoint simulator (1280px / 768px / 375px)
npx ux-md preview UX.md --output ux-preview.html
# 6. Diff two UX.md versions for route, budget, or threshold regressions
npx ux-md diff UX.old.md UX.md --json
```
*(If installed purely via `npx skills add`, each script is also directly callable under `node .agents/skills/ux-md-generator/scripts/<script>.mjs`.)*
### 3. Add the `UX.md` contract to `AGENTS.md` or `CLAUDE.md`
Drop this block into your project's `AGENTS.md` or `CLAUDE.md` so every AI coding session checks structural rules before editing UI routes:
```markdown
## UI & UX Architecture Contract
- Visual tokens (colors, typography, radii, shadows, spacing): see `DESIGN.md`.
- Structural skeleton (app shell budget, page archetypes, route graph, modal vs. drawer thresholds, 4-state view matrix, and `<AppShell>` / `<PageHeader>` / `<PageSection>` / `<DataStateBoundary>` primitives): see `UX.md`.
- Whenever adding or modifying UI routes, update `UX.md` and run `npx ux-md validate UX.md --strict --check-code`.
```
### 4. Connect the MCP server or GitHub Action
#### Model Context Protocol (MCP) configuration (`.mcp.json` / Claude Desktop / Cursor)
Exposes six deterministic tools (`ux_extract`, `ux_generate`, `ux_validate`, `ux_scaffold`, `ux_preview`, `ux_diff`) plus the `UX.md` v1.0 specification and JSON Schema resources over `stdio`:
```json
{
"mcpServers": {
"ux-md": {
"command": "npx",
"args": ["-y", "ux-md", "mcp"]
}
}
}
```
#### GitHub Actions CI enforcement (`.github/workflows/ux.yml`)
```yaml
- name: Validate UX.md structural contract
uses: SolidStateNetwork/ux.md@main
with:
file: UX.md
strict: 'true'
check-code: 'true'
```
Add the validation badge to your project's README:
```markdown
[](https://github.com/SolidStateNetwork/ux.md)
```
---
## Reference blueprints (5 core archetypes & product presets)
Each blueprint in [`examples/`](examples/) passes all strict checks in `validate-ux.mjs --strict` and can be initialized by archetype ID or `--preset` alias:
| Example | Archetype | `--preset` aliases | Key structural contracts |
| :--- | :--- | :--- | :--- |
| [`examples/b2b-saas-workspace/UX.md`](examples/b2b-saas-workspace/UX.md) | `b2b-saas-workspace` | `linear` | Keyboard-first issue workspace with `240px` rail, `?inspect=` slide-over drawer (`540px`), and `Cmd+K` command palette |
| [`examples/ai-chat-canvas/UX.md`](examples/ai-chat-canvas/UX.md) | `ai-chat-canvas` | `chatgpt-canvas`, `claude-artifacts` | Split-pane conversational thread with synchronized artifact code/preview stage (`?artifact=`) and streaming scroll-lock rules |
| [`examples/analytics-dashboard/UX.md`](examples/analytics-dashboard/UX.md) | `analytics-dashboard` | `stripe-dashboard`, `datadog` | Global URL-persisted time and environment filter bar (`?from=&to=&env=`), `CLS = 0` chart reservations, and `600px` JSON event drawer |
| [`examples/ecommerce-storefront/UX.md`](examples/ecommerce-storefront/UX.md) | `ecommerce-storefront` | `shopify-storefront` | Faceted discovery catalog, `4:5` aspect-reserved media, slide-over cart drawer (`?cart=open`), and guest-first checkout funnel |
| [`examples/developer-tool/UX.md`](examples/developer-tool/UX.md) | `developer-tool` | `supabase-studio`, `vercel-console` | Split SQL workbench, streaming build-log drawer (`?log=`), inline `2000ms` copy checkmarks, and tier-2 slug-confirm modals |
---
## The `UX.md` v1 format (YAML frontmatter + 12 sections)
Modeled on the hybrid structure of [Google's `DESIGN.md` specification](https://github.com/google-labs-code/design.md), `UX.md` pairs machine-verifiable YAML frontmatter (backed by [`schema/ux-md.schema.json`](schema/ux-md.schema.json)) with 12 ordered Markdown sections (see [`docs/spec.md`](docs/spec.md), [`PHILOSOPHY.md`](PHILOSOPHY.md), and [`llms.txt`](llms.txt)):
```yaml
---
spec_version: "1.0"
project: "Acme Workspace"
platform_profile: "web-app"
archetype: "b2b-saas-workspace"
token_source: "DESIGN.md"
scroll_owner: "inner-canvas"
breakpoints:
mobile_max: 767
tablet_max: 1023
desktop_min: 1280
shell_budget:
desktop_viewport: 1280
left_nav_px: 240
right_panel_px: 0
outer_padding_px: 48
content_min_px: 720
collapse_priority:
- panel: "left_nav"
below_px: 1024
z_index_scale:
base: 0
sticky: 10
navigation: 20
drawer: 30
modal: 40
popover: 50
toast: 60
tooltip: 70
thresholds:
modal_max_fields: 4
no_spinner_below_ms: 150
skeleton_min_ms: 150
toast_auto_dismiss_ms: 4000
min_touch_target_px: 44
layout_primitives:
- "AppShell"
- "PageHeader"
- "PageSection"
- "DataStateBoundary"
---
```
| Section | Enforced contract |
| :--- | :--- |
| **`0. Product & Domain Topology`** | Core user loop, auth/RBAC boundary, and input modality aligned with system architecture |
| **`1. Spatial Architecture & App Shell`** | ASCII app-shell wireframe, zone dimensions (`px`), and verified viewport budget math at `1280px`, `768px`, and `375px` |
| **`2. Scroll, Viewport & Z-Index Contract`** | Single scroll owner (prevents double scrollbars), sticky regions, `CLS = 0` reservations, and monotonic Z-Index table |
| **`3. Core Page Archetypes (Blueprints)`** | 3 to 5 named screen templates (`### Archetype: <ID>`) with ASCII wireframes and fixed primary CTA coordinates |
| **`4. Navigation, Route Graph & URL Persistence`** | Mermaid `flowchart LR` route map, bi-directional route reachability table, and URL state persistence matrix for `F5` and Browser `Back` |
| **`5. Overlay & Feedback Decision Matrix`** | Numeric thresholds separating `Modal` (`<= 4` fields), `Drawer` (`5 to 12` fields / inspect), `Dedicated Route` (`> 12` fields), `Popover`, and `Toast` |
| **`6. Mandatory View States (4-State Matrix)`** | Every view mapped across `Loading (Skeleton)`, `Empty (Copy + CTA)`, `Error (Reason + In-Place Retry)`, and `Populated` |
| **`7. Mutation, Form & Permission Ergonomics`** | Validation timing, double-submit locking, `isDirty` backdrop/`Esc` guard, 2-tier destructive rules (`Undo Toast` vs. `Confirm Modal`), and 3-way permission gates (`Hide` vs. `Disable + Tooltip` vs. `Lock Badge`) |
| **`8. Real-Data Stress, Density & Truncation`** | Single collection scaling strategy, `min-w-0 truncate` / `line-clamp`, `-` null fallback token, and right-aligned `tabular-nums` |
| **`9. Responsive Reflow & Input Choreography`** | Breakpoint collapse sequence, table-to-card conversion below `768px`, touch target size (`>= 44px` with `>= 8px` gap), tap equivalents for hover actions, and focus trapping |
| **`10. Mandatory Layout Primitives (Code Contract)`** | Shared code wrappers (`<AppShell>`, `<PageHeader>`, `<PageSection>`, `<DataStateBoundary>`) required across all route files |
| **`11. Project Do's, Don'ts & Agent Prompt Guide`** | Negative constraints with measurable numbers and a pre-commit verification checklist |
---
## Automated linter rules (`validate-ux.mjs`)
| Rule ID | Severity | What it verifies |
| :--- | :--- | :--- |
| `missing-frontmatter` | `error` | Required YAML frontmatter keys (`spec_version`, `shell_budget`, `z_index_scale`, `thresholds`, `layout_primitives`) |
| `missing-sections` | `error` | All 12 canonical sections (`## 0.` through `## 11.`) exist |
| `section-order` | `warning` | Sections appear in canonical order `0` through `11` |
| `viewport-overflow` | `error` | `left_nav_px + right_panel_px + outer_padding_px + content_min_px <= desktop_viewport` (or valid `collapse_priority`) |
| `z-index-collision` | `error` | Strictly ascending scale (`base < sticky < navigation < drawer < modal < popover < toast < tooltip`) |
| `broken-route-ref` | `error` | Every route in Section 4 references an `<ArchetypeID>` defined in Section 3 |
| `orphaned-archetype` | `warning` | Flags any page archetype defined in Section 3 that is never used by a route in Section 4 |
| `dead-end-flow` | `error` | Flags routes missing an `Entry Trigger`, `Primary Action`, or `Exit / Cancel Fallback` |
| `incomplete-state-matrix` | `error` | Verifies Section 6 defines all 4 mandatory states (`Loading`, `Empty`, `Error`, `Populated`) per view |
| `vague-prose` | `warning` | Flags non-deterministic adjectives (*"modals for small forms"*, *"clean layout"*) and unresolved `TODO`/`TBD` markers |
| `design-md-mismatch` | `warning` | Verifies `token_source: "DESIGN.md"` alignment when a sibling `DESIGN.md` is present |
| `route-parity` | `warning` | With `--check-code`, verifies that discovered routes in `src/app` or `src/pages` are registered in Section 4 |
| `missing-code-route` | `warning` | With `--check-code`, flags routes documented in Section 4 that have no matching route file in source code |
| `missing-layout-primitive` | `warning` | With `--check-code`, verifies that discovered route files reference at least one declared layout primitive (`AppShell`, `PageHeader`, `PageSection`, `DataStateBoundary`) |
| `dead-handler` | `error` | With `--check-code`, scans UI source files for no-op handlers (`onClick={() => {}}`, `href="#"`, `javascript:void(0)`) forbidden by Section 11 |
| `rogue-z-index` | `warning` | With `--check-code`, flags arbitrary z-index values (`z-[999]`, `zIndex: 9999`) outside the `z_index_scale` declared in frontmatter |
---
## Repository structure
```text
ux.md/
├── .github/workflows/
│ ├── validate.yml
│ ├── pages.yml
│ └── release.yml
├── action.yml
├── package.json
├── llms.txt
├── README.md
├── PHILOSOPHY.md
├── assets/
│ ├── hero.svg
│ ├── triad-workflow.svg
│ └── made-with-beautify.svg
├── bin/
│ └── ux-md.mjs
├── schema/
│ └── ux-md.schema.json
├── scripts/
│ ├── mcp-server.mjs
│ └── build-showcase.mjs
├── docs/
│ └── spec.md
├── examples/
│ ├── b2b-saas-workspace/UX.md
│ ├── ai-chat-canvas/UX.md
│ ├── analytics-dashboard/UX.md
│ ├── ecommerce-storefront/UX.md
│ └── developer-tool/UX.md
└── skills/
└── ux-md-generator/
├── SKILL.md
├── resources/
│ ├── ux-md-format.md
│ ├── archetype-taxonomy.md
│ ├── layout-primitives.md
│ ├── anti-patterns.md
│ ├── quality-checklist.md
│ └── writing-style-guide.md
└── scripts/
├── extract-ux.mjs
├── generate-ux.mjs
├── validate-ux.mjs
├── scaffold-ux.mjs
├── preview-ux.mjs
└── diff-ux.mjs
```
---
<p align="center">
<a href="https://github.com/oil-oil/beautify-github-readme"><img src="./assets/made-with-beautify.svg" width="300" alt="README made with beautify-github-readme" /></a>
</p>
## License
MIT © [SolidStateNetwork](https://github.com/SolidStateNetwork)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues