Back to Details

design-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Review Skill

设计评审技能

Status: Production Ready ✅ Last Updated: 2025-11-20 Dependencies: Playwright MCP or Chrome DevTools Methodology: 7-phase systematic review (inspired by Stripe, Airbnb, Linear)
状态: 可投入生产使用 ✅ 最后更新: 2025-11-20 依赖项: Playwright MCP 或 Chrome DevTools 方法论: 7阶段系统化评审（灵感来自Stripe、Airbnb、Linear）

Quick Start

快速开始

1. Prerequisites Check

1. 前置条件检查

Before starting a design review, verify browser automation tools are available:
Option A: Playwright MCP (recommended for interactive testing)
  • See the 
    playwright-testing
    skill for Playwright setup
  • Provides browser automation, screenshots, viewport testing, console monitoring
Option B: Chrome DevTools CLI (alternative for screenshots and performance)
  • See the 
    chrome-devtools
    skill for Puppeteer CLI setup
  • Provides screenshot capture, performance analysis, network monitoring
For complete browser tools reference, see references/browser-tools-reference.md.
开始设计评审前，请确认浏览器自动化工具已就绪：
选项A: Playwright MCP（推荐用于交互式测试）
  • 查看 
    playwright-testing
    技能了解Playwright设置方法
  • 提供浏览器自动化、截图、视口测试、控制台监控功能
选项B: Chrome DevTools CLI（截图和性能分析的替代方案）
  • 查看 
    chrome-devtools
    技能了解Puppeteer CLI设置方法
  • 提供截图捕获、性能分析、网络监控功能
完整的浏览器工具参考，请查看 references/browser-tools-reference.md。

2. Understand the Review Scope

2. 明确评审范围

For PR reviews:
bash
undefined
针对PR评审：
bash
undefined

Analyze git diff to understand scope

分析git diff以了解范围

git diff --name-only origin/main...HEAD
git diff --name-only origin/main...HEAD

Read PR description for context

阅读PR描述获取上下文


**For general UI reviews:**
Simply provide the preview URL and component/page description.

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

3. Execute 7-Phase Review

3. 执行7阶段评审

Follow the systematic checklist below. Each phase has specific objectives and testing procedures.
遵循以下系统化检查清单。每个阶段都有特定目标和测试流程。

The 7-Phase Review Methodology

7阶段评审方法论

Phase 0: Preparation

阶段0：准备工作

Objective: Understand context and set up testing environment.
Steps:
  1. Read PR description or review request to understand:
    • Motivation for changes
    • Scope of implementation
    • Testing notes from developer
    • Expected behavior
  2. Analyze code diff (if PR available):
    bash
    git diff origin/main...HEAD
    Identify modified files (components, styles, tests)
  3. Set up live preview environment:
    • Navigate to preview URL using browser tools
    • Set initial viewport: 1440x900 (desktop)
    • Take baseline screenshot for reference
  4. Review design principles (if project has custom guidelines):
    • Check project CLAUDE.md for design standards
    • Review component library documentation
    • Note design system tokens and patterns
When to skip: For quick component reviews without git context.
目标: 了解上下文并搭建测试环境。
步骤: 1. 阅读PR描述或评审请求，明确：
  • 变更动机
  • 实现范围
  • 开发者提供的测试说明
  • 预期行为
  1. 分析代码差异（若PR可用）：
    bash
    git diff origin/main...HEAD
    识别修改的文件（组件、样式、测试用例）
  2. 搭建实时预览环境：
    • 使用浏览器工具访问预览URL
    • 设置初始视口：1440x900（桌面端）
    • 截取基准截图用于参考
  3. 评审设计原则（若项目有自定义规范）：
    • 查看项目CLAUDE.md了解设计标准
    • 评审组件库文档
    • 记录设计系统的标记和模式
可跳过场景: 无git上下文的快速组件评审。

Phase 1: Interaction & User Flow

阶段1：交互与用户流程

Objective: Verify the interactive experience works as expected.
For complete interaction guide: Load 
references/interaction-patterns.md
when testing interactive states, forms, buttons, navigation flows, micro-interactions, modals, or keyboard navigation.
Quick checklist:
  • Test 5 interactive states (default, hover, active, focus, disabled) for all elements
  • Execute primary user flow (form submission, navigation, key actions)
  • Verify destructive actions have confirmation dialogs
  • Assess perceived performance (loading states, optimistic UI)
Triage: [Blocker] Critical flow broken | [High] Poor UX/missing focus states | [Medium] Missing polish | [Nitpick] Minor timing issues
目标: 验证交互式体验符合预期。
完整交互指南: 测试交互状态、表单、按钮、导航流程、微交互、模态框或键盘导航时，加载 
references/interaction-patterns.md
。
快速检查清单: - 测试所有元素的5种交互状态（默认、悬停、激活、聚焦、禁用）
  • 执行主要用户流程（表单提交、导航、关键操作）
  • 验证破坏性操作带有确认对话框
  • 评估感知性能（加载状态、乐观UI）
优先级划分: [阻塞] 核心流程崩溃 | [高] 糟糕的用户体验/缺失焦点状态 | [中] 缺失细节优化 | [细微问题] 轻微时序问题

Phase 2: Responsiveness Testing

阶段2：响应式测试

Objective: Ensure design works across all viewport sizes.
For complete responsive guide: Load 
references/responsive-testing.md
when testing viewports, touch targets, mobile navigation, image responsiveness, or debugging horizontal scrolling.
Test 3 viewports:
  • Desktop (1440px): Optimal layout, full feature set
  • Tablet (768px): Graceful adaptation, 44×44px touch targets, collapsing nav
  • Mobile (375px): No horizontal scroll, 16px min text, mobile-friendly navigation
Quick testing:
bash
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)
Triage: [Blocker] Layout broken | [High] Horizontal scroll/overlapping | [Medium] Suboptimal spacing | [Nitpick] Minor inconsistencies
目标: 确保设计适配所有视口尺寸。
完整响应式指南: 测试视口、触摸目标、移动端导航、图片响应性或调试横向滚动问题时，加载 
references/responsive-testing.md
。
测试3种视口: - 桌面端（1440px）: 最优布局、完整功能集
  • 平板端（768px）: 流畅适配、44×44px触摸目标、折叠导航
  • 移动端（375px）: 无横向滚动、最小16px文本、移动端友好导航
快速测试代码: ```bash 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)

**优先级划分**: [阻塞] 布局崩溃 | [高] 横向滚动/元素重叠 | [中] 间距布局不合理 | [细微问题] 轻微不一致

---

Phase 3: Visual Polish

阶段3：视觉优化

Objective: Assess aesthetic quality and visual consistency.
For design principles guide: Load 
references/visual-polish.md
when evaluating typography hierarchy, spacing/layout, color palette, alignment/grid, visual hierarchy, image quality, or S-Tier design standards.
Quick evaluation (5 criteria):
  1. Layout & spacing: Grid alignment, 8px scale, design tokens (no magic numbers like 17px)
  2. Typography: Clear H1>H2>H3 hierarchy, 1.5-1.7 line height, limited font weights
  3. Color: Design system tokens, semantic usage (red=error, green=success), consistent brand
  4. Images: High-res (no pixelation), correct aspect ratios, optimized sizes, alt text
  5. Visual hierarchy: Primary actions stand out, eye flows naturally, strategic whitespace
Triage: [Blocker] Illegible text/broken images | [High] Obvious inconsistencies | [Medium] Spacing/alignment issues | [Nitpick] Aesthetic preferences
目标: 评估美学质量和视觉一致性。
设计原则指南: 评估排版层级、间距/布局、调色板、对齐/网格、视觉层级、图片质量或S级设计标准时，加载 
references/visual-polish.md
。
快速评估（5项标准）: 1. 布局与间距: 网格对齐、8px尺度、设计标记（无17px这类魔法数值） 2. 排版: 清晰的H1>H2>H3层级、1.5-1.7行高、有限的字体权重 3. 颜色: 设计系统标记、语义化使用（红色=错误，绿色=成功）、一致的品牌风格 4. 图片: 高分辨率（无像素化）、正确宽高比、优化尺寸、替代文本 5. 视觉层级: 主要操作突出显示、视觉流自然、合理留白
优先级划分: [阻塞] 文本无法辨认/图片损坏 | [高] 明显的不一致 | [中] 间距/对齐问题 | [细微问题] 审美偏好差异

Phase 4: Accessibility (WCAG 2.1 AA)

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

Objective: Ensure inclusive design for all users.
For complete WCAG 2.1 AA checklist: Load 
references/accessibility-wcag.md
when verifying WCAG compliance, testing keyboard navigation, checking color contrast, auditing semantic HTML, or using accessibility testing tools (Lighthouse, axe, WAVE).
Quick WCAG tests (4 principles):
  1. Perceivable: Alt text on images, color contrast (4.5:1 text, 3:1 UI components), semantic HTML
  2. Operable: Keyboard navigation (Tab order logical, visible focus on ALL interactive elements, Enter/Space activation, Escape closes modals, no keyboard traps)
  3. Understandable: Clear labels, helpful error messages, consistent navigation/terminology
  4. Robust: Valid HTML, proper ARIA attributes (roles, states, properties)
Critical tests:
  • Tab through entire page (verify focus states visible, logical order, no traps)
  • Test with WebAIM Contrast Checker (all text/UI ≥4.5:1 or 3:1)
  • Verify form labels associated with inputs (
    <label for="id">
    or 
    aria-label
    )
  • Check semantic HTML (h1→h2→h3 no skipping, 
    <button>
    not 
    <div onClick>
    )
Triage: [Blocker] No keyboard access to core features | [High] WCAG AA violations | [Medium] Semantic HTML issues | [Nitpick] Enhanced accessibility
目标: 确保设计对所有用户具有包容性。
完整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对比度检查器（所有文本/UI ≥4.5:1或3:1）
  • 验证表单标签与输入框关联（
    <label for="id">
    或 
    aria-label
    ）
  • 检查语义化HTML（h1→h2→h3无跳跃，使用
    <button>
    而非
    <div onClick>
    ）
优先级划分: [阻塞] 核心功能无键盘访问权限 | [高] 违反WCAG AA标准 | [中] 语义化HTML问题 | [细微问题] 增强型可访问性优化

Phase 5: Robustness Testing

阶段5：健壮性测试

Objective: Verify handling of edge cases and error conditions.
Test scenarios:
目标: 验证边缘情况和错误条件的处理能力。
测试场景: #### 5.1 表单验证
  • 提交未填写必填字段的表单
  • 输入无效数据（错误邮箱格式、超出范围的数字）
  • 测试字段级验证（实时反馈）
  • 验证清晰且带有指导的错误提示
  • 测试成功提交流程（确认提示）

5.1 Form Validation

5.2 内容溢出

  • Submit form with empty required fields
  • Enter invalid data (wrong email format, out-of-range numbers)
  • Test field-level validation (real-time feedback)
  • Verify clear error messages with guidance
  • Test successful submission flow (confirmation message)
  • 长文本字符串: 超长名称、邮箱、标题
  • 大量条目: 大型列表、数百行的表格
  • 深度嵌套内容: 带有大量回复的评论
  • 空状态: 无数据可显示（展示有用提示）
常见溢出问题: - 文本破坏布局（溢出容器）
  • 截断无省略号或提示框
  • 大型列表的性能问题
  • 缺失空状态设计

5.2 Content Overflow

5.3 加载与错误状态

  • Long text strings: Very long names, emails, titles
  • Many items: Large lists, tables with hundreds of rows
  • Deeply nested content: Comments with many replies
  • Empty states: No data to display (show helpful message)
Common overflow issues:
  • Text breaking layout (overflowing containers)
  • Truncation without ellipsis or tooltip
  • Performance issues with large lists
  • Missing empty state designs
  • 加载状态: 骨架屏、加载动画、进度指示器
  • 错误提示: 清晰、可操作的错误描述
  • 重试机制: 允许用户重试失败操作
  • 超时处理: 优雅处理缓慢/失败请求
  • 乐观更新: 即时反馈，失败时回滚
测试流程: ```bash

5.3 Loading & Error States

模拟慢速网络

—

查看浏览器DevTools网络标签 → 节流设置

—

强制触发错误状态

—

使用无效API响应或网络故障进行测试

  • Loading states: Skeleton screens, spinners, progress indicators
  • Error messages: Clear, actionable error descriptions
  • Retry mechanisms: Allow user to retry failed operations
  • Timeout handling: Graceful handling of slow/failed requests
  • Optimistic updates: Immediate feedback, rollback on failure
Test procedure:
bash
undefined

**常见问题**: - 无加载指示器（页面看似冻结）
- 模糊的错误提示（"发生错误"）
- 故障后无重试机制
- 内容加载时布局跳动

**优先级划分**: - **[阻塞]** 边缘情况下崩溃或完全失效
- **[高]** 错误处理不佳或状态混淆
- **[中]** 缺失边缘情况处理或轻微问题
- **[细微问题]** 加载状态美学或细节优化

---

Simulate slow network

阶段6：代码健康度

Check browser DevTools Network tab → throttling

—

Force error states

—

Test with invalid API responses or network failures

—

**Common problems:**
- No loading indicators (appears frozen)
- Vague error messages ("Error occurred")
- No retry mechanism after failures
- Layout jumps when content loads

**Triage priorities:**
- **[Blocker]** Crashes or complete failures under edge cases
- **[High]** Poor error handling or confusing states
- **[Medium]** Missing edge case handling or minor issues
- **[Nitpick]** Loading state aesthetics or minor polish

---
目标: 确保实现可维护、一致。
代码模式指南: 评估组件复用（DRY原则）、设计标记使用（颜色、间距、排版）、模式一致性（命名、文件结构、API模式）或识别风险信号（重复代码、魔法数值、损坏的抽象）时，加载 
references/code-health-patterns.md
。
快速评审（3项标准）: 1. 组件复用: 无复制粘贴、提取共享组件、组合优于重复 2. 设计标记: 使用CSS变量定义颜色/间距/排版（无
margin: 17px
这类魔法数值）、圆角一致 3. 模式一致性: 遵循代码库模式、命名规范匹配、文件结构清晰
优先级划分: [高] 引入技术债务/破坏现有模式 | [中] 错失复用机会 | [细微问题] 代码风格偏好

Phase 6: Code Health

阶段7：内容与控制台

Objective: Ensure maintainable, consistent implementation.
For code patterns guide: Load 
references/code-health-patterns.md
when evaluating component reuse (DRY principle), design token usage (colors, spacing, typography), pattern consistency (naming, file structure, API patterns), or identifying red flags (duplication, magic numbers, broken abstractions).
Quick review (3 criteria):
  1. Component reuse: No copy-paste, shared components extracted, composition over duplication
  2. Design tokens: CSS variables for colors/spacing/typography (no magic numbers like 
    margin: 17px
    ), border radii consistent
  3. Pattern consistency: Follows codebase patterns, naming conventions match, file structure organized
Triage: [High] Introduces tech debt/breaks patterns | [Medium] Missed reuse opportunities | [Nitpick] Code style preferences
目标: 验证细节完善度和技术正确性。

Phase 7: Content & Console

7.1 内容评审

Objective: Verify polished details and technical correctness.
检查项: - 语法与拼写: 无错别字或语法错误
  • 清晰度: 标签和说明无歧义
  • 语气一致性: 匹配品牌语调（正式/随意）
  • 占位文本: 替换为真实内容（无"Lorem ipsum"）
  • 微文案质量: 有用的错误提示、按钮标签、工具提示
常见内容问题: - UI文本中的错别字
  • 生产环境中遗留占位文本
  • 模糊的标签（"提交" vs "保存更改"）
  • 术语不一致
  • 无用的错误提示（"错误" vs "邮箱格式无效"）

7.1 Content Review

7.2 控制台检查

Check for:
  • Grammar and spelling: No typos or grammatical errors
  • Clarity: Labels and instructions are unambiguous
  • Tone consistency: Matches brand voice (formal/casual)
  • Placeholder text: Replaced with real content (no "Lorem ipsum")
  • Microcopy quality: Helpful error messages, button labels, tooltips
Common content issues:
  • Typos in UI text
  • Placeholder text left in production
  • Vague labels ("Submit" vs "Save Changes")
  • Inconsistent terminology
  • Unhelpful error messages ("Error" vs "Email format invalid")
测试流程: ```bash

7.2 Console Check

使用Playwright MCP

Test procedure:
bash
undefined
mcp__playwright__browser_console_messages()

Using Playwright MCP

使用Chrome DevTools

—

打开DevTools → 控制台标签

mcp__playwright__browser_console_messages()

**检查内容**: - **JavaScript错误**: 未捕获异常、空引用
- **React警告**: Key属性警告、生命周期问题
- **网络故障**: API请求失败、404错误
- **弃用警告**: 旧API使用警告
- **性能警告**: 缓慢渲染、内存泄漏

**优先级划分**: - **[阻塞]** 控制台错误破坏功能
- **[高]** 用户可见文本中的语法错误或内容混淆
- **[中]** 控制台警告或轻微内容问题
- **[细微问题]** 内容优化、轻微控制台冗余信息

---

Using Chrome DevTools

沟通原则

Open DevTools → Console tab

1. 聚焦问题而非解决方案


**Look for:**
- **JavaScript errors**: Uncaught exceptions, null references
- **React warnings**: Key prop warnings, lifecycle issues
- **Network failures**: Failed API requests, 404s
- **Deprecation warnings**: Old API usage warnings
- **Performance warnings**: Slow renders, memory leaks

**Triage priorities:**
- **[Blocker]** Console errors breaking functionality
- **[High]** Grammar errors or confusing content in user-facing text
- **[Medium]** Console warnings or minor content issues
- **[Nitpick]** Content polish, minor console noise

---
描述问题及其影响，而非直接给出解决方案。让开发者决定实现方式。
❌ 不推荐（指令式）: "将边距改为16px"
✅ 推荐（问题导向）: "该间距与相邻元素不一致，造成视觉混乱，分散了用户对主要CTA的注意力。当前间距破坏了设计系统的既定节奏。"

Communication Principles

2. 优先级划分矩阵

1. Problems Over Prescriptions

—
Describe the problem and its impact, not the solution. Let the developer decide implementation.
❌ Prescriptive (avoid): "Change the margin to 16px"
✅ Problem-focused (preferred): "The spacing feels inconsistent with adjacent elements, creating visual clutter that distracts from the primary CTA. The current spacing breaks the established rhythm of the design system."
为每个问题明确分类优先级：
优先级判定标准处理要求
[阻塞]严重故障、核心功能崩溃、严重可访问性违规合并前必须修复
[高优先级]重大用户体验问题、明显设计不一致、违反WCAG标准合并前应修复
[中优先级]优化建议、轻微不一致、边缘情况处理考虑在后续PR中修复
[细微问题]审美偏好、细节优化、主观意见可选优化项
重要提示: 所有细微问题需前缀"Nit:"以标识低优先级。

2. Triage Matrix

3. 基于证据的反馈

Categorize every issue with clear priority:
PriorityCriteriaAction Required
[Blocker]Critical failures, core functionality broken, critical accessibility violationsMust fix before merge
[High-Priority]Significant UX issues, obvious design inconsistencies, WCAG violationsShould fix before merge
[Medium-Priority]Improvements, minor inconsistencies, edge case handlingConsider for follow-up PR
[Nitpick]Aesthetic preferences, minor polish, subjective opinionsOptional refinements
Important: Prefix all nitpicks with "Nit:" to signal low priority.
视觉问题需始终提供截图。截图应：
  • 清晰展示问题
  • 包含相关上下文（周边元素）
  • 标注关注点（必要时使用箭头、高亮）
示例: ```markdown

3. Evidence-Based Feedback

[高优先级] 禁用按钮对比度不足

Always provide screenshots for visual issues. Screenshots should:
  • Show the problem clearly
  • Include relevant context (surrounding elements)
  • Indicate what to look at (arrows, highlights if needed)
Example:
markdown
undefined
问题: 禁用按钮文本对比度不足（2.1:1），未达到WCAG AA标准（要求4.5:1）。低视力用户可能无法识别该按钮为禁用状态。
截图: [附上显示禁用按钮的截图]
影响: 违反可访问性标准，可能给视障用户造成困惑。
undefined

[High-Priority] Poor contrast on disabled button

4. 先肯定优点

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.
undefined
列出问题前，先认可做得好的地方。这能：
  • 体现你认可优质工作
  • 提供平衡的反馈
  • 维持良好的协作氛围
示例: ```markdown

4. Start with Positives

设计评审总结

Always acknowledge what works well before listing issues. This:
  • Shows you recognize good work
  • Provides balanced feedback
  • Maintains positive collaboration
Example:
markdown
undefined
新的结账流程在用户体验上表现出色。步骤指示器清晰且设计精良，错误提示有用且可操作，整体布局宽敞整洁。带骨架屏的加载状态尤其出色。表单验证反馈做得很棒！
不过，合并前还有一些可访问性和响应式问题需要解决...

---

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模板。
核心结构: ```markdown

Report Structure Template

设计评审总结

For complete template: Load 
assets/review-report-template.md
for the full markdown template with all sections and examples.
Essential structure:
markdown
undefined
[2-3句话：肯定优点 + 整体评估] 评审范围: [PR编号、页面、组件] 测试视口: 桌面端（1440px）、平板端（768px）、移动端（375px） 方法论: 7阶段全面评审

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
[后续PR可优化的内容]
  • [中] [标题]: 问题描述 + 所属阶段

📋 Medium-Priority / Suggestions

✨ 细微问题

[Improvements for follow-up PR]
  • [Medium] [Title]: Problem + Phase
[次要美学细节 - 可选]
  • Nit: [问题] - [简要描述]

✨ Nitpicks

测试证据

[Minor aesthetic details - optional]
  • Nit: [Issue] - [Brief description]
截图: 桌面端（1440px）+ 平板端（768px）+ 移动端（375px） 控制台输出: [错误/警告或"控制台无异常"] 可访问性: 键盘导航 + 焦点状态 + 颜色对比度

Testing Evidence

下一步计划

Screenshots: Desktop (1440px) + Tablet (768px) + Mobile (375px) Console output: [Errors/warnings or "Console clean"] Accessibility: Keyboard nav + Focus states + Color contrast
  1. 修复阻塞问题
  2. 处理高优先级问题
  3. 考虑中优先级优化项
整体评估: [修复阻塞问题后可合并 / 需要修订 / 可直接合并!]

---

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!]

---
处理设计评审的特定环节时，加载对应参考文件：

When to Load References

accessibility-wcag.md

Load reference files when working on specific aspects of design review:
加载场景: - 标准合规: 验证生产部署的WCAG 2.1 AA合规性
  • 问题排查: 遇到可访问性违规（颜色对比度、键盘导航、语义化HTML、焦点状态、ARIA属性）
  • 全面审计: 使用系统化检查清单开展完整可访问性审计
  • 工具辅助: 使用可访问性测试工具（Lighthouse、axe、WAVE、Pa11y）进行自动化测试
  • 优先级判定: 确定可访问性问题的严重程度（阻塞/高/中优先级）

accessibility-wcag.md

browser-tools-reference.md

Load when:
  • Standards-based: Verifying WCAG 2.1 AA compliance for production deployment
  • Issue-based: Encountering accessibility violations (color contrast, keyboard navigation, semantic HTML, focus states, ARIA attributes)
  • Testing-based: Conducting comprehensive accessibility audit with systematic checklist
  • Tools-based: Using accessibility testing tools (Lighthouse, axe, WAVE, Pa11y) for automated testing
  • Triage-based: Determining severity of accessibility issues (Blocker/High/Medium for WCAG violations)
加载场景: - 环境搭建: 安装或配置Playwright MCP或Chrome DevTools CLI用于测试
  • 命令查询: 需要特定Playwright命令（导航、调整视口、截图、点击、输入、悬停、获取控制台输出）
  • 流程落地: 实施常见测试流程（跨3种视口的响应式评审、表单交互测试、键盘导航测试）
  • 选择器调试: 遇到CSS选择器、文本选择器或可访问性选择器的元素定位问题
  • 故障排查: Playwright MCP无法找到元素、Chrome依赖缺失、截图捕获问题

browser-tools-reference.md

code-health-patterns.md

Load when:
  • Setup-based: Installing or configuring Playwright MCP or Chrome DevTools CLI for testing
  • Command-based: Need specific Playwright commands (navigate, resize viewport, screenshot, click, type, hover, get console output)
  • Workflow-based: Implementing common testing workflows (responsive review across 3 viewports, form interaction testing, keyboard navigation testing)
  • Selector-based: Struggling with CSS selectors, text selectors, or accessibility selectors for element targeting
  • Troubleshooting-based: Playwright MCP not finding elements, Chrome dependencies missing, screenshot capture issues
加载场景: - 模式评估: 评估组件复用模式、DRY原则合规性、提取共享组件
  • 标记检查: 检查设计标记使用（颜色、间距尺度、排版尺度、圆角一致性）
  • 一致性验证: 评审模式一致性（命名规范、文件结构、API模式、状态管理）
  • 示例参考: 需要对比优劣模式的代码示例（内联样式vs标记、重复vs组合）
  • 风险识别: 发现代码健康问题（复制粘贴重复代码、17px这类魔法数值、不一致的状态管理、损坏的抽象）

code-health-patterns.md

design-principles-s-tier.md

Load when:
  • Pattern-based: Evaluating component reuse patterns, DRY principle compliance, extracting shared components
  • Token-based: Checking design token usage (colors, spacing scale, typography scale, border radii consistency)
  • Consistency-based: Reviewing pattern consistency (naming conventions, file structure organization, API patterns, state management)
  • Example-based: Need code examples comparing good vs bad patterns (inline styles vs tokens, duplication vs composition)
  • Red-flag-based: Identifying code health issues (copy-paste duplication, magic numbers like 
    17px
    , inconsistent state management, broken abstractions)
加载场景: - 标准对齐: 确保达到S级SaaS仪表盘质量（Stripe、Airbnb、Linear、Vercel级别的细节优化）
  • 系统评估: 评估设计系统基础（调色板结构、排版尺度、间距尺度、核心UI组件）
  • 模块评审: 评审特定模块（多媒体审核界面、数据表格、配置面板、仪表盘）
  • 理念落地: 应用核心设计理念（用户优先、精益求精而非追求速度、简洁而非复杂、一致性）
  • 架构评估: 评估CSS与样式架构（设计标记、组件模式、响应式策略）

design-principles-s-tier.md

interaction-patterns.md

Load when:
  • Standards-based: Ensuring S-Tier SaaS dashboard quality (Stripe, Airbnb, Linear, Vercel level polish)
  • System-based: Evaluating design system foundation (color palette structure, typography scale, spacing scale, core UI components)
  • Module-based: Reviewing specific modules (multimedia moderation interfaces, data tables, configuration panels, dashboards)
  • Philosophy-based: Applying core design philosophy (users first, meticulous craft over speed, simplicity over complexity, consistency)
  • Architecture-based: Evaluating CSS & styling architecture (design tokens, component patterns, responsive strategies)
加载场景: - 状态测试: 测试按钮、输入框、链接的交互状态（默认、悬停、激活、聚焦、禁用）
  • 表单测试: 测试表单交互、验证模式、错误状态、成功状态、加载状态
  • 按钮评估: 评估按钮加载状态、破坏性操作确认模式、主次按钮区分
  • 流程测试: 测试导航流程、用户旅程、多步骤流程、模态框交互
  • 动画评审: 评审微交互、动画时长（200-300ms）、感知性能（乐观UI、骨架屏）
  • 模态框测试: 测试模态框交互、键盘陷阱、焦点管理、Escape键行为

interaction-patterns.md

responsive-testing.md

Load when:
  • States-based: Testing interactive states (default, hover, active, focus, disabled) for buttons, inputs, links
  • Form-based: Testing form interactions, validation patterns, error states, success states, loading states
  • Button-based: Evaluating button loading states, destructive action confirmation patterns, primary vs secondary actions
  • Flow-based: Testing navigation flows, user journeys, multi-step processes, modal interactions
  • Animation-based: Reviewing micro-interactions, animation timing (200-300ms), perceived performance (optimistic UI, skeleton screens)
  • Modal-based: Testing modal interactions, keyboard traps, focus management, Escape key behavior
加载场景: - 视口测试: 使用Playwright MCP测试特定视口（桌面端1440px、平板端768px、移动端375px）
  • 触摸验证: 验证触摸目标尺寸满足移动端可用性的最小44×44px要求
  • 溢出调试: 调试移动端横向滚动问题或布局溢出问题
  • 移动端适配: 确保文本可读性（最小16px字体）、移动端导航模式、响应式图片
  • 断点测试: 实施或测试断点策略（常见断点：640px、768px、1024px、1280px）
  • 导航测试: 测试响应式导航模式（汉堡菜单、折叠导航、移动端抽屉菜单）

responsive-testing.md

visual-polish.md

Load when:
  • Viewport-based: Testing at specific viewports (desktop 1440px, tablet 768px, mobile 375px) with Playwright MCP
  • Touch-based: Verifying touch target sizes meet minimum 44×44px requirement for mobile usability
  • Overflow-based: Debugging horizontal scrolling issues or layout overflow problems on mobile
  • Mobile-based: Ensuring text readability (16px minimum font size), mobile navigation patterns, responsive images
  • Breakpoint-based: Implementing or testing breakpoint strategy (common breakpoints: 640px, 768px, 1024px, 1280px)
  • Navigation-based: Testing responsive navigation patterns (hamburger menus, collapsing navigation, mobile drawer menus)
加载场景: - 排版评估: 评估字体层级（H1>H2>H3）、字体尺度标准（16/18/24/32/48/64px）、行高（1.5-1.7）、可读性
  • 间距检查: 验证8点网格合规性（8/16/24/32/40/48/64px）、一致的间距尺度、组件内边距/外边距
  • 颜色验证: 验证调色板一致性、颜色语义化使用（红色=错误，绿色=成功）、设计标记使用（无硬编码十六进制值）
  • 对齐检查: 验证基于网格的布局、精确对齐（0.5px精度）、垂直节奏、视觉平衡
  • 层级评估: 评估视觉层级技巧（尺寸对比、权重对比、颜色对比、位置、合理留白）
  • 质量评估: 评估图片质量（无像素化）、正确宽高比、网页图片优化
  • 组件评审: 评审设计系统组件（按钮样式、表单输入样式、卡片组件、一致的圆角）

visual-polish.md

已知问题预防

Load when:
  • Typography-based: Evaluating font hierarchy (H1>H2>H3), font scale standards (16/18/24/32/48/64px), line height (1.5-1.7), readability
  • Spacing-based: Checking 8-point grid compliance (8/16/24/32/40/48/64px), consistent spacing scale, component padding/margin
  • Color-based: Verifying color palette consistency, semantic color usage (red=error, green=success), design token usage (no hardcoded hex values)
  • Alignment-based: Checking grid-based layout, precise alignment (0.5px precision), vertical rhythm, visual balance
  • Hierarchy-based: Evaluating visual hierarchy techniques (size contrast, weight contrast, color contrast, position, strategic whitespace)
  • Quality-based: Assessing image quality (no pixelation), correct aspect ratios, proper image optimization for web
  • Component-based: Reviewing design system components (button styles, form input styles, card components, consistent border radii)
本技能可预防8种已记录的设计评审问题：
问题编号问题描述影响预防措施
#1: 缺失可访问性检查评审仅关注视觉外观，忽略键盘导航和屏幕阅读器生产环境出现WCAG违规，排斥残障用户阶段4强制执行完整的WCAG 2.1 AA检查清单及键盘测试
#2: 响应式测试不完整仅在桌面端视口评审，遗漏移动端故障移动端布局崩溃，用户体验糟糕阶段2要求在1440px、768px和375px视口进行测试
#3: 反馈模糊仅评论"看起来不对"，无截图或具体说明浪费时间、任务不明确、开发者受挫基于证据的反馈原则要求提供截图
#4: 指令式解决方案直接指定实现方式（"将边距改为16px"）而非描述用户体验影响设计与开发冲突，错失更优方案强制执行"聚焦问题而非解决方案"原则
#5: 无优先级划分所有反馈同等对待，因细微问题阻塞合并交付速度变慢、优先级不明确要求使用优先级划分矩阵（阻塞/高/中/细微问题）
#6: 跳过边缘情况正常流程可用，但错误状态和溢出导致布局崩溃生产环境出现边缘情况Bug阶段5强制要求健壮性测试
#7: 忽略控制台错误视觉设计通过，但控制台存在JavaScript错误运行时故障、用户体验差阶段7要求检查控制台
#8: 方法论不一致临时评审因评审者状态遗漏关键环节评审不完整、遗漏问题7阶段检查清单确保全面、可重复的评审

Known Issues Prevention

依赖项

—

必需

This skill prevents 8 documented design review issues:
IssueProblemImpactPrevention
#1: Missing AccessibilityReviews focus only on visual appearance, ignoring keyboard navigation and screen readersWCAG violations shipped to production, excluding users with disabilitiesPhase 4 enforces complete WCAG 2.1 AA checklist with keyboard testing
#2: Incomplete Responsive TestingReviewing only at desktop viewport, missing mobile breakageBroken mobile layouts, frustrated mobile usersPhase 2 requires testing at 1440px, 768px, and 375px viewports
#3: Vague FeedbackComments like "looks off" without screenshots or specificsWasted time, unclear action items, frustrated developersEvidence-based feedback principle requires screenshots
#4: Prescriptive SolutionsDictating implementation ("change margin to 16px") instead of describing UX impactDesign-dev friction, missed better solutions"Problems Over Prescriptions" principle enforced
#5: No Triage PriorityAll feedback treated equally, blocking merges on nitpicksSlowed delivery, unclear prioritiesTriage matrix (Blocker/High/Medium/Nitpick) required
#6: Skipped Edge CasesHappy path works, but error states and overflow break layoutProduction bugs with edge casesPhase 5 mandates robustness testing
#7: Console Errors IgnoredVisual design passes, but JavaScript errors exist in consoleRuntime failures, poor user experiencePhase 7 requires console check
#8: Inconsistent MethodologyAd-hoc reviews miss critical areas depending on reviewer moodIncomplete reviews, missed issues7-phase checklist ensures comprehensive, repeatable reviews
浏览器自动化工具（二选一）：
  1. Playwright MCP（推荐）
    • 查看 
      playwright-testing
      技能了解安装方法
    • 提供：浏览器自动化、截图、视口测试、控制台监控
    • 最适用于：交互式测试、键盘导航、表单测试
  2. Chrome DevTools CLI
    • 查看 
      chrome-devtools
      技能了解安装方法
    • 提供：截图捕获、性能分析、网络监控
    • 最适用于：视觉测试、性能审计
实时预览环境: - 可访问的测试URL
  • 代表实际实现（而非原型图）

Dependencies

可选

Required

—
Browser automation tools (one of the following):
  1. Playwright MCP (recommended)
    • See 
      playwright-testing
      skill for installation
    • Provides: Browser automation, screenshots, viewport testing, console monitoring
    • Best for: Interactive testing, keyboard navigation, form testing
  2. Chrome DevTools CLI
    • See 
      chrome-devtools
      skill for installation
    • Provides: Screenshot capture, performance analysis, network monitoring
    • Best for: Visual testing, performance audits
Live preview environment:
  • URL accessible for testing
  • Represents actual implementation (not mockups)
  • Git/GitHub: 用于获取PR上下文和差异分析
  • 设计系统文档: 用于对照既定模式检查一致性
  • 项目CLAUDE.md: 用于项目特定设计规范

Optional

安装指引

  • Git/GitHub: For PR context and diff analysis
  • Design system docs: For consistency checks against established patterns
  • Project CLAUDE.md: For project-specific design guidelines
若浏览器工具未就绪，本技能将：1. 检测缺失工具 2. 链接至对应安装技能（
playwright-testing
或 
chrome-devtools
） 3. 提供手动测试的备选指引

Installation Guidance

相关技能

If browser tools are not available, this skill will:
  1. Detect missing tools
  2. Link to appropriate skill for installation (
    playwright-testing
    or 
    chrome-devtools
    )
  3. Provide fallback guidance for manual testing
  • playwright-testing: 使用Playwright进行端到端测试、浏览器自动化设置
  • chrome-devtools: 通过Puppeteer CLI脚本实现浏览器自动化
  • frontend-design: 创建具备设计质量的新前端界面（互补技能）
  • tailwind-v4-shadcn: UI框架实现（待评审设计可能使用该框架）
  • ai-sdk-ui: AI驱动的UI组件（可能是待评审界面的一部分）

Related Skills

官方文档

  • playwright-testing: E2E testing with Playwright, browser automation setup
  • chrome-devtools: Browser automation via Puppeteer CLI scripts
  • frontend-design: Create new frontend interfaces with design quality (complementary skill)
  • tailwind-v4-shadcn: UI framework implementation (designs being reviewed may use this)
  • ai-sdk-ui: AI-powered UI components (may be part of reviewed interfaces)

Official Documentation

生产验证

本技能基于真实设计评审工作流，已在以下场景应用：
  • 方法论灵感: Stripe、Airbnb、Linear（7阶段系统化方法）
  • 测试方法: 使用Playwright/Puppeteer进行自动化浏览器测试
  • 可访问性标准: WCAG 2.1 AA合规性（行业标准）
预估Token效率: - 无技能辅助: ~25k Token（反复试错、多次修正）
  • 使用技能辅助: ~8k Token（引导式方法论、系统化流程）
  • 节省比例: ~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
    或
    chrome-devtools
    技能）
  5. 确保预览URL已上线且可访问

Production Validation

—
This skill is based on real design review workflows used at:
  • Methodology inspiration: Stripe, Airbnb, Linear (7-phase systematic approach)
  • Testing approach: Automated browser testing with Playwright/Puppeteer
  • Accessibility standards: WCAG 2.1 AA compliance (industry standard)
Estimated token efficiency:
  • Without skill: ~25k tokens (trial-and-error, repeated corrections)
  • With skill: ~8k tokens (guided methodology, systematic approach)
  • Savings: ~68% with 100% checklist coverage
Questions or issues?
  1. Check references/accessibility-wcag.md for complete WCAG checklist
  2. See references/browser-tools-reference.md for Playwright/Chrome DevTools commands
  3. Review references/visual-polish.md for design principles
  4. Verify browser tools are installed (see 
    playwright-testing
    or 
    chrome-devtools
    skills)
  5. Ensure preview URL is live and accessible
—