uxloom

UXLoom

生成器给了你 6 个屏幕。UXLoom 证明你还缺少 9 种状态。

AI 生成器（v0、Lovable、Figma Make、Claude）会生成顺利流程中的屏幕。 UXLoom 是评审层：它将用户旅程建模为状态机，将屏幕视为带有状态契约的节点，并在一行生产代码尚未编写之前，以机械方式证明缺失之处——无法到达的屏幕、死胡同、缺失的错误／空白／加载状态、WCAG 对比度不达标、触控目标尺寸不足，以及在本地化后会溢出的标签。

Agent 原生设计：界面是 MCP 服务（可与 Claude Code、Codex 和任何 MCP 客户端配合使用），并内置 Agent Skills。

确定性设计：相同输入会生成逐字节一致的报告——在种子化缺陷目录上进行基准测试（packages/bench），精确率／召回率均为 1.000，跨进程保持 SHA-256 稳定，1000 个屏幕在 5ms 内完成。这使设计完整性可以成为 CI 的门槛，而 LLM 的意见做不到这一点。

网站： uxloom.dev · npm： uxloom · MCP 注册表： io.github.uxloom-dev/uxloom ·

软件包

软件包	说明
@uxloom/journeygraph	开放的设计即数据格式：将旅程表示为状态机，将屏幕表示为带有必需状态的节点
@uxloom/critics	验证器：旅程完整性、状态覆盖率、WCAG 对比度、触控目标、文本扩展
uxloom	MCP 服务 + Agent Skills——Agent 使用的界面

初次使用？从快速入门开始——了解前置条件、 Claude Code 操作指南、如何向 Agent 提出需求，以及故障排除。

快速开始（Agent）

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

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

项目文件（uxloom.project.json）位于你的工作区中，应纳入 git——设计即数据，与其所描述的代码一同进行版本管理。

快速开始（面向用户和 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

基于证据的设计：合约中的每项决策都可以附带依据——推理、被否决的替代方案及其优缺点、来源和置信度。采纳后，这些依据会由评审器强制执行，并通过有界的 design_review 循环（最多 3 轮）反复迭代，展示在预览的证据面板（ⓘ）和导出内容中。设计不只是通过验证，还会为自己辩护。

可由 Agent 处理的评论：评审者在预览中添加固定评论，然后点击“→ agent”。评论会成为一项工作，任何生成式 AI 模型都能读取完整上下文——comment_context 会返回固定的布局块、屏幕合约、用户旅程引用，以及该屏幕当前的检查结果——随后采取行动，并附注释将处理结果反馈到预览中。从收到反馈到解决问题，只需点击一次。

原生支持 CI：check 和 audit 支持 --json、--sarif（GitHub 代码扫描）和 --github（PR 内联批注）。适用于已有项目：--update-baseline 会冻结现有检查结果，只有新增偏差会阻止合并；uxloom.config.json 可根据你的无障碍标准调整阈值。完整文档：uxloom.dev/docs.html。

将其加入 CI，这样只有顺畅路径的设计就永远无法合并：

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

工作流（也作为技能发布在 packages/mcp-server/skills/ 中）： project_init → brief_start/brief_answer → journey_define → screen_register → project_validate → 修复 → 重复，直到错误数为零 → coverage_report。

它真的能发现问题吗？

tools/dogfood.mjs 会让真实 MCP 服务处理三款产品，每款各处理两次：先由顺畅路径生成器生成屏幕，再根据验证报告修复。产物位于 examples/。

产品	生成结果（顺畅路径）	修复后
shopmweb — 电子商务结账（mWeb + Android）	9 个错误，6 个警告	0 / 0
taskflow — SaaS 注册/引导流程（Web）	1 个错误，6 个警告	0 / 0
ridenow — 叫车预订（iOS + Android，重度依赖离线功能）	3 个错误，7 个警告	0 / 0

发现的问题包括：无法到达的促销屏幕、无出路的验证状态、五种未设计的支付/错误状态、对比度为 2.4:1 的按钮、Android 上 40px 的触控目标、在德语中显示异常的结账标签，以及三款产品缺少离线状态。只要如实使用就能达到错误为零、警告也为零——屏幕可声明有文档记录的 exemptions，说明某项基准状态确实不适用；互相矛盾的豁免声明会被标记。

开发

npm install
npm run typecheck
npm test

状态

已发布并持续维护：可通过 npm 和官方 MCP 注册表获取，基准评分卡会随每次 GitHub 发布一同发布。JourneyGraph 格式（formatVersion: "0.1"）在 1.0 之前可能会有所演变；发布遵循 RELEASING.md——CI 会检查所有界面是否存在偏差。

许可证

MIT