ux-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UX Audit

UX审计

Static UX-quality reviewer for React/Next.js code. Operates at the feature level (a checkout flow, an onboarding flow, a dashboard) — not the principle level. Answers one question for a frontend dev with a PR open: "which of these will hurt users in production, and which are nice-to-haves?"

针对React/Next.js代码的静态UX质量评审工具。以功能层面（结账流程、注册流程、仪表盘）为操作对象——而非原则层面。为有PR待处理的前端开发者解答一个问题：哪些问题会在生产环境中影响用户体验，哪些只是锦上添花的优化项？

What this skill IS

本工具的定位

A diff-aware reviewer that audits changed files in a PR
A feature-level checklist runner: detects "this is a sign-in flow" / "this is a checkout" / "this is a modal" and runs the right playbook
A ship-readiness verdict generator: every finding gets
```
release-blocker | fix-this-sprint | backlog
```
A concrete-fix advisor that uses modern React 19 APIs (
```
useActionState
```
,
```
useFormStatus
```
,
```
useOptimistic
```
,
```
useTransition
```
,
```
<Suspense>
```
, error boundaries)

具备差异感知能力的评审工具，仅审计PR中的变更文件
功能级检查清单执行器：可识别「这是登录流程」/「这是结账流程」/「这是模态框」并运行对应的检查手册
发布就绪判定生成器：每个发现都会被标记为
```
release-blocker | fix-this-sprint | backlog
```
（发布阻断项/本迭代修复/待办积压）
具体修复方案顾问：使用现代React 19 API（
```
useActionState
```
、
```
useFormStatus
```
、
```
useOptimistic
```
、
```
useTransition
```
、
```
<Suspense>
```
、错误边界）提供修复建议

What this skill IS NOT

本工具不负责的内容

Defer to the right tool. Do not duplicate what these already do well:

Concern	Use this tool instead	Why
Core Web Vitals (LCP, CLS, INP)	Lighthouse + web-vitals + Vercel Agent	Field + lab measurement, not static
WCAG rule violations	axe-core / jsx-a11y	Authoritative rule list, structured violations
a11y prevention at write time	eslint-plugin-jsx-a11y	Lint catches before runtime
Visual regression	Chromatic / Percy	Pixel-level diffs
Bundle size budget	size-limit / bundle-analyzer	Continuous budget tracking
Generic bug review	CodeRabbit / Vercel Agent	LLM bug review of the whole diff

When a finding overlaps any of the above, link out — don't restate.

See

references/defer-to-other-tools.md

for the full inventory.

请使用对应的专业工具。请勿重复以下工具已擅长处理的工作：

关注点	推荐工具	原因
核心Web指标（LCP、CLS、INP）	Lighthouse + web-vitals + Vercel Agent	需结合真实场景与实验室测量，非静态检查可覆盖
WCAG规则违规	axe-core / jsx-a11y	权威规则列表，结构化违规检测
编码阶段的无障碍预防	eslint-plugin-jsx-a11y	代码检查可在运行前捕捉问题
视觉回归	Chromatic / Percy	像素级差异对比
包大小预算	size-limit / bundle-analyzer	持续预算跟踪
通用漏洞评审	CodeRabbit / Vercel Agent	基于大语言模型的全差异漏洞评审

当发现的问题与上述工具的覆盖范围重叠时，请直接链接至对应工具说明——无需重复描述。

完整工具分工清单请查看

references/defer-to-other-tools.md

。

Audit Workflow

审计流程

Copy and track this checklist:

text

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

Scope. Default to
```
git diff --name-only main
```
if in a git repo with uncommitted changes; otherwise audit the explicit scope the user passes. Don't audit the whole codebase by default — noise floor is too high.
Detect features. Match on element semantics + filenames + route paths. A
```
<form>
```
with email + password = sign-in. A
```
<form>
```
with a multi-step indicator = onboarding. A
```
role="dialog"
```
= modal. See
```
references/feature-playbooks.md
```
for detection heuristics per feature.
Run playbook. Each feature has 5-7 ordered checks. Don't skip checks even when you expect them to pass; each pass goes into the audit-self-check.
Load rules. Two layers:
- rules-modern/
  (Layer 2) — modern frontend UX failure modes (state coverage, form preservation, focus mgmt, optimistic rollback, CLS, microcopy). This is where most findings come from.
- rules/
  (Layer 3) — Laws of UX (Hick's, Fitts's, Miller's, etc.). Used for cognitive/perceptual reasoning when Layer 2 doesn't apply.
Ship tier. Every finding gets one of three tiers (see
```
references/ship-readiness.md
```
):
- ```
release-blocker
```
  — fix before merge (data loss, broken auth, missing critical-path error state, dark patterns, focus traps that don't restore)
- ```
fix-this-sprint
```
  — merge but log issue (sub-44 px target on touch, missing skeleton, vague error, missing empty CTA)
- ```
backlog
```
  — track, ship (dark-mode untested, RTL not verified, microcopy nits)
Group + render. Group by surface (component file or page). Render with one of the three adapters in
```
references/output-adapters.md
```
.
Self-check. Verify the audit was actually run (rules executed > rules planned, file:line cited on every finding, fix snippet on every finding).

复制并跟踪以下检查清单：

text

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

范围确定：如果处于有未提交变更的git仓库中，默认范围为
```
git diff --name-only main
```
；否则审计用户指定的明确范围。默认不审计整个代码库——噪音过高。
功能识别：基于元素语义、文件名和路由路径进行匹配。包含邮箱+密码的
```
<form>
```
即为登录流程；包含多步骤指示器的
```
<form>
```
即为注册流程；
```
role="dialog"
```
即为模态框。各功能的识别规则请查看
```
references/feature-playbooks.md
```
。
执行检查手册：每个功能对应5-7项有序检查。即使预期检查会通过，也请勿跳过；每一项通过的检查都会纳入审计自我校验。
加载规则：分为两层：
- rules-modern/
  （第二层）——现代前端UX失效场景（状态覆盖、表单数据保留、焦点管理、乐观UI回滚、CLS、微文案）。大部分发现都来自这一层。
- rules/
  （第三层）——UX法则（希克定律、费茨定律、米勒定律等）。当第二层规则不适用时，用于认知/感知层面的推理。
发布层级分配：每个发现都会被分配至以下三个层级之一（详情请查看
```
references/ship-readiness.md
```
）：
- ```
release-blocker
```
  —— 合并前必须修复（数据丢失、认证失效、关键路径缺失错误状态、暗黑模式、无法恢复的焦点陷阱）
- ```
fix-this-sprint
```
  —— 可合并但需记录问题（触摸目标小于44px、缺失骨架屏、模糊错误提示、缺失空状态操作按钮）
- ```
backlog
```
  —— 跟踪后可发布（暗黑模式未测试、RTL未验证、微文案微调）
分组与渲染：按界面（组件文件或页面）分组。使用
```
references/output-adapters.md
```
中的三种适配器之一进行渲染。
自我校验：验证审计是否实际执行（已执行规则数>计划规则数、每个发现都标注了
```
file:line
```
、每个发现都提供了修复代码片段）。

Three audit layers

三层审计架构

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
  30 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.

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
  30 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.

Diff-aware mode

差异感知模式

Default scope is the PR diff. Detect with:

bash

git diff --name-only main -- '*.tsx' '*.jsx' '*.ts' '*.js' '*.css' '*.module.css'

Audit only those files. Surface the base branch in the output:

Auditing: 8 files changed vs main

For a quick local check (single component):

git diff --name-only HEAD -- src/Component.tsx

For a full sweep: explicit

--full src/

(rare; only when introducing the skill to a codebase).

默认范围为PR差异。通过以下命令检测：

bash

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-readiness verdict

发布就绪判定

Every audit emits a top-level verdict before per-finding details:

text

═══════════════════════════════════════════════════════════
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
═══════════════════════════════════════════════════════════

Verdict tiers:

✅ READY — 0 release-blockers, ≤3 fix-this-sprint
⚠️ READY WITH FOLLOW-UP — 0 release-blockers, ≥4 fix-this-sprint
❌ NOT READY — ≥1 release-blocker
🚫 INCOMPLETE — audit-self-check failed (re-run)

每次审计都会在具体发现详情前输出顶层判定结果：

text

═══════════════════════════════════════════════════════════
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 —— 审计自我校验未通过（需重新运行）

Output adapters

输出适配器

Three formats, all rendered from the same JSON. Pick based on context.

Adapter	When	Format
Terminal table	Local dev, fast scan	Tight 5-col table grouped by surface
PR comment	GitHub / Vercel review	Markdown with `suggestion` blocks for inline diffs
CI JSON	Pipelines, dashboards	Strict JSON per `references/output-schema.md`

See

references/output-adapters.md

for verbatim templates and field mappings.

三种格式，均基于同一JSON生成。根据使用场景选择：

适配器	使用场景	格式
Terminal table	本地开发、快速扫描	按界面分组的紧凑5列表格
PR comment	GitHub / Vercel评审	包含 `suggestion` 块的Markdown，用于内联差异
CI JSON	流水线、仪表盘	符合 `references/output-schema.md` 的严格JSON格式

详细模板和字段映射请查看

references/output-adapters.md

。

Skip protocol

跳过规则

A finding can be intentionally suppressed with an inline comment:

tsx

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

Slug must match the rule slug. Suppressions are reported in the audit summary so reviewers can verify intent.

可通过内联注释主动屏蔽某一发现：

tsx

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

注释中的slug必须与规则slug匹配。屏蔽操作会在审计摘要中报告，以便评审者验证意图。

Reference Files

参考文件

File	Read when
`references/feature-playbooks.md`	Step 2-3 — detecting features and selecting their playbooks
`references/modern-failure-modes.md`	Index of all 30 modern rules grouped by category
`references/states-coverage.md`	Validating loading/empty/error/disabled coverage per component type
`references/ship-readiness.md`	Step 5 — assigning each finding a ship tier with examples
`references/output-adapters.md`	Step 6 — formatting findings for terminal / PR comment / JSON
`references/defer-to-other-tools.md`	Recognizing concerns to delegate (CWV, WCAG, bundle, etc.)
`references/output-schema.md`	Strict JSON schema for findings + verdict
`references/observational-rubrics.md`	Layer 3 rubric rules (1-5 scoring with anchors)
`rules-modern/<category>-<slug>.md`	Step 4 — running a Layer 2 modern frontend check
`rules-modern/_sections.md`	Category index for the modern rule layer
`rules/<prefix>-<slug>.md`	Step 4 — running a Layer 3 Laws of UX check
`rules/_sections.md`	Category index for the Laws of UX rule layer

文件	阅读时机
`references/feature-playbooks.md`	步骤2-3 —— 识别功能并选择对应的检查手册
`references/modern-failure-modes.md`	所有30项现代规则的分类索引
`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 schema
`references/observational-rubrics.md`	第三层评分规则（1-5分锚定评分）
`rules-modern/<category>-<slug>.md`	步骤4 —— 执行第二层现代前端检查
`rules-modern/_sections.md`	现代规则层的分类索引
`rules/<prefix>-<slug>.md`	步骤4 —— 执行第三层UX法则检查
`rules/_sections.md`	UX法则规则层的分类索引

Gotchas

注意事项

Don't audit the whole codebase by default. Diff-aware mode is the default; full sweeps are explicit.
Don't duplicate other tools. If a finding is "LCP > 4s," that's Lighthouse — link, don't restate. If it's "missing alt text," that's axe — link, don't restate.
Don't skip the feature-detection step. Running every rule against every file produces noise; running the right playbook per feature produces signal.
Don't assign every finding
release-blocker
. Reserve that tier for genuine ship-blockers (data loss, broken critical path, dark patterns). Inflation kills the signal.
Don't suggest fixes without modern React APIs when applicable. "Add a loading state" is weak; "Wrap in
```
<Suspense fallback={<Skeleton />}>
```
and use
```
useTransition
```
for the trigger" is actionable.
Don't render markdown without a JSON pass first. Even when the user wants markdown, build the JSON document first to keep findings auditable across runs.
Don't pile on Laws of UX findings. Layer 3 is reserve. If a finding has both a Layer-2 framing ("missing error state") and a Layer-3 framing ("Postel's Law violation"), use Layer 2 — it's more specific and actionable.
Don't quote the source verbatim. Every rule paraphrases; lawsofux.com uses CC BY-NC-SA which would contaminate the skill.
Don't fabricate detections. If you can't grep the file or see the JSX, mark the finding
```
unknown
```
with a reason. Never claim a finding without evidence.

默认不审计整个代码库：差异感知模式为默认模式；全面扫描需显式指定。
不重复其他工具的工作：如果发现「LCP > 4s」，这属于Lighthouse的职责——直接链接，无需重复描述。如果发现「缺失alt文本」，这属于axe的职责——直接链接，无需重复描述。
请勿跳过功能识别步骤：对每个文件运行所有规则会产生大量噪音；针对每个功能运行对应的检查手册才能产生有效信号。
请勿将所有发现标记为
release-blocker
：该层级仅用于真正的发布阻断项（数据丢失、关键路径失效、暗黑模式）。过度标记会降低信号有效性。
适用时请使用现代React API提供修复建议：「添加加载状态」过于笼统；「用
```
<Suspense fallback={<Skeleton />}>
```
包裹，并为触发操作使用
```
useTransition
```
」才具有可操作性。
请勿直接渲染Markdown而不先生成JSON：即使用户需要Markdown格式，也请先生成JSON文档，以便跨审计周期保持发现结果的可追溯性。
请勿过度使用UX法则发现结果：第三层为备用层。如果一个发现同时具备第二层框架（「缺失错误状态」）和第三层框架（「违反Postel定律」），请使用第二层描述——更具体且更具可操作性。
请勿直接引用源内容：所有规则需进行改写；lawsofux.com采用CC BY-NC-SA许可，直接引用会导致本工具的许可污染。
请勿伪造检测结果：如果无法搜索文件或查看JSX，请将发现标记为
```
unknown
```
并说明原因。绝不无证据地声称存在问题。

Audit-self-check

审计自我校验

Self-flag the audit as

INCOMPLETE

if any of these are true:

Fewer rules ran than the playbook's planned count
More than 30% of rules returned
```
unknown
```
(insufficient evidence)
No
```
file:line
```
cited on any fail/warn finding
No
```
reproduceSteps
```
or
```
fix
```
snippet provided
Median apparent time-per-rule was implausibly short (no Read or Grep tool calls between findings)
Every finding ended up in the same tier (suspect: blanket-assignment without judgment)

如果出现以下任一情况，需将审计标记为

INCOMPLETE

：

已执行规则数少于检查手册的计划规则数
超过30%的规则返回
```
unknown
```
（证据不足）
任何失败/警告发现未标注
```
file:line
```
未提供
```
reproduceSteps
```
或
```
fix
```
代码片段
单条规则的平均执行时间明显过短（发现之间未调用Read或Grep工具）
所有发现都被分配至同一层级（可疑：未经过判断的批量分配）