uxloom-dev/uxloom

**Your generator gave you 6 screens. UXLoom proves you're missing 9 states.**
AI generators (v0, Lovable, Figma Make, Claude) produce happy-path screens.
UXLoom is the critic layer: it models user journeys as state machines, treats
screens as nodes with state contracts, and mechanically proves what's missing
before a line of production code exists — unreachable screens, dead ends,
missing error/empty/loading states, WCAG contrast failures, undersized touch
targets, and labels that will overflow under localization.
Agent-native by design: the interface is an MCP server (works with Claude
Code, Codex, and any MCP client), with Agent Skills included.
**Deterministic by design**: same input, byte-identical report — benchmarked
(packages/bench) at 1.000 precision/recall on a seeded
defect catalog, SHA-256-stable across processes, 1000 screens in under 5ms.
That's what lets design completeness gate CI, where an LLM opinion can't.
**Website:** uxloom.dev · **npm:** uxloom · **MCP registry:** io.github.uxloom-dev/uxloom ·
Packages
| Package | What it is |
|---|---|
| @uxloom/journeygraph | The open design-as-data format: journeys as state machines, screens as nodes with required states |
| @uxloom/critics | The validators: journey completeness, state coverage, WCAG contrast, touch targets, text expansion |
| uxloom | The MCP server + Agent Skills — the interface agents use |
**New here? Start with the Quickstart** — prerequisites,
the Claude Code walkthrough, what to say to your agent, and troubleshooting.
Quick start (agents)
The project file (uxloom.project.json) lives in your workspace and belongs
in git — the design is data, versioned next to the code it specifies.
Quick start (humans & CI)
**Evidence-based design**: every decision in the contract can carry its
rationale — reasoning, rejected alternatives with pros/cons, sources,
confidence — enforced by the critics once adopted, iterated through a
bounded design_review loop (max 3 rounds), and shown to stakeholders in
the preview's evidence panel (ⓘ) and exports. The design doesn't just
validate; it argues its case.
**Agent-addressable comments**: a reviewer drops a pinned comment in the
preview and clicks "→ agent". The comment becomes a work item any Gen-AI
model can read with full context — comment_context returns the pinned
layout block, the screen contract, the journey references, and the current
findings for that screen — act on, and resolve back into the preview with
a note. One click from feedback to addressed.
CI-native: check and audit take --json, --sarif (GitHub code
scanning), and --github (inline PR annotations). Brownfield-ready:
--update-baseline freezes existing findings so only *new* drift blocks;
uxloom.config.json tunes thresholds to your accessibility bar. Full
documentation: uxloom.dev/docs.html.
Add it to CI and a happy-path-only design can never merge:
Workflow (also shipped as a skill in packages/mcp-server/skills/):