{
  "markdown": "# UXLoom\n\n**Your generator gave you 6 screens. UXLoom proves you're missing 9 states.**\n\nAI generators (v0, Lovable, Figma Make, Claude) produce happy-path screens.\nUXLoom is the critic layer: it models user journeys as state machines, treats\nscreens as nodes with state contracts, and mechanically proves what's missing\nbefore a line of production code exists — unreachable screens, dead ends,\nmissing error/empty/loading states, WCAG contrast failures, undersized touch\ntargets, and labels that will overflow under localization.\n\nAgent-native by design: the interface is an MCP server (works with Claude\nCode, Codex, and any MCP client), with Agent Skills included.\n\n**Deterministic by design**: same input, byte-identical report — benchmarked\n([`packages/bench`](packages/bench)) at 1.000 precision/recall on a seeded\ndefect catalog, SHA-256-stable across processes, 1000 screens in under 5ms.\nThat's what lets design completeness gate CI, where an LLM opinion can't.\n\n**Website:** [uxloom.dev](https://uxloom.dev) · **npm:** [`uxloom`](https://www.npmjs.com/package/uxloom) · **MCP registry:** `io.github.uxloom-dev/uxloom` · [![uxloom MCP server](https://glama.ai/mcp/servers/uxloom-dev/uxloom/badges/score.svg)](https://glama.ai/mcp/servers/uxloom-dev/uxloom)\n\n![uxloom check finding 9 errors in a generated checkout flow, then passing the repaired one](docs/demo.gif)\n\n## Packages\n\n| Package | What it is |\n|---|---|\n| [`@uxloom/journeygraph`](packages/journeygraph) | The open design-as-data format: journeys as state machines, screens as nodes with required states |\n| [`@uxloom/critics`](packages/critics) | The validators: journey completeness, state coverage, WCAG contrast, touch targets, text expansion |\n| [`uxloom`](packages/mcp-server) | The MCP server + Agent Skills — the interface agents use |\n\n**New here? Start with the [Quickstart](QUICKSTART.md)** — prerequisites,\nthe Claude Code walkthrough, what to say to your agent, and troubleshooting.\n\n![Connecting UXLoom to Claude Code and running the first check](docs/getting-started.gif)\n\n## Quick start (agents)\n\n```bash\n# Claude Code\nclaude mcp add uxloom -- npx -y uxloom\n\n# Codex CLI\ncodex mcp add uxloom -- npx -y uxloom\n```\n\nThe project file (`uxloom.project.json`) lives in your workspace and belongs\nin git — the design is data, versioned next to the code it specifies.\n\n## Quick start (humans & CI)\n\n```bash\nnpx uxloom init      # one-command setup: MCP config + agent skill + starter file\nnpx uxloom preview   # live mocks (themed, commentable, EDITABLE in the browser)\nnpx uxloom export    # shareable HTML — plus --svg (Figma/Penpot import; add\n                     #   --manifest for the round-trip key) and --png (playwright)\nnpx uxloom check     # design completeness — exit 1 on errors, CI-ready\nnpx uxloom audit     # implementation drift — web AND native (Swift/Kotlin/\n                     #   Dart/Java markers); --live verifies the real DOM;\n                     #   --design <file|dir> audits a Figma/Penpot export vs the contract\nnpx uxloom diff      # human-readable design diffs for PR review\n```\n\n**Evidence-based design**: every decision in the contract can carry its\nrationale — reasoning, rejected alternatives with pros/cons, sources,\nconfidence — enforced by the critics once adopted, iterated through a\nbounded `design_review` loop (max 3 rounds), and shown to stakeholders in\nthe preview's evidence panel (ⓘ) and exports. The design doesn't just\nvalidate; it argues its case.\n\n**Agent-addressable comments**: a reviewer drops a pinned comment in the\npreview and clicks \"→ agent\". The comment becomes a work item any Gen-AI\nmodel can read with full context — `comment_context` returns the pinned\nlayout block, the screen contract, the journey references, and the current\nfindings for that screen — act on, and resolve back into the preview with\na note. One click from feedback to addressed.\n\n![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](docs/preview-handoff.gif)\n\nCI-native: `check` and `audit` take `--json`, `--sarif` (GitHub code\nscanning), and `--github` (inline PR annotations). Brownfield-ready:\n`--update-baseline` freezes existing findings so only *new* drift blocks;\n`uxloom.config.json` tunes thresholds to your accessibility bar. Full\ndocumentation: [uxloom.dev/docs.html](https://uxloom.dev/docs.html).\n\n![Live preview: state tabs and clickable journey events on wireframe mocks](docs/preview-demo.gif)\n\nAdd it to CI and a happy-path-only design can never merge:\n\n```yaml\n- run: npx uxloom check design/uxloom.project.json\n```\n\nWorkflow (also shipped as a skill in `packages/mcp-server/skills/`):\n`project_init` → `brief_start`/`brief_answer` → `journey_define` →\n`screen_register` → `project_validate` → fix → repeat until zero errors →\n`coverage_report`.\n\n## Does it actually catch things?\n\n`tools/dogfood.mjs` drives the real MCP server through three products, twice\neach: screens as a happy-path generator hands them over, then repaired using\nthe validation report. Artifacts in [`examples/`](examples/).\n\n| Product | Generated (happy-path) | Repaired |\n|---|---|---|\n| `shopmweb` — e-commerce checkout (mWeb + Android) | 9 errors, 6 warnings | 0 / 0 |\n| `taskflow` — SaaS signup/onboarding (web) | 1 error, 6 warnings | 0 / 0 |\n| `ridenow` — ride booking (iOS + Android, offline-heavy) | 3 errors, 7 warnings | 0 / 0 |\n\nCaught: an unreachable promo screen, dead-end verification states, five\nundesigned payment/error states, a 2.4:1 contrast button, a 40px touch target\non Android, a checkout label that breaks in German, and three products' worth\nof missing offline states. Zero errors *and zero warnings* is reachable\nhonestly — screens declare documented `exemptions` where a baseline state\ngenuinely cannot apply, and contradictory exemptions are flagged.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\n```\n\n## Status\n\nReleased and maintained: on [npm](https://www.npmjs.com/package/uxloom) and\nthe official MCP registry, with the benchmark scorecard published in every\n[GitHub release](https://github.com/uxloom-dev/uxloom/releases). The\nJourneyGraph format (`formatVersion: \"0.1\"`) may evolve until 1.0; releases\nfollow [RELEASING.md](RELEASING.md) — every surface is drift-checked in CI.\n\n## License\n\nMIT\n",
  "bytes": 6376,
  "sha": "1b5ebed670cc44020c3f48e2c1dfcf0afa20a7e17bea5d3667f88286874530c1",
  "repo_slug": "uxloom-dev/uxloom",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_uxloom_dev_uxloom_13ff1c81/readme"
}