review

review

评审是一份需要修改事项的清单，每项都包含位置、修复方式和原因。其他内容都只是观点。此技能会生成这份清单。

评审原则

• 依据证据，而非品味。每条问题都要引用 path/file.tsx:42，并说明当前内容。如果无法指出具体位置，就不算发现了问题。
• 按项目惯例修复。如果项目使用 Tailwind，修复方式就应是修改类名；如果项目定义了设计令牌，修复方式就应指定令牌。要求采用不同技术栈不算问题。
• 认真检查后列出的短清单，胜过为了显得全面而凑出的长清单。最多列出 15 条。如果问题更多，列出影响最大的 15 条，并说明还有其他问题。
• 有意为之的选择不算问题。密度、圆角、语气和配色由项目自行决定，除非违反硬性规则（对比度、焦点、点击区域大小、状态缺失）。
• 不要说“可以考虑”。直接说明要改什么。

1. 范围

评审前先说明评审对象：一个屏幕、一条流程、一个组件或一份差异。如果请求指定了分支或 PR，范围就是改动的文件及其影响到的界面。如果请求针对某个屏幕，范围就是该屏幕的所有状态，以及 375px 和 1440px 两种视口。

如果范围过大，无法可信地完成检查，就缩小到一条完整流程，说明具体检查了哪条流程，以及排除了哪些内容。绝不要暗示检查过未检查的界面。

2. 预先了解

先花两分钟了解情况，再作判断：

• 框架、样式系统、组件库、动效库、图标集。
• 设计令牌：颜色、间距、缓动、圆角和 z-index 的定义位置。问题报告中会注明这些令牌。
• 文档约定：CLAUDE.md、AGENTS.md、CONTRIBUTING.md、设计文档。与文档约定相悖的问题，应针对约定统一报告一次，而不是逐一报告每个实例。
• 如何运行项目。评审交互行为时必须运行界面；仅检查源代码的评审则要说明这一点。

3. 按以下顺序检查

基础问题常被表面润色掩盖。自下而上检查，避免重要问题被外观细节淹没。

顺序	领域	检查内容
1	功能	屏幕的核心操作是否一目了然？能否完成？是否有任何内容阻碍完成？
2	无障碍	键盘可达性、焦点可见性与管理、控件名称、对比度、div onClick、仅通过颜色传达的信号、减少动态效果时的行为
3	状态	加载、空内容、错误、部分完成、繁忙、禁用、成功状态。数据到达时的布局偏移。加载指示器的时机
4	文案	按钮上的动词、句首大小写、提供后续步骤的错误提示、带操作入口的空状态、未替换的占位文本
5	空间	超出设计尺度的数值、节奏不均、组件外边距、对齐方式、375px 视口下的边距、横向滚动
6	字体	字号过多、仅靠字号建立层级、字号对应的行高与字距、等宽数字、重要文本被截断、孤行
7	表面样式	设计令牌之外的十六进制颜色值、不同主题下的边框与阴影、强调色使用过度、是否检查两种主题、选中状态与滚动条
8	交互	悬停效果是否未设门槛、缺少按下状态、禁用与繁忙状态是否混淆、繁忙时宽度变化、复制反馈、Escape 键与焦点返回
9	动效	transition: all、入场时使用 ease-in、产品 UI 中时长超过 300ms、键盘操作触发动效、scale(0)、缺少离场动画、未适配减少动态效果
10	润色	标题、网站图标、OG、外部链接标记、图片尺寸、粘性标题遮挡锚点、404

每个领域都有一项详细技能，包含完整规则（a11y、states、ux-copy、space、type、surface、interaction、motion、polish）。根据评审范围加载所需技能；不要凭记忆重建这些规则。

4. 严重程度

级别	含义	示例
阻断	有人无法完成任务	键盘陷阱、无法触达的控件、主要操作的对比度低于 3:1、出错时提交没有任何反应
高	有人经常会失败或感到困惑	缺少错误状态、加载时布局偏移、仅悬停时才显示的提示、含糊的按钮标签
中	感觉有缺陷或廉价；大多数人都会注意到	没有按下状态、transition: all、微调器闪现、孤立的标题、各处间距都偏离比例
低	受过训练的人才会注意到	图标低了 1px、标签的字距、深色模式下的阴影

先按级别排序，再按有多少人、多频繁地遇到问题排序。主要按钮上的低级问题，优先级高于没人访问的设置页面上的中级问题。

5. 输出

一个表格。表格之前只能有范围说明行和侦察说明行。表格之后只能有结论，以及（如有）排除项列表。

Scope: /settings/profile at 375px and 1440px, both themes, running locally.
Stack: Next.js, Tailwind v4 with tokens in globals.css, Base UI, Motion. Conventions: CLAUDE.md.

| # | Level | Where | Now | Change to | Why |
| --- | --- | --- | --- | --- | --- |
| 1 | Blocking | `ProfileForm.tsx:88` | `<div onClick={save}>` | `<button type="submit">` | not keyboard reachable; Enter does not submit |
| 2 | High | `ProfileForm.tsx:41` | error shown only as red border | message under field, `aria-describedby`, focus first invalid | user cannot tell what is wrong |
| 3 | Medium | `Avatar.tsx:12` | `transition: all 0.3s` | `transition: transform 120ms var(--ease-out-expo)` | `all` transitions layout properties; 300ms is slow for hover |
| … |

Verdict: Not ready. Fix 1–2, then 3–7 in this change; 8–12 can follow.
Excluded: the billing tab (separate flow), the mobile nav (not in scope).

表格规则：

• Where 是文件和行号；如果在没有源代码的情况下审查正在运行的页面，则填写选择器。
• Now 是实际存在的内容：观察到的值、标记或行为。
• Change to 是符合项目惯例的具体替换方案。不要写“改进”或“考虑”。
• Why 用一个分句说明用户受到的影响，而不是规则名称。
• 每行都必须包含以上四项。不要列出偏好问题。

结论只能是以下之一：Ready、Ready after blocking fixes、Not ready。说明哪些发现是放行条件。

6. 不要做什么

• 不要在评审中重写组件。评审内容就是问题列表；修复是另一个步骤（如有要求）。
• 不要按实例逐条列出相同问题。“14 个文件中有 transition: all”应合并为一行，并注明数量和应使用的设计令牌。
• 不要报告范围内根本不需要的内容缺失（例如，打印样式表“没有深色模式”）。
• 不要评分。没有分数，只有列表和结论。
• 不要因为其他方面做得好，就淡化阻断级发现。

返回前自检

• 已说明范围和技术栈
• 每行都标有我实际检查过的位置
• 按影响排序，而非按发现顺序排列
• 不超过十五项
• 每项修复都符合项目惯例
• 结论指出了放行条件对应的条目
• 表格中没有偏好问题

目录精选

• Nielsen Norman Group — 有助于制定良好评审标准的启发式原则。
• 让界面体验更好的细节 — 那些细微的发现。
• axe、Lighthouse — 自动化初步检查；其余靠人工审查。
• Polypane — 在一个窗口中查看所有断点和主题。
• 更多内容见 stealth.pm/tools。