Skip to main content
Glama

UX.md

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


Related MCP server: art-director-mcp

Quickstart

1. Install the agent skill (ux-md-generator)

Works with Claude Code, Antigravity / Gemini CLI, Cursor, OpenCode, OpenAI Codex, and GitHub Copilot:

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:

# 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:

## 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:

{
  "mcpServers": {
    "ux-md": {
      "command": "npx",
      "args": ["-y", "ux-md", "mcp"]
    }
  }
}

GitHub Actions CI enforcement (.github/workflows/ux.yml)

- 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:

[![UX.md Validated](https://img.shields.io/badge/UX.md-v1.0_Validated-0284c7)](https://github.com/SolidStateNetwork/ux.md)

Reference blueprints (5 core archetypes & product presets)

Each blueprint in 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

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

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

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

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

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, UX.md pairs machine-verifiable YAML frontmatter (backed by schema/ux-md.schema.json) with 12 ordered Markdown sections (see docs/spec.md, PHILOSOPHY.md, and llms.txt):

---
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

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

License

MIT © SolidStateNetwork

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Design contract layer for AI agents. Scans Figma, code, Storybook, and token files, reconciles conflicts, and serves a single machine-readable source of truth so every agent gets the same authoritative design rules before it builds. Local-first.
      9
      33 npm
      21
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides coding agents with local tools to inspect project UI inventories, propose and compare visual direction boards, compile versioned design contracts and DTCG tokens, retrieve section-specific blueprints, and audit running interfaces with browser evidence including screenshots, accessibility findings, and overflow measurements.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes six tools over MCP (stdio) that let agents lay out, build, and validate a local Figma-like sheet of app screens and their connections, capture screen images from a live app or HTML mock-ups, and return PNG crops of a single screen card or row so the agent can show a person exactly the area under discussion.
      1
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI coding assistants to create and edit FigCraft design files, automatically open them in the FigCraft GUI, and generate responsive UI/UX live on screen with Figma-grade auto-layout, anti-overflow text constraints, luxury theming, and built-in layout auditing. It also supports batch operations, screenshots, document inspection, and saving canvases back to disk.
      30
      1
      MIT