design-review

此技能会根据设计简报和选定的美学理念，对已构建的内容进行结构化设计评审。

重要 — 视觉截图采集

每次设计评审时，都必须采集正在运行的应用程序截图。仅进行代码评审是不够的——你需要看到用户实际看到的内容。请遵循下方第 3 步中的截图采集流程。这是必需步骤。

示例提示

• “评审我刚刚构建的内容”
• “对着陆页进行设计点评”
• “检查是否符合简报”
• “这是一个截图。你觉得效果如何？” [粘贴截图]
• “发布前做一轮 QA”

流程

1. 阅读简报。 在 .design/<feature-slug>/DESIGN_BRIEF.md 查找当前功能的简报。如果 .design/ 下有多个功能文件夹，请询问用户要评审哪个功能。如果不存在 .design/ 文件夹，则使用项目根目录中的 DESIGN_BRIEF.md。如果这两处都没有，请询问用户预期的设计方向。

2. 检查已构建的代码。 检查所有新建或修改的组件、页面和样式文件。重点检查：

   • 所有新建或修改的组件，以及它们与现有组件的关系
   • 令牌／变量的使用情况：组件是否使用共享令牌，还是将值硬编码？
   • 是否存在应当合并的重复组件
   • 文件命名和组织方式：新文件是否遵循项目约定？
   • 弄清楚实际构建了什么，而非原计划构建什么。

3. 采集正在运行的应用程序截图。

   此步骤为必需步骤。不得跳过。不得仅依赖用户提供的截图。

   截图工具优先级

   按顺序尝试各个选项。使用第一个可用的选项：

   1. Playwright MCP（首选）。 检查是否有 plugin-playwright-playwright MCP 服务可用。如果有，请使用它——它可以精确控制视口尺寸、整页截图和文件命名。
   2. Cursor IDE Browser（第二选择）。 如果 Playwright MCP 不可用，请改用 cursor-ide-browser MCP 服务的 browser_take_screenshot 工具。它具备相同的核心功能。
   3. 询问用户（最后手段）。 如果这两个 MCP 服务和应用内浏览器都不可用，则必须请用户手动提供截图。请明确说明所需内容：
      • “我无法使用浏览器工具。要完成视觉评审，我需要正在运行的应用程序截图。请提供：”
      • 一张桌面端宽度（1280px）的整页截图
      • 一张平板端宽度（768px）的整页截图
      • 一张移动端宽度（375px）的整页截图
      • 暗色模式的截图（如适用）
      • 你希望评审的任何特定组件或交互状态
      • 请用户直接在聊天中粘贴／附加图片，或自行将图片保存到 screenshots/ 文件夹中。
      • 不得跳过视觉评审。 在继续检查清单之前，等待用户提供截图。

   截图保存位置

   所有截图都必须保存到功能对应 .design/ 目录下的 screenshots/ 子文件夹中——也就是保存 DESIGN_BRIEF.md 和其他设计流程文件的同一目录。

   路径格式：.design/<feature-slug>/screenshots/

   如果简报位于 .design/onboarding-flow/DESIGN_BRIEF.md，截图应保存到 .design/onboarding-flow/screenshots/。如果文件夹不存在，请创建它。

   如果不存在 .design/ 文件夹（旧项目或独立评审），则使用项目根目录下的 screenshots/ 文件夹。

   使用能说明截图内容的描述性文件名：

   .design/
   └── onboarding-flow/
       ├── DESIGN_BRIEF.md
       ├── DESIGN_REVIEW.md
       └── screenshots/
           ├── review-homepage-desktop-1280.png
           ├── review-homepage-tablet-768.png
           ├── review-homepage-mobile-375.png
           ├── review-homepage-dark-mode-desktop-1280.png
           └── review-card-component-hover.png
   

   截图采集流程

   a. 打开应用程序。 如果项目中无法判断应用程序的 URL（例如 http://localhost:3000），请向用户询问。使用 browser_navigate 打开该 URL。

   b. 采集不同响应式断点的截图。 对每个关键页面／视图，至少采集以下三个视口的截图：

   断点	宽度 × 高度	文件名后缀
   移动端	375 × 812	-mobile-375
   平板	768 × 1024	-tablet-768
   桌面端	1280 × 800	-desktop-1280

   每次截图前，使用 browser_resize 设置视口。使用 browser_take_screenshot 并设置 fullPage: true，以捕获整个可滚动页面；保存时，将 filename 参数指向 screenshots/ 文件夹。

   Playwright MCP 示例流程（假设功能标识为 onboarding-flow）：

   1. browser_navigate → { url: "http://localhost:3000" }
   2. browser_resize   → { width: 1280, height: 800 }
   3. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-desktop-1280.png", fullPage: true }
   4. browser_resize   → { width: 768, height: 1024 }
   5. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-tablet-768.png", fullPage: true }
   6. browser_resize   → { width: 375, height: 812 }
   7. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-mobile-375.png", fullPage: true }
   

   c. 捕获交互状态（适用时）。

   • 按钮、卡片和链接的悬停状态
   • 表单字段的聚焦状态
   • 下拉菜单、模态框和菜单的打开状态
   • 表单的错误／成功状态
   • 加载和空状态

   d. 捕获深色模式（如果项目支持）。 切换至深色模式，并重复捕获各响应式断点；文件名中添加 -dark-mode。

   e. 捕获特定组件。 如果评审聚焦于某个特定组件，请使用 element 和 ref 参数，仅截取该元素。

   分析每张截图

   截图完成后，根据设计简介对每张截图进行视觉分析。对于每张截图：

   • 对照设计简介中的美学方向
   • 检查视觉层级：最重要的元素是否最醒目？
   • 检查间距一致性：边距和内边距是否均匀且有设计意图？
   • 检查颜色：配色是否符合设计简介中的方向？
   • 检查排版：字体大小、字重和间距在视觉上是否恰当？
   • 检查响应式适配：布局是否进行了合理重组，而不只是缩小？
   • 记录仅靠代码评审无法发现的渲染问题（字体加载失败、图片损坏、布局溢出、z-index 问题、border-radius 不正确、颜色不匹配）

   在评审结果中通过文件名引用具体截图，确保问题可追溯。

4. 执行以下评审清单。 针对每个类别，记录哪些方面符合要求，哪些需要改进。务必具体，并引用确切的组件、文件、行号和截图文件名。

5. 生成按优先级排列的改进清单。 按严重程度对问题分组：

   • 必须修复：功能损坏、无障碍访问问题、与设计简介严重不符。
   • 应该修复：不一致、缺少状态、响应式问题。
   • 可以改进：润色、动画优化、排版微调。

6. 将评审结果保存为功能对应的 .design/<feature-slug>/ 文件夹中的 DESIGN_REVIEW.md（与 DESIGN_BRIEF.md 放在一起）。如果不存在 .design/ 文件夹，则保存到项目根目录。添加“已截取的屏幕截图”部分，列出所有截图及其路径。如果用户有此偏好，也请直接呈现评审结果。

评审清单

视觉层级

• 每个页面／视图中最重要的内容是否最醒目？
• 字体比例是否清晰地体现不同重要级别（标题、副标题、正文、说明文字）？
• 交互元素（按钮、链接、输入框）是否足够醒目，无需费力寻找？
• 阅读顺序是否清晰？能否看出视线的移动顺序？

一致性

• 间距值是否一致？请对照既定的间距体系检查内边距和外边距（基于 4px／8px，或项目采用的其他基准）。
• 颜色使用是否一致？请检查相同的语义是否始终对应相同的颜色（主要操作、错误、成功、禁用状态）。
• 边框圆角、阴影值和字体大小是否复用共享样式集，还是存在一次性取值？
• 类似组件的外观和行为是否相似？（例如，所有卡片、所有表单字段，以及同一类别中的所有按钮。）

美学契合度

• 实现是否符合需求说明中指定的设计理念？
• 用户能否一眼看出预期的美学方向？
• 是否有破坏整体美感的元素（例如，在风格鲜明的界面中出现通用组件、字体冲突或颜色不协调）？
• 细节程度是否符合设计理念？（极简设计不应有多余装饰；极繁设计不应有空荡、未完成的区域。）

组件质量

• 代码库中的现有组件是否得到正确使用，还是被重新实现了？
• 新组件是否遵循现有组件的 API 模式（属性、命名、文件组织）？
• 是否存在应合并的重复组件？

状态与交互

• 交互元素是否具备所有必要状态：默认、悬停、焦点、激活、禁用？
• 表单字段是否具备以下状态：空、已填写、错误、成功、禁用？
• 是否处理了加载状态和空状态？
• 过渡和动画是否符合设计理念的动态效果规范？
• 是否为每项用户操作提供了视觉反馈？

响应式行为

• 布局在移动端（375px）、平板（768px）和桌面端（1280px 及以上）是否正常？
• 组件是否能够恰当适配？（不仅仅是缩小，必要时还应重新布局。）
• 移动端的触控目标尺寸是否足够（至少为 44x44px）？
• 文本在所有断点下是否都易于阅读？是否存在过小的文字或过长的行（最长 65–75 个字符）？

无障碍访问

• 颜色对比度：文字与背景的组合是否符合 WCAG AA（正文文本为 4.5:1，大号文本为 3:1）？
• 键盘导航：是否可以仅使用键盘访问并激活每个交互元素？
• 焦点指示器：焦点环是否清晰可见且样式一致？
• 语义化 HTML：标题顺序是否正确？是否使用了地标元素（main、nav、header、footer）？表单标签是否已关联？
• 屏幕阅读器：图片是否有替代文本？图标是否有标签？装饰元素是否已对辅助技术隐藏？
• 动态效果：是否为需要减少动态效果的用户提供了媒体查询？

排版

• 字体是否已成功加载？（检查是否出现 FOIT/FOUT 闪烁。）
• 行长是否便于阅读（正文文本为 45–75 个字符）？
• 行高是否合适（正文为 1.4–1.6，标题应更紧凑）？
• 字号比例是否经过规划，还是随意设定的？

深色模式

• 如果项目定义了深色模式令牌，是否正确应用？
• 所有颜色值是否都使用 CSS 变量（而不是无法随模式切换的硬编码十六进制值）？
• 深色调色板是否符合所选设计理念，还是只是简单反转？
• 阴影是否针对深色模式进行了调整（更暗、更透明）？
• 强调色与深色背景之间是否保持足够的对比度？
• 是否有可用的切换机制或 prefers-color-scheme 支持？

移动端优先

• 布局是否采用移动端优先的方式构建（使用 min-width 媒体查询，而不是 max-width）？
• 移动端布局在 375px 宽度下是否无需水平滚动即可正常使用？
• 导航是否针对移动端进行了适配（而不是直接使用会溢出的桌面端导航）？
• 触控目标是否至少为 44x44px？
• 移动端正文文本是否至少为 16px？

输出格式

# Design Review: [Feature/Page Name]

Reviewed against: DESIGN_BRIEF.md
Philosophy: [named philosophy]
Date: [date]

## Screenshots Captured

| Screenshot                                   | Breakpoint         | Description     |
| -------------------------------------------- | ------------------ | --------------- |
| `screenshots/review-[page]-desktop-1280.png` | Desktop (1280×800) | [what it shows] |
| `screenshots/review-[page]-tablet-768.png`   | Tablet (768×1024)  | [what it shows] |
| `screenshots/review-[page]-mobile-375.png`   | Mobile (375×812)   | [what it shows] |

> All screenshots are in `.design/<feature-slug>/screenshots/`.

## Summary

[2-3 sentences on overall quality and the biggest finding.]

## Must Fix

1. **[Issue]**: [Specific description with file/component reference]. See [`screenshots/[relevant-screenshot].png`]. _Fix: [concrete suggestion]._

## Should Fix

1. **[Issue]**: [Description]. See [`screenshots/[relevant-screenshot].png`]. _Fix: [suggestion]._

## Could Improve

1. **[Issue]**: [Description]. _Suggestion: [idea]._

## What Works Well

[Note the strongest aspects of the implementation. This is not padding. Designers need to know what to keep doing.]