ux-md
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
/issueswith a1280pxcontainer, places+ New Issuein the top-right header, edits items in a right-hand slide-over drawer, and renders a geometry-matched skeleton loader.Session 2 builds
/cycleswith an896pxcontainer, 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 pressingF5or BrowserBackresets the screen), and renders anExportbutton wired toonClick={() => {}}.
File standard | Role | What it governs |
| Brain & governance | Module boundaries, build and test commands, dependency rules, security constraints |
| Skin & visual tokens | Color palette, typography scale, border radii, shadows, spacing units, motion curves |
| Skeleton & behavior | App shell geometry, page archetypes, route graph, modal vs. drawer thresholds, 4-state view matrix ( |
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 -y2. 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:
[](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 |
| Key structural contracts |
|
| Keyboard-first issue workspace with | |
|
| Split-pane conversational thread with synchronized artifact code/preview stage ( | |
|
| Global URL-persisted time and environment filter bar ( | |
|
| Faceted discovery catalog, | |
|
| Split SQL workbench, streaming build-log drawer ( |
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 |
| Core user loop, auth/RBAC boundary, and input modality aligned with system architecture |
| ASCII app-shell wireframe, zone dimensions ( |
| Single scroll owner (prevents double scrollbars), sticky regions, |
| 3 to 5 named screen templates ( |
| Mermaid |
| Numeric thresholds separating |
| Every view mapped across |
| Validation timing, double-submit locking, |
| Single collection scaling strategy, |
| Breakpoint collapse sequence, table-to-card conversion below |
| Shared code wrappers ( |
| Negative constraints with measurable numbers and a pre-commit verification checklist |
Automated linter rules (validate-ux.mjs)
Rule ID | Severity | What it verifies |
|
| Required YAML frontmatter keys ( |
|
| All 12 canonical sections ( |
|
| Sections appear in canonical order |
|
|
|
|
| Strictly ascending scale ( |
|
| Every route in Section 4 references an |
|
| Flags any page archetype defined in Section 3 that is never used by a route in Section 4 |
|
| Flags routes missing an |
|
| Verifies Section 6 defines all 4 mandatory states ( |
|
| Flags non-deterministic adjectives ("modals for small forms", "clean layout") and unresolved |
|
| Verifies |
|
| With |
|
| With |
|
| With |
|
| With |
|
| With |
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.mjsLicense
MIT © SolidStateNetwork
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
UI design from prompts, screenshots, and URLs for AI coding agents and theme tokens.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Spec-driven delivery: plans, solutions, ADRs, UX docs, tasks, rules and skills for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceDesign 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.933 npm21Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides 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
- AlicenseNot gradedqualityBmaintenanceExposes 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.1MIT
- AlicenseCqualityCmaintenanceEnables 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.301MIT