ux-audit

UX 审计

用于 React/Next.js 代码的静态 UX 质量审查工具。以功能级别（结账流程、引导流程、仪表板）为单位运行，而非原则级别。它要为打开 PR 的前端开发者回答一个问题：“这些问题中，哪些会在生产环境中影响用户，哪些只是锦上添花？”

这项技能是什么

• 可感知代码差异的审查工具，用于审计 PR 中变更的文件
• 功能级别的检查清单执行器：识别“这是一个登录流程”／“这是一个结账流程”／“这是一个模态框”，并运行相应的操作指南
• 发布就绪度判定工具：每项发现都标记为 release-blocker | fix-this-sprint | backlog
• 具体修复建议工具，使用现代 React 19 API（useActionState、useFormStatus、useOptimistic、useTransition、<Suspense>、错误边界）

这项技能不是什么

请使用合适的工具。不要重复以下工具已经做得很好的工作：

关注点	改用此工具	原因
Core Web Vitals（LCP、CLS、INP）	Lighthouse + web-vitals + Vercel Agent	通过实测和实验室测量，而非静态分析
WCAG 规则违规	axe-core / jsx-a11y	提供权威规则列表和结构化违规信息
编写代码时预防 a11y 问题	eslint-plugin-jsx-a11y	Lint 可在运行时之前捕获问题
视觉回归	Chromatic / Percy	提供像素级差异对比
Bundle 大小预算	size-limit / bundle-analyzer	持续跟踪预算
通用 Bug 审查	CodeRabbit / Vercel Agent	使用 LLM 审查整个代码差异中的 Bug

如果某项发现与上述任一项重叠，请链接到相应工具，不要重复描述。

完整清单见 references/defer-to-other-tools.md。

审计工作流

复制并跟踪此检查清单：

UX Audit progress:
- [ ] Step 1: Determine scope (PR diff via `git diff --name-only main` OR explicit file/folder)
- [ ] Step 2: Detect features in scope (sign-in / checkout / form / modal / list / dashboard / etc.)
- [ ] Step 3: For each feature, run its playbook from references/feature-playbooks.md
- [ ] Step 4: For each check, load the matching rule (rules-modern/ for state/form/focus bugs; rules/ for Laws of UX)
- [ ] Step 5: Assign each finding a ship tier per references/ship-readiness.md
- [ ] Step 6: Group findings by surface, render with the chosen output adapter
- [ ] Step 7: Verify the audit-self-check before reporting

1. 确定范围。 如果位于有未提交变更的 Git 仓库中，默认使用 git diff --name-only main；否则审计用户明确指定的范围。默认不要审计整个代码库——噪声过多。
2. 识别功能。 根据元素语义、文件名和路由路径进行匹配。包含邮箱和密码的 <form> = 登录。包含多步骤指示器的 <form> = 引导流程。role="dialog" = 模态框。各类功能的识别启发式规则见 references/feature-playbooks.md。
3. 运行操作指南。 每项功能都有 5-7 项有序检查。即使预期检查会通过，也不要跳过；每项通过的检查都要记录在审计自检中。
4. 加载规则。 分两层：
   • rules-modern/（第 2 层）——现代前端 UX 失效模式（状态覆盖、表单保留、焦点管理、乐观更新回滚、CLS、微文案）。大多数发现都来自这一层。
   • rules/（第 3 层）——UX 定律（Hick 定律、Fitts 定律、Miller 定律等）。当第 2 层不适用时，用于认知／感知方面的分析。
5. 划分发布等级。 每项发现都归入三个等级之一（见 references/ship-readiness.md）：
   • release-blocker — 合并前修复（数据丢失、身份验证失效、关键路径缺少错误状态、暗黑模式、无法恢复焦点的焦点陷阱）
   • fix-this-sprint — 合并，但记录问题（触屏目标尺寸不足 44 px、缺少骨架屏、错误提示含糊、缺少空状态 CTA）
   • backlog — 记录并发布（未经测试的深色模式、未经验证的 RTL、微文案小问题）
6. 分组并呈现。 按界面区域（组件文件或页面）分组。使用 references/output-adapters.md 中的三个适配器之一呈现结果。
7. 自检。 确认审计确实已运行（已执行的规则数 > 计划执行的规则数；每项发现都引用文件和行号；每项发现都包含修复代码片段）。

三层审计

Layer 1 — Feature playbooks  (the entry point)
  references/feature-playbooks.md
  12 features × 5-7 ordered checks → pulls rules from Layers 2 and 3

Layer 2 — Modern frontend failure modes  (the high-leverage layer)
  rules-modern/<category>-<slug>.md
  33 rules covering state coverage, form preservation, focus mgmt,
  async/optimistic, CLS pairings, microcopy, dark mode, i18n, mobile.
  Detection recipes use React 19 APIs.

Layer 3 — Laws of UX  (the cognitive/perceptual reserve)
  rules/<prefix>-<slug>.md
  30 rules for Hick's, Fitts's, Miller's, etc. Invoked when feature
  playbooks need cognitive load / decision / perception reasoning.
  Usually 1-2 of these per audit; not all 30.

感知差异模式

默认范围是 PR 差异。使用以下命令检测：

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/（较少使用；仅在将这项技能引入代码库时使用）。

发布就绪判定

每次审计都会在逐项列出发现之前，先输出顶层判定：

═══════════════════════════════════════════════════════════
SHIP VERDICT: ❌ NOT READY (1 release-blocker)

Surface count:           3 (CheckoutForm, PaymentStep, ConfirmStep)
Findings:                7
  Release blockers:      1   ⛔  Form data loss on validation (PaymentStep.tsx:42)
  Fix this sprint:       3   ⚠️
  Backlog:               3   📋

Defer-to (not audited here):
  Performance (CWV):     Run Lighthouse
  Bundle size:           Run size-limit
  WCAG violations:       Run axe-core
═══════════════════════════════════════════════════════════

判定等级：

• ✅ READY — 0 个发布阻断项，≤3 个本迭代修复项
• ⚠️ READY WITH FOLLOW-UP — 0 个发布阻断项，≥4 个本迭代修复项
• ❌ NOT READY — ≥1 个发布阻断项
• 🚫 INCOMPLETE — 审计自检失败（重新运行）

输出适配器

三种格式，均由同一份 JSON 渲染。根据上下文选择。

适配器	使用场景	格式
终端表格	本地开发，快速浏览	按界面分组的紧凑 5 列表格
PR 评论	GitHub / Vercel 评审	使用 suggestion 代码块展示行内差异的 Markdown
CI JSON	流水线、仪表板	符合 references/output-schema.md 的严格 JSON

请参阅 references/output-adapters.md，了解原样模板和字段映射。

跳过协议

可以使用行内注释有意忽略某项发现：

{/* ux-audit-ignore:focus-not-restored — intentional: parent owns focus */}
<Dialog open={open} onClose={onClose}>

Slug 必须与规则 slug 匹配。忽略的项目会显示在审计摘要中，供评审者确认其意图。

参考文件

文件	阅读时机
references/feature-playbooks.md	步骤 2-3 — 检测功能并选择对应的操作手册
references/modern-failure-modes.md	按类别分组的全部 33 条现代规则索引
references/states-coverage.md	按组件类型验证加载／空／错误／禁用状态的覆盖情况
references/ship-readiness.md	步骤 5 — 为每项发现分配发布等级并查看示例
references/output-adapters.md	步骤 6 — 将发现格式化为终端／PR 评论／JSON
references/defer-to-other-tools.md	识别应交由其他工具处理的问题（CWV、WCAG、包体积等）
references/output-schema.md	发现项和判定的严格 JSON 架构
references/observational-rubrics.md	第 3 层评分规则（含锚点的 1-5 分评分）
rules-modern/<category>-<slug>.md	步骤 4 — 执行第 2 层现代前端检查
rules-modern/_sections.md	现代规则层的类别索引
rules/<prefix>-<slug>.md	步骤 4 — 执行第 3 层 Laws of UX 检查
rules/_sections.md	Laws of UX 规则层的类别索引

注意事项

• 默认不要审计整个代码库。 默认采用感知差异的模式；全量扫描需显式指定。
• 不要与其他工具重复检查。 如果发现的问题是“LCP > 4s”，那属于 Lighthouse 的检查——提供链接，不要复述。如果是“缺少 alt 文本”，那属于 axe 的检查——提供链接，不要复述。
• 不要跳过功能检测步骤。 对每个文件运行所有规则会产生噪声；根据每项功能运行恰当的操作手册才能发现有效问题。
• 不要把每项发现都定为 release-blocker。 仅将真正阻碍发布的问题（数据丢失、关键路径中断、暗黑模式）列为该等级。滥用会削弱信号。
• 适用时，提出的修复方案必须使用现代 React API。 “添加加载状态”不够具体；“用 <Suspense fallback={<Skeleton />}> 包裹，并在触发时使用 useTransition”才具有可操作性。
• 先处理 JSON，再渲染 Markdown。 即使用户需要 Markdown，也要先构建 JSON 文档，以确保不同运行中的发现可审计。
• 不要堆砌 Laws of UX 相关发现。 第 3 层是备用层。如果某项发现既可用第 2 层表述（“缺少错误状态”），也可用第 3 层表述（“违反 Postel 定律”），则使用第 2 层——它更具体，也更具可操作性。
• 不要逐字引用来源。 每条规则都经过转述；lawsofux.com 使用 CC BY-NC-SA 许可，直接引用会污染此技能。
• 不要捏造检测结果。 如果无法 grep 文件或查看 JSX，请将发现标记为 unknown 并说明原因。没有证据时，绝不要声称发现了问题。

审计自检

如果符合以下任一条件，则将审计自行标记为 INCOMPLETE：

• 实际运行的规则少于操作手册计划的数量
• 超过 30% 的规则返回 unknown（证据不足）
• 任何失败／警告结果都未引用 file:line
• 未提供 reproduceSteps 或 fix 代码片段
• 每条规则表面上的耗时中位数短得不合常理（各结果之间没有 Read 或 Grep 工具调用）
• 所有结果都落在同一层级（疑点：未作判断，全部一概归类）