Skip to main content
Glama
Sign In
uxloom

uxloom

Official
by uxloom-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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 · uxloom MCP server

uxloom check finding 9 errors in a generated checkout flow, then passing the repaired one

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.

Connecting UXLoom to Claude Code and running the first check

Related MCP server: Designesy

Quick start (agents)

# Claude Code
claude mcp add uxloom -- npx -y uxloom

# Codex CLI
codex mcp add uxloom -- npx -y uxloom

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)

npx uxloom init      # one-command setup: MCP config + agent skill + starter file
npx uxloom preview   # live mocks (themed, commentable, EDITABLE in the browser)
npx uxloom export    # shareable HTML — plus --svg (Figma/Penpot import; add
                     #   --manifest for the round-trip key) and --png (playwright)
npx uxloom check     # design completeness — exit 1 on errors, CI-ready
npx uxloom audit     # implementation drift — web AND native (Swift/Kotlin/
                     #   Dart/Java markers); --live verifies the real DOM;
                     #   --design <file|dir> audits a Figma/Penpot export vs the contract
npx uxloom diff      # human-readable design diffs for PR review

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.

Reviewer pins a comment, clicks "→ agent"; the pin turns amber and a copyable prompt hands the comment to any AI agent, which reads the block and contract and resolves it

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.

Live preview: state tabs and clickable journey events on wireframe mocks

Add it to CI and a happy-path-only design can never merge:

- run: npx uxloom check design/uxloom.project.json

Workflow (also shipped as a skill in packages/mcp-server/skills/): project_init → brief_start/brief_answer → journey_define → screen_register → project_validate → fix → repeat until zero errors → coverage_report.

Does it actually catch things?

tools/dogfood.mjs drives the real MCP server through three products, twice each: screens as a happy-path generator hands them over, then repaired using the validation report. Artifacts in examples/.

Product

Generated (happy-path)

Repaired

shopmweb — e-commerce checkout (mWeb + Android)

9 errors, 6 warnings

0 / 0

taskflow — SaaS signup/onboarding (web)

1 error, 6 warnings

0 / 0

ridenow — ride booking (iOS + Android, offline-heavy)

3 errors, 7 warnings

0 / 0

Caught: an unreachable promo screen, dead-end verification states, five undesigned payment/error states, a 2.4:1 contrast button, a 40px touch target on Android, a checkout label that breaks in German, and three products' worth of missing offline states. Zero errors and zero warnings is reachable honestly — screens declare documented exemptions where a baseline state genuinely cannot apply, and contradictory exemptions are flagged.

Development

npm install
npm run typecheck
npm test

Status

Released and maintained: on npm and the official MCP registry, with the benchmark scorecard published in every GitHub release. The JourneyGraph format (formatVersion: "0.1") may evolve until 1.0; releases follow RELEASING.md — every surface is drift-checked in CI.

License

MIT

Available Tools

17 tools
brief_answerA

Submit brief answers. Unanswered fields take researched defaults and are recorded in the assumption ledger (auditable, reversible).

Inputs: prompt (required), answers (required).

brief_startA

Start a design brief. Returns a structured questionnaire. Answer every question you can yourself — from the provided context document (PRD, spec) first, then conversation context; only relay questions marked askHuman:true to the user. Then call brief_answer.

Inputs: prompt (required), context.

comment_contextA

The full work packet for one reviewer comment: the comment, the exact layout block its pin lands on, the complete screen definition (contract, components, layout, rationale, exemptions), every journey state referencing that screen with its transitions, and the current validation findings scoped to that screen. Use it to address the comment precisely, then call comment_resolve.

Inputs: id (required).

comment_resolveA

Resolve a reviewer comment after addressing it. The resolution note is shown to the reviewer and persisted; the pin clears live in every open preview. Never resolve without actually making the change.

Inputs: id (required), resolution (required).

comments_listA

Reviewer comments from the preview, with lifecycle status. Comments the reviewer clicked "→ agent" on are ASSIGNED — they are your work queue: call comment_context for each (assigned first, then open), make the change, then comment_resolve. Check this at session start and after every validation run.

Inputs: status.

coverage_reportB

The demo number: screens delivered vs. states the journeys actually need. Returns per-screen coverage and the missing-state list.

Inputs: no named parameters.

design_auditA

Reverse bridge (RFC 0007): audit a design export against the contract. Point it at a Figma/Penpot SVG or JSON export, a folder of them, or a uxloom --manifest index.json. Recovers screen×state from frame names (grammar " / ", or the manifest) and reports which required screens/states have no frame: design-screen-unmapped, design-state-missing, design-frame-unmapped. Optional scaffold writes a draft {screens} fragment for frames not yet in the contract. Deterministic, zero-coupling — no Figma/Penpot API.

Inputs: design (required), scaffold.

design_reviewA

One iterative design-review round (max 3 per project — enforced). Computes validation + rationale coverage, persists the round with deltas to .reviews.json, and returns a structured rubric to critique the design against: completeness, evidence, consistency, market fit, accessibility, honesty. Address the rubric, improve the design, then call again. Round 4 is refused: present results to the user instead.

Inputs: notes.

journey_defineA

Add or replace a journey (a state machine: states reference screens, events move between states). Screens referenced here must be registered via screen_register before project_validate passes.

Inputs: journey (required).

palette_checkA

Check a design system's color pairs against WCAG 2.2 AA (4.5:1) before any screens exist. Reports each pair's exact ratio, pass/fail, and thin-margin passes (under 5.0:1) that one shade lighter would break.

Inputs: pairs (required).

project_auditA

Audit the implementation against the design contract (drift detection). Static tiers: the uxloom.map.json screen registry and data-ux-screen/data-ux-state markers in source. Returns per-state verdicts (implemented with file:line evidence / unimplemented / unproven) and findings with fixes. When implementing screens from the contract, emit data-ux-state markers so the code stays self-auditing.

Inputs: root.

project_exportA

Return the complete current project document (for inspection, backup, or transformation before a project_import).

Inputs: no named parameters.

project_importA

Replace the whole project in one call: journeys and screens together. Prefer this over many journey_define/screen_register calls when registering a complete or large design. Validates the full document; unknown fields are rejected.

Inputs: project (required).

project_initA

Create a new UXLoom project file (uxloom.project.json). Run once per product.

Inputs: name (required), platforms (required).

project_validateA

Run every critic: journey completeness (unreachable states, dead ends, broken transitions), state coverage, WCAG contrast, touch targets, text expansion — plus fragment-merge errors and open reviewer comments from the preview. Honors uxloom.config.json thresholds. Iterate until errors = 0 and reviewer comments are addressed.

Inputs: no named parameters.

screen_critiqueB

Findings scoped to a single screen. Use during iteration on one screen.

Inputs: screenId (required).

screen_registerB

Add or replace a screen: its intent, requiredStates (the contract), designedStates (progress), and components with colors/labels/target sizes for the critics.

Inputs: screen (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools map to a distinct lifecycle stage or object—brief, journey, screen, comment, audit—and the descriptions include explicit workflow hints that reduce confusion. The main ambiguity is among the validation/critique cluster (design_review, screen_critique, project_validate, coverage_report), but their scopes are differentiated enough for careful agents.

    Naming Consistency4/5

    The set is consistently snake_case and mostly follows a <resource>_<operation> shape, with clear clusters like project_*, comment*, and design_*. Minor inconsistencies exist: comments_list vs comment_context vs comment_resolve mix plural/singular and some names use nouns rather than verbs (design_audit, coverage_report), but the overall pattern remains readable.

    Tool Count4/5

    17 tools is slightly above the typical 3-15 range, but the domain genuinely spans briefs, screen and journey modeling, validation, review rounds, comment triage, audits, and coverage reporting. Each tool has a defensible role, so the count feels dense but not bloated.

    Completeness4/5

    The lifecycle is broadly covered: init, brief, define, import/export, validate, review, comment resolution, audits, and coverage reporting are all present. Minor gaps exist, such as no explicit delete tool or direct assumption-ledger reversal, though project_import can replace the whole project as a workaround.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Designesy

      LE-VAI
      A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to score live URLs against a deterministic design contract, validate DTCG tokens and Lottie animations, audit accessibility, and retrieve design-system contracts, catalogs, and review rubrics.
      17
      5 npm
      MIT
    • artisign

      artisignofficial

      artisign
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create and manage consistent multi-screen UI designs through a token-efficient MCP interface, with design system tokens, components, flows, and visual review.
      94 npm
      2
      AGPL 3.0

    • InspireDesign

      SvtStarfire-Hit
      A
      license
      A
      quality
      C
      maintenance
      Enables AI coding agents to retrieve mode and stage guidance so they can lead users through a 9-stage design workflow, including questions, required artifacts, exit criteria, dependencies, pitfalls, rollback impact, and environment requirements. It helps non-designers turn ideas into buildable HTML/WPF design specs while keeping the human in control of confirmation and revisions.
      2
      MIT