design-review

设计评审

对 UI 代码进行设计评审，并按优先级返回评估意见。评审视角遵循 Emil Kowalski 的设计工程理念——品味是差异化的关键；那些不易察觉的细节会不断累积；引导视线关注重点——并结合 Refactoring UI、WCAG 和 MDN 中的启发式原则，将其落实为具体评审标准。

这是一项只读评审技能：用于诊断问题并提出修复建议，不会改写代码库。每条发现都会指出代码采用了哪种不理想的默认做法、具体修复方案，以及问题的重要性。

适用场景

• 用户要求“评审这个 UI”、进行“设计评审”或“批评”某个组件、屏幕或页面。
• 用户表示输出“看起来不太对劲”“像 AI 生成的”“像线框图”或“感觉很普通”，并想了解原因。
• PR 涉及 CSS/JSX/Tailwind，用户希望在合并前获得设计反馈。
• 用户希望提升现有界面的视觉精致度或无障碍性。

不适用于从头构建 UI（使用 web-taste），也不适用于详尽的动画规则集（使用 emilkowal-animations）。

如何进行评审

**两种模式。**默认采用静态评审，即阅读代码。运行时评审还会驱动真实浏览器，测量代码本身无法体现的内容——动画时序和丢帧、布局偏移、实时焦点顺序和无障碍树，以及端到端点击完成的多页面流程。当评审结论取决于渲染行为时（motion-、interact- 和 flow- 类别），请切换到运行时评审，并参阅 runtime-capture.md。

1. **了解界面——0.5 秒测试。**逐行阅读之前，先想象渲染后的屏幕。视线首先落在哪里？是否有单一的视觉焦点，还是所有内容的权重都相同？这有助于确定哪些类别对当前 UI 最重要。
2. 按优先级顺序检查各类别（见下表）。对于代码中的每项设计决策，阅读对应的参考文件，并据此检查代码。视觉层级和间距是最常见、影响最大的问题——从这里开始。
3. **对于多页面或由交互驱动的 UX，请在浏览器中走查。**如果需求描述的是一个流程（例如“评审这个新手引导流程”），或问题出现在动态交互中（卡顿、路由闪白、焦点丢失），请参阅 runtime-capture.md 获取运行时证据，确保 Before 栏中记录的是测量值，而非猜测。
4. 将每个问题记录为一条发现，包含 Before（具体代码或测量值）、After（明确的修复方案）、Why（设计原则）以及结合上下文判定的严重程度。
5. 最后给出评审结论：按影响程度排列最重要的 3 项修复建议，让作者知道应先修改什么。

输出格式（必需）

请将发现报告为单个 Markdown 表格，每个问题占一行。请勿将发现写成散文，也不要把 Before: / After: 分成单独的行。

严重程度	修改前	修改后	原因
高	transition: all 300ms ease-in	transition: opacity 180ms cubic-bezier(0.23, 1, 0.32, 1)	ease-in 会让进入动画显得迟缓；请指定属性，并使用明显的缓出曲线
高	所有按钮都使用 bg-indigo-600	一个实心主按钮；其他按钮使用幽灵或描边样式	按钮权重相同会互相争抢注意力；设置一个主按钮可以让下一步一目了然
中	在 #fff 背景上使用 color: #000	color: hsl(222 47% 11%)	纯黑比墨色更刺眼，视觉上显得生硬
严重	<div onClick={remove}>	<button type="button" onClick={remove}>	键盘无法访问 div，屏幕阅读器也无法识别

错误格式——切勿这样做：

Before: transition: all 300ms
After: transition: opacity 180ms ease-out
────────────────────────────
Before: color #000
After: color slate-900

严重程度指南（根据每项问题对当前 UI 的影响分配）：

严重程度	含义
严重	破坏可用性或无障碍体验——对比度不达标、无法通过键盘访问、文本无法阅读
高	明显损害设计——缺乏层次、间距拥挤、主操作互相争抢
中	存在明显的细节瑕疵——使用默认缓动、行高统一、缺少按下反馈
低	细微调整——某个值略微偏离比例尺度

最后请写：优先修复的 3 项——按作者应着手处理的顺序，列出影响最大的几项。

规则类别

#	类别	前缀	涵盖内容
1	视觉层次	hier-	焦点、强调手法、一个主操作、数值优先于标签、用留白替代边框
2	间距与布局	space-	间距比例、充足留白、邻近分组、限制宽度
3	排版	type-	字体比例、行长、行高、对齐、易读的正文
4	颜色与对比度	color-	近黑色文本、WCAG 对比度、HSL 色阶、克制的强调色、颜色加提示
5	组件状态与反馈	state-	按下反馈、可见焦点、完整的状态矩阵、空状态
6	动效与动画	motion-	目的与频率、缓出曲线、低于 300ms、进入方向/缩放、仅使用变换
7	响应式设计与触控	resp-	流式移动优先布局、44px 点击目标、限制悬停状态
8	无障碍与语义	access-	语义元素、无障碍名称、减少动态效果
9	流程与导航	flow-	应用外壳一致性、视图状态持久化、入口完整性、路径指引
10	交互连贯性	interact-	衔接路由切换、异步反馈、导航时的焦点

快速参考

1. 视觉层次（hier-）

• hier-one-focal-point — 为每个屏幕设置一个明确的焦点
• hier-emphasis-color-weight — 使用颜色和字重设置强调，而非仅依赖字号
• hier-one-primary-action — 每个视图只设置一个主操作
• hier-values-over-labels — 让数值比标签更醒目
• hier-replace-borders-with-space — 用间距和背景替代边框

2. 间距与布局（space-）

• space-use-a-scale — 按照统一的比例尺度设置间距
• space-start-generous — 为布局留出比直觉所需更多的空白
• space-proximity-groups — 通过调整间距展示分组关系
• space-constrain-measure — 限制页面容器宽度并使其居中

3. 排版（type-）

• type-modular-scale — 从小型字体比例尺中选择字号
• type-limit-line-length — 限制正文行长，提升可读性
• type-line-height-by-size — 根据字号设置行高
• type-left-align-prose — 将多行文本左对齐
• type-readable-body-size — 确保正文字号足够大、字重足够清晰，便于阅读

4. 颜色与对比度（color-）

• color-avoid-pure-black — 使用近黑色，而非纯黑色
• color-meet-contrast — 确保正文文本符合 WCAG 对比度要求
• color-hsl-scales — 使用 HSL 色阶定义颜色
• color-limit-accents — 将调色板限制为一种强调色和中性色
• color-not-only-signal — 用另一种提示与颜色搭配来表示状态

5. 组件状态与反馈（state-）

• state-press-feedback — 为可按压元素提供按下反馈
• state-focus-visible — 保留易于访问的焦点指示器
• state-design-all-states — 设计所有交互状态，而不只是默认状态
• state-empty-state — 设计空状态并提供引导

6. 动效与动画（motion-）

• motion-needs-purpose — 只在有明确目的时添加动画
• motion-ease-out-custom — 为 UI 过渡使用带自定义曲线的缓出效果
• motion-under-300ms — 将 UI 过渡时长控制在 300ms 以内
• motion-enter-origin-scale — 从接近最终尺寸的状态和触发元素的原点进入
• motion-transform-opacity-only — 只为 transform 和 opacity 添加动画

对于拖动、手势、弹簧效果、交错动画、clip-path 以及完整的时长／缓动表，请参考 emilkowal-animations 技能。

7. 响应式设计与触控（resp-）

• resp-fluid-not-fixed — 采用移动端优先设计，并使用流式宽度
• resp-touch-target-size — 将触控目标尺寸设为至少 44px
• resp-gate-hover — 通过指针媒体查询限制仅悬停时显示的功能

8. 无障碍与语义（access-）

• access-semantic-elements — 使用语义化元素实现交互控件
• access-name-icon-controls — 为纯图标控件提供无障碍名称
• access-respect-reduced-motion — 遵循减少动态效果偏好

9. 流程与导航（flow-）

评审跨页面的体验，这是单屏评审无法发现的。请在浏览器中走查流程（runtime-capture.md）。

• flow-consistent-shell — 确保应用外壳在各页面间保持一致
• flow-preserve-state-on-nav — 在导航过程中保留滚动位置和视图状态
• flow-entry-point-integrity — 确保每个页面都能作为首个入口正常使用
• flow-wayfinding — 显示用户所在位置以及返回路径

10. 交互连续性（interact-）

评估体验能否随时间推移和跨越不同状态保持连续——这是截图无法呈现的维度。最好结合捕获的跟踪记录（runtime-capture.md）进行评估。

• interact-bridge-route-transitions — 衔接路由切换，避免屏幕短暂变为空白
• interact-feedback-spans-async — 在交互进行期间填补等待空档
• interact-move-focus-on-navigation — 客户端导航后将焦点移至新内容

使用方法

当代码审查中遇到相关决策时，请阅读对应的参考文件。每条规则都会指出要纠正的错误默认做法，然后展示规范修复方式（仅当错误做法确实容易造成问题时，才会对比错误与正确做法）。请在“Why”列中注明规则的标识符，以便作者进一步了解。

• 运行时捕获 — 驱动真实浏览器（chrome-devtools-mcp），在静态阅读不足以判断时，测量动态效果、卡顿、焦点顺序和多页面流程
• 章节定义 — 类别结构和顺序
• 规则模板 — 用于添加新规则
• AGENTS.md — 自动生成的所有规则目录

相关技能

• emilkowal-animations — 全面的动画规则集（缓动、手势、弹簧、交错）；本技能将动画细节交由它处理。
• web-taste — 从零开始打造有品位的 React/Next/Tailwind UI（对应的构建指南）。
• tailwind-ui-refactor — 将这些修复应用为 Tailwind 重构。
• ui-design — 更广泛的构建阶段前端参考（Core Web Vitals、表单、深色模式）。对于两者重叠的内容（语义、对比度、焦点、单一主要操作），编写代码时请参考 ui-design，审查代码时请参考 design-review。

参考文件

文件	描述
references/_runtime-capture.md	浏览器驱动的捕获指南（通过 mcporter 使用 chrome-devtools-mcp）
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和来源引用