UX Audit 是一个面向 React/Next.js 代码的静态 UX 质量审查技能。它以功能级别运行（例如结账流程、引导流程、仪表盘），而非原则级别，帮助打开 PR 的前端开发者回答一个问题：这些改动中哪些会在生产环境伤害用户，哪些只是锦上添花？
该技能是什么
它是一个 diff-aware 审查器，审查 PR 中改动的文件；一个功能级检查清单运行器，能检测“这是登录流程”“这是结账”“这是模态框”并运行对应 playbook；一个发布就绪判决生成器，每个发现被赋予 release-blocker、fix-this-sprint、backlog 三个层级之一；一个具体修复顾问，使用现代 React 19 API（useActionState、useFormStatus、useOptimistic、useTransition、<Suspense>、error boundaries）。
该技能不是什么
遇到以下关注点应使用对应工具而非本技能：Core Web Vitals（LCP、CLS、INP）使用 Lighthouse + web-vitals + Vercel Agent；WCAG 规则违规使用 axe-core / jsx-a11y；写入时 a11y 预防使用 eslint-plugin-jsx-a11y；视觉回归使用 Chromatic / Percy；包体积预算使用 size-limit / bundle-analyzer；通用 bug 审查使用 CodeRabbit / Vercel Agent。当发现与上述重叠时应链接出去，而非复述。
审查工作流
- 确定范围：通过 git diff --name-only main 获取 PR diff，或使用显式文件/文件夹。
- 检测范围中的功能（登录/结账/表单/模态框/列表/仪表盘等）。
- 对每个功能运行其 references/feature-playbooks.md 中的 playbook。
- 对每个检查加载匹配规则：rules-modern/ 用于状态/表单/焦点 bug，rules/ 用于 UX 定律。
- 按 references/ship-readiness.md 为每个发现分配 ship 层级。
- 按界面分组发现，使用所选输出适配器渲染。
- 报告前验证 audit-self-check。
范围默认使用 git diff --name-only main（若在 git 仓库中有未提交改动），否则审查用户传入的显式范围。默认不审查整个代码库。
功能检测基于元素语义、文件名和路由路径。例如带邮箱和密码的 <form> 是登录；带多步指示器的 <form> 是引导；role="dialog" 是模态框。
每个功能有 5-7 个有序检查。不跳过检查，即使预期通过；每次通过都进入 audit-self-check。
规则分两层：rules-modern/（第 2 层）是现代前端 UX 失败模式（状态覆盖、表单保留、焦点管理、乐观回滚、CLS、微文案），大多数发现来源于此；rules/（第 3 层）是 UX 定律（Hick's、Fitts's、Miller's 等），当第 2 层不适用时用于认知/感知推理。
Ship 层级每个发现获得以下之一：release-blocker（合并前修复，如数据丢失、认证损坏、关键路径缺少错误状态、暗模式、不恢复的焦点陷阱）；fix-this-sprint（合并但记录问题，如触摸目标小于 44px、缺少骨架屏、模糊错误、缺少空状态 CTA）；backlog（跟踪后发布，如暗色模式未测试、RTL 未验证、微文案小问题）。
三层审查
第 1 层 — 功能 playbook（入口点）：references/feature-playbooks.md，12 个功能 × 5-7 个有序检查，从第 2、3 层拉取规则。
第 2 层 — 现代前端失败模式（高杠杆层）：rules-modern/<category>-<slug>.md，33 条规则覆盖状态覆盖、表单保留、焦点管理、异步/乐观、CLS 配对、微文案、暗色模式、i18n、移动端。检测配方使用 React 19 API。
第 3 层 — UX 定律（认知/感知储备）：rules/<prefix>-<slug>.md，30 条 Hick's、Fitts's、Miller's 等规则。当功能 playbook 需要认知负荷/决策/感知推理时调用。通常每次审查 1-2 条，而非全部 30 条。
Diff-aware 模式
默认范围是 PR diff。通过以下命令检测：git diff --name-only main -- '.tsx' '.jsx' '.ts' '.js' '.css' '.module.css'。仅审查这些文件。在输出中显示基础分支：Auditing: 8 files changed vs main。快速本地检查（单个组件）：git diff --name-only HEAD -- src/Component.tsx。完整扫描：显式 --full src/（罕见，仅在向代码库引入该技能时）。
发布就绪判决
每次审查在逐发现详情前先输出顶层判决，包含表面数量、发现数、release-blockers、fix-this-sprint、backlog 数量，以及 defer-to 列表（性能运行 Lighthouse、包体积运行 size-limit、WCAG 违规运行 axe-core）。判决层级：✅ READY（0 个 release-blocker，≤3 个 fix-this-sprint）；⚠️ READY WITH FOLLOW-UP（0 个 release-blocker，≥4 个 fix-this-sprint）；❌ NOT READY（≥1 个 release-blocker）；🚫 INCOMPLETE（audit-self-check 失败，需重跑）。
输出适配器
三种格式，均从同一 JSON 渲染：终端表格（本地开发快速扫描，紧密 5 列表格按界面分组）；PR 评论（GitHub / Vercel 审查，Markdown 带建议块用于内联 diff）；CI JSON（流水线、仪表盘，严格 JSON 按 references/output-schema.md）。
跳过协议
发现可通过内联注释有意抑制：{/* ux-audit-ignore:focus-not-restored — intentional: parent owns focus */}<Dialog open={open} onClose={onClose}>。slug 必须匹配规则 slug。抑制项在审查摘要中报告，以便审查者验证意图。
参考文件
references/feature-playbooks.md 在步骤 2-3 读取，用于检测功能和选择 playbook；references/modern-failure-modes.md 是所有 33 条现代规则的分类索引；references/states-coverage.md 验证各组件类型的加载/空/错误/禁用覆盖；references/ship-readiness.md 在步骤 5 使用，为发现分配 ship 层级；references/output-adapters.md 在步骤 6 使用，格式化终端/PR 评论/JSON 输出；references/defer-to-other-tools.md 识别应委托的关注点；references/output-schema.md 是发现和判决的严格 JSON schema；references/observational-rubrics.md 是第 3 层评分规则（1-5 分带锚点）；rules-modern/<category>-<slug>.md 在步骤 4 运行第 2 层检查；rules-modern/_sections.md 是现代规则层的分类索引；rules/<prefix>-<slug>.md 在步骤 4 运行第 3 层 UX 定律检查；rules/_sections.md 是 UX 定律规则层的分类索引。
注意事项
默认不审查整个代码库（diff-aware 是默认，完整扫描需显式指定）；不重复其他工具（LCP > 4s 是 Lighthouse，缺少 alt 文本是 axe，链接而非复述）；不跳过功能检测步骤（对每个文件运行所有规则会产生噪音）；不为每个发现分配 release-blocker（保留给真正的阻塞项，膨胀会破坏信号）；不提供不带现代 React API 的修复建议（“添加加载状态”很弱，“包裹在 <Suspense fallback={<Skeleton />}> 并使用 useTransition 触发”才可操作）；不先做 JSON 传递就直接渲染 markdown；不堆砌 UX 定律发现（第 3 层是储备）；不逐字引用来源（每条规则均改写，lawsofux.com 使用 CC BY-NC-SA 会污染技能）；不捏造检测（若无法 grep 文件或看到 JSX，标记为 unknown 并给出原因，绝无证据就声称发现）。
审查自检
若以下任一为真，将审查标记为 INCOMPLETE：运行的规则少于 playbook 计划数量；超过 30% 的规则返回 unknown（证据不足）；任何 fail/warn 发现未引用 file:line；未提供 reproduceSteps 或修复片段；每条规则的明显耗时中位数短得不合理（发现之间没有 Read 或 Grep 工具调用）；每个发现最终都落入同一层级（疑似无判断的笼统分配）。