name: design-review description: 包含可访问性（WCAG 2.1 AA）、响应式测试和视觉抛光的7阶段前端设计评审。适用于PR评审、UI审计，或遇到对比度问题、布局断裂、可访问性违规、间距不一致、缺失焦点状态等情况。

关键词：设计评审、UI审计、前端评审、可访问性审计、WCAG合规、响应式设计、视觉QA、UX评审、组件评审、PR设计检查、布局问题、可访问性违规、对比度问题、响应式断裂、交互错误、键盘导航、焦点状态、设计系统合规、视觉一致性、用户体验 license: MIT allowed-tools:

Read
Grep
Glob
Bash

设计评审技能

状态: 生产就绪 ✅ 最后更新: 2025-11-20 依赖: Playwright MCP 或 Chrome DevTools 方法论: 7阶段系统评审（灵感来源于 Stripe、Airbnb、Linear）

快速开始

1. 前提条件检查

开始设计评审前，验证浏览器自动化工具是否可用：

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

查看 playwright-testing 技能获取 Playwright 设置
提供浏览器自动化、截图、视口测试、控制台监控

选项 B: Chrome DevTools CLI（替代方案用于截图和性能）

查看 chrome-devtools 技能获取 Puppeteer CLI 设置
提供截图捕获、性能分析、网络监控

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

2. 理解评审范围

对于 PR 评审：

# 分析 git diff 以理解范围
git diff --name-only origin/main...HEAD

# 阅读 PR 描述以获取上下文

对于通用 UI 评审： 只需提供预览 URL 和组件/页面描述。

3. 执行7阶段评审

遵循下面的系统检查清单。每个阶段有特定目标和测试流程。

7阶段评审方法论

阶段 0: 准备

目标: 理解上下文并设置测试环境。

步骤:

阅读 PR 描述 或评审请求以理解：
- 变更动机
- 实施范围
- 开发者的测试笔记
- 预期行为
分析代码差异（如果 PR 可用）：
```
git diff origin/main...HEAD
```
识别修改的文件（组件、样式、测试）
设置实时预览环境：
- 使用浏览器工具导航到预览 URL
- 设置初始视口：1440x900（桌面）
- 拍摄基线截图作为参考
评审设计原则（如果项目有自定义指南）：
- 检查项目 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)  # 桌面
mcp__playwright__browser_resize(width: 768, height: 1024)  # 平板
mcp__playwright__browser_resize(width: 375, height: 667)   # 移动
mcp__playwright__browser_take_screenshot(fullPage: true)

分级： [阻塞] 布局断裂 | [高] 水平滚动/重叠 | [中] 次优间距 | [挑剔] 小不一致性

阶段 3: 视觉抛光

目标: 评估美学质量和视觉一致性。

设计原则指南： 在评估字体层级、间距/布局、颜色调色板、对齐/网格、视觉层级、图像质量或 S-Tier 设计标准时，加载 references/visual-polish.md。

快速评估（5个标准）：

布局和间距：网格对齐、8px 尺度、设计标记（无魔法数字如 17px）
字体：清晰的 H1>H2>H3 层级、1.5-1.7 行高、有限字体权重
颜色：设计系统标记、语义使用（红色=错误、绿色=成功）、一致的品牌
图像：高分辨率（无像素化）、正确的宽高比、优化尺寸、替代文本
视觉层级：主要操作突出、眼睛自然流动、战略性空白

分级： [阻塞] 文本难以辨认/图像断裂 | [高] 明显不一致性 | [中] 间距/对齐问题 | [挑剔] 美学偏好

阶段 4: 可访问性（WCAG 2.1 AA）

目标: 确保包容性设计适合所有用户。

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

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

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

关键测试：

通过整个页面 Tab 键导航（验证焦点状态可见、逻辑顺序、无陷阱）
使用 WebAIM 对比度检查器测试（所有文本/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 加载和错误状态

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

测试流程：

# 模拟慢网络
# 检查浏览器 DevTools 网络标签 → 节流

# 强制错误状态
# 测试无效 API 响应或网络失败

常见问题：

无加载指示器（出现冻结）
模糊错误消息（“发生错误”）
失败后无重试机制
内容加载时布局跳跃

分级优先级：

[阻塞] 边缘案例下崩溃或完全失败
[高] 差劲的错误处理或混乱状态
[中] 缺失边缘案例处理或小问题
[挑剔] 加载状态美学或小抛光

阶段 6: 代码健康

目标: 确保可维护、一致的实现。

代码模式指南： 在评估组件重用（DRY 原则）、设计标记使用（颜色、间距、字体）、模式一致性（命名、文件结构、API 模式）或识别红旗（重复、魔法数字、断裂抽象）时，加载 references/code-health-patterns.md。

快速评审（3个标准）：

组件重用：无复制粘贴、提取共享组件、组合优于重复
设计标记：用于颜色/间距/字体的 CSS 变量（无魔法数字如 margin: 17px）、边界半径一致
模式一致性：遵循代码库模式、命名约定匹配、文件结构组织

分级： [高] 引入技术债务/破坏模式 | [中] 错过的重用机会 | [挑剔] 代码风格偏好

阶段 7: 内容和控制台

目标: 验证抛光细节和技术正确性。

7.1 内容评审

检查：

语法和拼写：无拼写或语法错误
清晰度：标签和指令明确
语气一致性：匹配品牌声音（正式/随意）
占位符文本：替换为真实内容（无“Lorem ipsum”）
微文案质量：有帮助的错误消息、按钮标签、工具提示

常见内容问题：

UI 文本中的拼写错误
生产中留下占位符文本
模糊标签（“提交”对比“保存更改”）
不一致术语
无帮助的错误消息（“错误”对比“电子邮件格式无效”）

7.2 控制台检查

测试流程：

# 使用 Playwright MCP
mcp__playwright__browser_console_messages()

# 使用 Chrome DevTools
# 打开 DevTools → 控制台标签

查找：

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

分级优先级：

[阻塞] 控制台错误破坏功能性
[高] 用户面对文本中的语法错误或混乱内容
[中] 控制台警告或小内容问题
[挑剔] 内容抛光、小控制台噪音

沟通原则

1. 问题而非处方

描述问题及其影响，而非解决方案。让开发者决定实现。

❌ 处方式（避免）： “将边距改为 16px”

✅ 问题聚焦（首选）： “间距与相邻元素感觉不一致，创建视觉杂乱，分散了对主要 CTA 的注意力。当前间距打破了设计系统的既定节奏。”

2. 分级矩阵

用清晰优先级分类每个问题：

优先级	标准	所需操作
[阻塞]	关键失败、核心功能断裂、关键可访问性违规	合并前必须修复
[高优先级]	显著 UX 问题、明显设计不一致性、WCAG 违规	合并前应修复
[中优先级]	改进、小不一致性、边缘案例处理	考虑后续 PR
[挑剔]	美学偏好、小抛光、主观意见	可选精修

重要： 所有挑剔以“Nit:”前缀表示低优先级。

3. 基于证据的反馈

始终为视觉问题提供截图。截图应：

清晰显示问题
包括相关上下文（周围元素）
指示查看内容（如需，箭头、高亮）

示例：

### [高优先级] 禁用按钮对比度差

**问题：** 禁用按钮文本对比度不足 (2.1:1)，未达到 WCAG AA 标准 (需 4.5:1)。低视力用户可能无法识别按钮为禁用。

**截图：** [附加显示禁用按钮的截图]

**影响：** 可访问性违规、视觉障碍用户的潜在混淆。

4. 从积极开始

在列出问题前，始终承认工作良好之处。这：

显示您认可良好工作
提供平衡反馈
维护积极协作

示例：

### 设计评审总结

新的结账流程显示出对用户体验的极佳关注。步骤指示器清晰且设计良好，错误消息有帮助且可操作，整体布局感觉宽敞且不杂乱。使用骨架屏幕的加载状态执行得特别好。表单验证反馈做得很好！

然而，合并前有一些可访问性和响应式问题需要解决...

报告结构模板

完整模板： 加载 assets/review-report-template.md 获取包含所有部分和示例的完整 Markdown 模板。

基本结构：

## 设计评审总结
[2-3 句子：积极承认 + 整体评估]
**评审范围：** [PR #、页面、组件]
**测试视口：** 桌面 (1440px)、平板 (768px)、移动 (375px)
**方法论：** 7阶段全面评审

---

### 发现

#### 🚨 阻塞
[需立即修复的关键问题]
- **[阻塞] [标题]：** 问题 + 截图 + 阶段

#### ⚠️ 高优先级问题
[需修复的显著问题]
- **[高] [标题]：** 问题 + 截图 + 阶段

#### 📋 中优先级 / 建议
[后续 PR 的改进]
- **[中] [标题]：** 问题 + 阶段

#### ✨ 挑剔
[小美学细节 - 可选]
- **Nit：** [问题] - [简要描述]

---

### 测试证据
**截图：** 桌面 (1440px) + 平板 (768px) + 移动 (375px)
**控制台输出：** [错误/警告 或 “控制台干净”]
**可访问性：** 键盘导航 + 焦点状态 + 颜色对比度

---

### 下一步
1. 修复阻塞
2. 解决高优先级问题
3. 考虑中优先级项目

**整体评估：** [阻塞修复后可合并 / 需要修订 / 可合并！]

何时加载参考文件

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

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

加载时机：

基于标准： 确保 S-Tier SaaS 仪表板质量（Stripe、Airbnb、Linear、Vercel 级别的抛光）
基于系统： 评估设计系统基础（颜色调色板结构、字体尺度、间距尺度、核心 UI 组件）
基于模块： 评审特定模块（多媒体审核界面、数据表、配置面板、仪表板）
基于哲学： 应用核心设计哲学（用户第一、精益求精而非速度、简单优于复杂、一致性）
基于架构： 评估 CSS 和样式架构（设计标记、组件模式、响应式策略）

interaction-patterns.md

加载时机：

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

responsive-testing.md

加载时机：

基于视口： 在特定视口（桌面 1440px、平板 768px、移动 375px）使用 Playwright MCP 测试
基于触摸： 验证触摸目标尺寸满足移动可用性的最小 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 精度）、垂直节奏、视觉平衡
基于层级： 评估视觉层级技术（大小对比、权重对比、颜色对比、位置、战略性空白）
基于质量： 评估图像质量（无像素化）、正确的宽高比、适当的图像优化
基于组件： 评审设计系统组件（按钮样式、表单输入样式、卡片组件、一致边界半径）

已知问题预防

此技能预防 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阶段检查清单确保全面、可重复评审

依赖

必需

浏览器自动化工具（以下之一）：

Playwright MCP（推荐）
- 查看 playwright-testing 技能获取安装
- 提供：浏览器自动化、截图、视口测试、控制台监控
- 最佳用于：交互式测试、键盘导航、表单测试
Chrome DevTools CLI
- 查看 chrome-devtools 技能获取安装
- 提供：截图捕获、性能分析、网络监控
- 最佳用于：视觉测试、性能审计

实时预览环境：

可访问测试的 URL
代表实际实现（非模拟）

可选

Git/GitHub：用于 PR 上下文和差异分析
设计系统文档：用于一致性检查对已建立模式
项目 CLAUDE.md：用于项目特定设计指南

安装指导

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

检测缺失工具
链接到适当的技能以进行安装（playwright-testing 或 chrome-devtools）
提供手动测试的后备指导

官方文档

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

生产验证

此技能基于真实设计评审工作流，用于：

方法论灵感：Stripe、Airbnb、Linear（7阶段系统方法）
测试方法：使用 Playwright/Puppeteer 的自动化浏览器测试
可访问性标准：WCAG 2.1 AA 合规性（行业标准）

估计令牌效率：

无技能：约 25k 令牌（试错、重复修正）
有技能：约 8k 令牌（引导方法、系统方法）
节省：约 68% 并提供 100% 检查清单覆盖

有问题或问题？

检查 references/accessibility-wcag.md 获取完整 WCAG 检查清单
参见 references/browser-tools-reference.md 获取 Playwright/Chrome DevTools 命令
评审 references/visual-polish.md 获取设计原则
验证浏览器工具已安装（参见 playwright-testing 或 chrome-devtools 技能）
确保预览 URL 在线并可访问

设计评审技能

快速开始

1. 前提条件检查

2. 理解评审范围

3. 执行7阶段评审

7阶段评审方法论

阶段 0: 准备

阶段 1: 交互和用户流程

阶段 2: 响应式测试

阶段 3: 视觉抛光

阶段 4: 可访问性（WCAG 2.1 AA）

阶段 5: 健壮性测试

5.1 表单验证

5.2 内容溢出

5.3 加载和错误状态

阶段 6: 代码健康

阶段 7: 内容和控制台

7.1 内容评审

7.2 控制台检查

沟通原则

1. 问题而非处方

2. 分级矩阵

3. 基于证据的反馈

4. 从积极开始

报告结构模板

何时加载参考文件

accessibility-wcag.md

browser-tools-reference.md

code-health-patterns.md

design-principles-s-tier.md

interaction-patterns.md

responsive-testing.md

visual-polish.md

已知问题预防

依赖

必需

可选

安装指导

相关技能

官方文档

生产验证