design-review

设计审查技能

状态：已可用于生产 ✅ 最后更新：2025-11-20 依赖项：Playwright MCP 或 Chrome DevTools 方法论：7 阶段系统化审查（灵感源自 Stripe、Airbnb、Linear）

---

快速开始

1. 检查先决条件

开始设计审查前，请确认浏览器自动化工具可用：

选项 A：Playwright MCP（推荐用于交互测试）

• 查看 playwright-testing 技能，了解 Playwright 的设置
• 提供浏览器自动化、屏幕截图、视口测试和控制台监控

选项 B：Puppeteer CLI（用于截图和性能分析的替代方案）

• 通过 npm install -g puppeteer 直接安装 Puppeteer
• 提供屏幕截图、性能分析和网络监控

完整的浏览器工具参考，请参阅 references/browser-tools-reference.md。

2. 了解审查范围

对于 PR 审查：

# Analyze git diff to understand scope
git diff --name-only origin/main...HEAD

# Read PR description for context

对于常规 UI 审查： 只需提供预览 URL 和组件／页面说明。

3. 执行 7 阶段审查

按照以下系统化清单进行操作。每个阶段都有具体目标和测试流程。

---

7 阶段审查方法论

阶段 0：准备

目标： 了解上下文并设置测试环境。

步骤：

1. 阅读 PR 描述或审查请求，了解：

   • 修改动机
   • 实现范围
   • 开发者提供的测试说明
   • 预期行为

2. 分析代码差异（如果有 PR）：

   git diff origin/main...HEAD
   

   找出修改的文件（组件、样式、测试）

3. 设置实时预览环境：

   • 使用浏览器工具访问预览 URL
   • 设置初始视口：1440x900（桌面）
   • 截取基准屏幕截图以供参考

4. 审阅设计原则（如果项目有自定义指南）：

   • 查看项目的 CLAUDE.md，了解设计规范
   • 查阅组件库文档
   • 记录设计系统令牌和模式

何时跳过： 不涉及 Git 上下文的快速组件审查。

---

阶段 1：交互与用户流程

目标： 确认交互体验符合预期。

完整交互指南：测试交互状态、表单、按钮、导航流程、微交互、模态框或键盘导航时，请加载 references/interaction-patterns.md。

快速清单：

• 测试所有元素的 5 种交互状态（默认、悬停、激活、焦点、禁用）
• 执行主要用户流程（提交表单、导航、关键操作）
• 确认破坏性操作带有确认对话框
• 评估用户感知的性能（加载状态、乐观 UI）

问题分级： [阻断] 关键流程失效 | [高] UX 较差／缺少焦点状态 | [中] 缺少润色 | [小问题] 轻微时序问题

---

阶段 2：响应式测试

目标： 确保设计适用于所有视口尺寸。

完整响应式指南：测试视口、触控目标、移动端导航、图像响应式效果或排查水平滚动问题时，请加载 references/responsive-testing.md。

测试 3 种视口：

• 桌面（1440px）：最佳布局、完整功能集
• 平板（768px）：平滑适配、44×44px 触控目标、导航折叠
• 移动端（375px）：无水平滚动、文本最小 16px、适合移动端的导航

快速测试：

mcp__playwright__browser_resize(width: 1440, height: 900)  # Desktop
mcp__playwright__browser_resize(width: 768, height: 1024)  # Tablet
mcp__playwright__browser_resize(width: 375, height: 667)   # Mobile
mcp__playwright__browser_take_screenshot(fullPage: true)

问题分级： [阻断] 布局失效 | [高] 水平滚动／元素重叠 | [中] 间距不理想 | [小问题] 轻微不一致

---

阶段 3：视觉润色

目标： 评估美观度和视觉一致性。

设计原则指南：评估排版层级、间距/布局、配色方案、对齐/网格、视觉层级、图像质量或 S 级设计标准时，加载 references/visual-polish.md。

快速评估（5 项标准）：

1. 布局与间距：网格对齐、8px 比例、设计令牌（不使用 17px 之类的随意数值）
2. 排版：清晰的 H1>H2>H3 层级、1.5-1.7 行高、有限的字体粗细
3. 颜色：设计系统令牌、语义化使用（红色=错误，绿色=成功）、品牌一致
4. 图像：高分辨率（无像素化）、宽高比正确、尺寸经过优化、包含替代文本
5. 视觉层级：主要操作醒目、视觉动线自然、留白合理

分级： [阻断级] 文本无法辨认/图像损坏 | [高] 明显不一致 | [中] 间距/对齐问题 | [小问题] 美观偏好

---

阶段 4：无障碍（WCAG 2.1 AA）

目标： 确保为所有用户提供包容性设计。

完整的 WCAG 2.1 AA 检查清单：验证 WCAG 合规性、测试键盘导航、检查颜色对比度、审查语义化 HTML 或使用无障碍测试工具（Lighthouse、axe、WAVE）时，加载 references/accessibility-wcag.md。

WCAG 快速测试（4 项原则）：

1. 可感知性：图像的替代文本、颜色对比度（文本 4.5:1，UI 组件 3:1）、语义化 HTML
2. 可操作性：键盘导航（Tab 顺序符合逻辑、所有交互元素均显示焦点、可用 Enter/Space 激活、Escape 可关闭模态框、无键盘陷阱）
3. 可理解性：标签清晰、错误消息有帮助、导航/术语一致
4. 健壮性：HTML 有效、ARIA 属性正确（角色、状态、属性）

关键测试：

• 使用 Tab 遍历整个页面（确认焦点状态可见、顺序符合逻辑、无键盘陷阱）
• 使用 WebAIM Contrast Checker 测试（所有文本/UI 对比度 ≥4.5:1 或 3:1）
• 确认表单标签与输入框关联（<label for="id"> 或 aria-label）
• 检查语义化 HTML（h1→h2→h3 不跳级，使用 <button> 而非 <div onClick>）

分级： [阻断级] 无法通过键盘访问核心功能 | [高] 违反 WCAG AA | [中] 语义化 HTML 问题 | [小问题] 增强无障碍性

---

阶段 5：健壮性测试

目标： 验证对边缘情况和错误条件的处理。

测试场景：

5.1 表单验证

• 提交必填字段为空的表单
• 输入无效数据（错误的电子邮件格式、超出范围的数字）
• 测试字段级验证（实时反馈）
• 确认错误消息清晰且提供指导
• 测试成功提交流程（确认消息）

5.2 内容溢出

• 长文本字符串：非常长的姓名、电子邮件、标题
• 大量项目：大型列表、包含数百行的表格
• 深层嵌套内容：包含大量回复的评论
• 空状态：没有可显示的数据（显示有帮助的消息）

常见的溢出问题：

• 文本破坏布局（溢出容器）
• 截断内容时没有省略号或工具提示
• 大型列表导致性能问题
• 缺少空状态设计

5.3 加载与错误状态

• 加载状态：骨架屏、旋转指示器、进度指示器
• 错误消息：清晰且可执行的错误描述
• 重试机制：允许用户重试失败的操作
• 超时处理：妥善处理缓慢/失败的请求
• 乐观更新：立即反馈，失败时回滚

测试步骤：

# Simulate slow network
# Check browser DevTools Network tab → throttling

# Force error states
# Test with invalid API responses or network failures

常见问题：

• 没有加载指示器（看起来像是卡住了）
• 错误消息含糊不清（“发生错误”）
• 失败后没有重试机制
• 内容加载时布局跳动

分级优先级：

• [阻断级] 边缘情况下发生崩溃或完全失效
• [高] 错误处理不佳或状态令人困惑
• [中] 缺少边缘情况处理或存在轻微问题
• [小问题] 加载状态美观度或细节润色

阶段 6：代码健康度

目标： 确保实现易于维护且保持一致。

代码模式指南：评估组件复用（DRY 原则）、设计令牌的使用（颜色、间距、排版）、模式一致性（命名、文件结构、API 模式），或识别危险信号（重复代码、魔法数字、抽象失效）时，请加载 references/code-health-patterns.md。

快速审查（3 项标准）：

1. 组件复用：无复制粘贴代码，提取共享组件，优先组合而非重复
2. 设计令牌：使用 CSS 变量定义颜色／间距／排版（不使用 margin: 17px 之类的魔法数字），边框圆角保持一致
3. 模式一致性：遵循代码库中的模式，命名约定一致，文件结构清晰

分级： [High] 引入技术债务／破坏模式 | [Medium] 错过复用机会 | [Nitpick] 代码风格偏好

---

阶段 7：内容与控制台

目标： 检查细节是否完善、技术内容是否正确。

7.1 内容审查

检查以下方面：

• 语法和拼写：没有拼写错误或语法问题
• 清晰度：标签和说明明确无歧义
• 语气一致性：符合品牌语调（正式／轻松）
• 占位文本：已替换为实际内容（没有“Lorem ipsum”）
• 微文案质量：错误消息、按钮标签和工具提示能提供帮助

常见内容问题：

• UI 文本中的拼写错误
• 生产环境中遗留的占位文本
• 含糊的标签（“提交”而不是“保存更改”）
• 术语不一致
• 没有帮助的错误消息（“错误”而不是“电子邮件格式无效”）

7.2 控制台检查

测试步骤：

# Using Playwright MCP
mcp__playwright__browser_console_messages()

# Using Chrome DevTools
# Open DevTools → Console tab

检查以下问题：

• JavaScript 错误：未捕获的异常、空引用
• React 警告：key prop 警告、生命周期问题
• 网络故障：API 请求失败、404 错误
• 弃用警告：使用旧 API 的警告
• 性能警告：渲染缓慢、内存泄漏

分级优先级：

• [Blocker] 导致功能异常的控制台错误
• [High] 面向用户文本中的语法错误或令人困惑的内容
• [Medium] 控制台警告或轻微的内容问题
• [Nitpick] 内容润色、轻微的控制台杂音

---

沟通原则

1. 说明问题，而非开处方

描述问题及其影响，而不是解决方案。由开发者决定如何实现。

❌ 指定解决方案（避免）： “将边距改为 16px”

✅ 聚焦问题（推荐）： “此处的间距与相邻元素不一致，造成视觉杂乱，分散了用户对主要 CTA 的注意力。当前间距破坏了设计系统既有的节奏。”

2. 分级矩阵

为每个问题明确标注优先级：

优先级	标准	所需操作
[Blocker]	严重故障、核心功能失效、严重的无障碍违规	合并前必须修复
[High-Priority]	严重的 UX 问题、明显的设计不一致、WCAG 违规	应在合并前修复
[Medium-Priority]	改进项、轻微的不一致、边缘情况处理	可考虑在后续 PR 中处理
[Nitpick]	审美偏好、轻微润色、主观意见	可选优化

重要： 所有细枝末节问题前都要加上“Nit:”，以表明其优先级较低。

3. 基于证据的反馈

视觉问题务必提供截图。截图应：

• 清晰展示问题
• 包含相关背景（周围的元素）
• 标明需要关注的位置（必要时使用箭头或高亮）

示例：

### [High-Priority] Poor contrast on disabled button

**Problem:** Disabled button text has insufficient contrast (2.1:1), failing WCAG AA
standard (requires 4.5:1). Users with low vision may not recognize the button as disabled.

**Screenshot:** [Attach screenshot showing disabled button]

**Impact:** Accessibility violation, potential confusion for users with visual impairments.

4. 先肯定优点

列出问题前，务必先肯定做得好的地方。这样可以：

• 表明你看到了优秀的工作
• 提供平衡的反馈
• 维持积极的协作氛围

示例：

### Design Review Summary

The new checkout flow shows excellent attention to user experience. The step indicator
is clear and well-designed, error messages are helpful and actionable, and the overall
layout feels spacious and uncluttered. The loading states with skeleton screens are
particularly well-executed. Great work on the form validation feedback!

However, there are a few accessibility and responsiveness issues to address before merge...

---

报告结构模板

完整模板：加载 assets/review-report-template.md，查看包含所有章节和示例的完整 Markdown 模板。

基本结构：

## Design Review Summary
[2-3 sentences: positive acknowledgment + overall assessment]
**Review scope:** [PR #, pages, components]
**Viewports tested:** Desktop (1440px), Tablet (768px), Mobile (375px)
**Methodology:** 7-phase comprehensive review

---

### Findings

#### 🚨 Blockers
[Critical issues requiring immediate fix before merge]
- **[Blocker] [Title]**: Problem + Screenshot + Phase

#### ⚠️ High-Priority Issues
[Significant issues to fix before merge]
- **[High] [Title]**: Problem + Screenshot + Phase

#### 📋 Medium-Priority / Suggestions
[Improvements for follow-up PR]
- **[Medium] [Title]**: Problem + Phase

#### ✨ Nitpicks
[Minor aesthetic details - optional]
- **Nit:** [Issue] - [Brief description]

---

### Testing Evidence
**Screenshots:** Desktop (1440px) + Tablet (768px) + Mobile (375px)
**Console output:** [Errors/warnings or "Console clean"]
**Accessibility:** Keyboard nav + Focus states + Color contrast

---

### Next Steps
1. Fix Blockers
2. Address High-Priority issues
3. Consider Medium-Priority items

**Overall assessment:** [Ready to merge after blockers fixed / Needs revisions / Ready to merge!]

---

何时加载参考文件

在处理设计评审的特定方面时，加载参考文件：

accessibility-wcag.md

在以下情况下加载：

• 基于标准：验证生产部署是否符合 WCAG 2.1 AA 标准
• 基于问题：遇到无障碍问题（颜色对比度、键盘导航、语义化 HTML、焦点状态、ARIA 属性）
• 基于测试：使用系统化清单开展全面的无障碍审计
• 基于工具：使用无障碍测试工具（Lighthouse、axe、WAVE、Pa11y）进行自动化测试
• 基于分级：确定无障碍问题的严重程度（WCAG 违规的阻断级/高/中）

browser-tools-reference.md

在以下情况下加载：

• 基于设置：安装或配置 Playwright MCP 或 Chrome DevTools CLI 进行测试
• 基于命令：需要特定的 Playwright 命令（导航、调整视口大小、截图、点击、输入、悬停、获取控制台输出）
• 基于工作流：实施常见测试工作流（在 3 种视口下进行响应式评审、表单交互测试、键盘导航测试）
• 基于选择器：难以使用 CSS 选择器、文本选择器或无障碍选择器定位元素
• 基于故障排查：Playwright MCP 找不到元素、缺少 Chrome 依赖项、截图问题

code-health-patterns.md

在以下情况下加载：

• 基于模式：评估组件复用模式、DRY 原则的遵循情况、提取共享组件
• 基于令牌：检查设计令牌的使用情况（颜色、间距比例、排版比例、边框圆角的一致性）
• 基于一致性：评审模式的一致性（命名约定、文件结构组织、API 模式、状态管理）
• 基于示例：需要对比良好与不良模式的代码示例（内联样式与令牌、重复与组合）
• 基于警示信号：识别代码健康问题（复制粘贴式重复、17px 这类魔法数字、不一致的状态管理、失效的抽象）

design-principles-s-tier.md

在以下情况下加载：

• 基于标准：确保 SaaS 仪表板达到 S 级品质（Stripe、Airbnb、Linear、Vercel 的精致水准）
• 基于系统：评估设计系统基础（调色板结构、排版比例、间距比例、核心 UI 组件）
• 基于模块：评审特定模块（多媒体审核界面、数据表、配置面板、仪表板）
• 基于理念：践行核心设计理念（用户优先、精益求精胜过追求速度、简单胜过复杂、一致性）
• 基于架构：评估 CSS 和样式架构（设计令牌、组件模式、响应式策略）

interaction-patterns.md

在以下情况下加载：

• 基于状态：测试按钮、输入框、链接的交互状态（默认、悬停、激活、焦点、禁用）
• 基于表单：测试表单交互、验证模式、错误状态、成功状态、加载状态
• 基于按钮：评估按钮加载状态、破坏性操作确认模式、主要操作与次要操作
• 基于流程：测试导航流程、用户旅程、多步流程、模态框交互
• 基于动画：评审微交互、动画时长（200-300ms）、感知性能（乐观 UI、骨架屏）
• 基于模态框：测试模态框交互、键盘陷阱、焦点管理、Escape 键行为

responsive-testing.md

加载条件：

• 视口测试：使用 Playwright MCP 在特定视口下测试（桌面端 1440px、平板 768px、移动端 375px）
• 触控测试：验证触控目标尺寸是否达到移动端易用性要求的最小值 44×44px
• 溢出测试：排查移动端横向滚动问题或布局溢出问题
• 移动端测试：确保文本易读（最小字号为 16px）、移动端导航模式和响应式图片
• 断点测试：实现或测试断点策略（常见断点：640px、768px、1024px、1280px）
• 导航测试：测试响应式导航模式（汉堡菜单、折叠导航、移动端抽屉菜单）

visual-polish.md

加载条件：

• 字体排版测试：评估字体层级（H1>H2>H3）、字体大小规范（16/18/24/32/48/64px）、行高（1.5-1.7）和易读性
• 间距测试：检查是否遵循 8 点网格（8/16/24/32/40/48/64px）、间距比例是否一致，以及组件内边距/外边距
• 颜色测试：验证调色板的一致性、语义化颜色的使用（红色=错误，绿色=成功）以及设计令牌的使用（不使用硬编码的十六进制值）
• 对齐测试：检查基于网格的布局、精确对齐（精度为 0.5px）、垂直韵律和视觉平衡
• 层级测试：评估视觉层级技巧（大小对比、字重对比、颜色对比、位置、策略性留白）
• 质量测试：评估图像质量（无像素化）、宽高比是否正确，以及图像是否针对 Web 正确优化
• 组件测试：审查设计系统组件（按钮样式、表单输入样式、卡片组件、统一的边框圆角）

---

已知问题预防

此技能可预防 8 个有记录的设计审查问题：

问题	问题描述	影响	预防措施
#1：缺少无障碍支持	审查只关注视觉外观，忽略键盘导航和屏幕阅读器	违反 WCAG 的内容被发布到生产环境，将残障用户排除在外	第 4 阶段通过键盘测试落实完整的 WCAG 2.1 AA 检查清单
#2：响应式测试不完整	只在桌面端视口下审查，遗漏移动端布局问题	移动端布局损坏，令移动端用户感到沮丧	第 2 阶段要求在 1440px、768px 和 375px 视口下测试
#3：反馈含糊	只说“看起来不对”，没有截图或具体说明	浪费时间、待办事项不明确、令开发者感到沮丧	基于证据的反馈原则要求提供截图
#4：给出规定式解决方案	规定具体实现方式（“将外边距改为 16px”），而非描述 UX 影响	设计与开发产生摩擦，错过更好的解决方案	强制遵循“聚焦问题，而非规定解决方案”原则
#5：没有分级优先级	将所有反馈一视同仁，因细枝末节的问题阻止合并	交付速度变慢，优先级不明确	必须使用分级矩阵（阻断项/高/中/细枝末节）
#6：跳过边界情况	正常流程可用，但错误状态和溢出问题会破坏布局	边界情况下出现生产环境缺陷	第 5 阶段要求进行健壮性测试
#7：忽略控制台错误	视觉设计通过审查，但控制台中存在 JavaScript 错误	运行时故障，用户体验不佳	第 7 阶段要求检查控制台
#8：方法不一致	临时审查会因审查者当时的状态而遗漏关键领域	审查不完整，遗漏问题	7 阶段检查清单确保审查全面且可重复

---

依赖项

必需

浏览器自动化工具（以下任选其一）：

1. Playwright MCP（推荐）

   • 请参阅 playwright-testing skill 了解安装方法
   • 提供：浏览器自动化、截图、视口测试、控制台监控
   • 适用于：交互测试、键盘导航、表单测试

2. Puppeteer CLI

   • 通过 npm install -g puppeteer 安装
   • 提供：截图、性能分析、网络监控
   • 适用于：视觉测试、性能审计

实时预览环境：

• 可访问的测试 URL
• 展示实际实现（而非模型图）

可选

• Git/GitHub：用于 PR 背景信息和差异分析
• 设计系统文档：用于检查是否符合既定模式
• 项目 CLAUDE.md：用于了解项目专属设计指南

安装指南

如果浏览器工具不可用，此 skill 将：

1. 检测缺失的工具
2. 链接到相应的 skill 以供安装（playwright-testing）
3. 提供手动测试的备用指南

---

相关 Skills

• playwright-testing：使用 Playwright 进行 E2E 测试、设置浏览器自动化
• frontend-design：创建高质量的新前端界面（互补 skill）
• tailwind-v4-shadcn：UI 框架实现（待评审的设计可能会用到）

---

官方文档

• WCAG 2.1 指南：https://www.w3.org/WAI/WCAG21/quickref/
• WebAIM 对比度检查器：https://webaim.org/resources/contrastchecker/
• Playwright 文档：https://playwright.dev/
• 包容性设计原则：https://inclusivedesignprinciples.org/
• A11y Project 检查清单：https://www.a11yproject.com/checklist/

---

生产环境验证

此 skill 基于真实的设计评审工作流，应用于：

• 方法论灵感来源：Stripe、Airbnb、Linear（7 阶段系统化方法）
• 测试方法：使用 Playwright/Puppeteer 进行自动化浏览器测试
• 无障碍标准：符合 WCAG 2.1 AA 标准（行业标准）

预计 token 使用效率：

• 不使用 skill：约 25k tokens（反复试错、多次修正）
• 使用 skill：约 8k tokens（引导式方法、系统化流程）
• 节省：约 68%，并覆盖 100% 的检查清单

---

有问题或遇到故障？

1. 查看 references/accessibility-wcag.md，获取完整的 WCAG 检查清单
2. 查看 references/browser-tools-reference.md，了解 Playwright/Chrome DevTools 命令
3. 查看 references/visual-polish.md，了解设计原则
4. 确认已安装浏览器工具（请参阅 playwright-testing skill）
5. 确保预览 URL 已上线且可访问