---
name: design-review
description: 对原型和组件进行设计规范一致性审查，识别违规元素并建议将新增设计模式纳入主题。在需要检查设计质量、规范合规性或识别可复用设计模式时使用。
---

# 设计 Review

对项目中的原型和组件进行设计规范一致性审查，产出结构化 Review 报告。

## 角色定位

你将作为 **设计质量审查员 × 主题架构师（复合型）**，协助用户完成设计 Review。

## 核心流程

确定范围与依据 → 执行审查 → 生成报告 → 追加日志

### 步骤 1：确定审查依据

按以下优先级确定设计审查的依据（设计规范）：

1. **用户指定** → 用户明确提供的设计规范文档、主题或 DESIGN.md
2. **项目默认主题** → `AGENTS.md` 中定义的默认主题目录下的设计系统文件

**加载依据文件**：

进入确定的主题目录（如 `src/themes/<theme-key>/`），按以下顺序加载：

1. `DESIGN.md` — 设计规范文档（核心依据，优先级最高）
2. `globals.css` 或 `designToken.json` — 设计令牌定义（二选一，以主题内实际存在的文件为准）
3. `components/` — 主题组件（如有）
4. `templates/` — 页面模板（如有）

> **如果项目无默认主题且用户未指定依据**，则仅执行通用设计质量检查（一致性、可访问性、响应式等），不执行主题合规性检查。

### 步骤 2：确定审查范围

按以下优先级确定审查的原型/组件范围：

1. **用户明确指定** → 用户直接点明了目标原型或目录
   - "Review 一下首页" → 仅审查首页原型
   - "检查所有按钮组件" → 仅审查 `src/components/` 下的按钮相关组件
2. **用户模糊描述** → 用户给出方向但未精确指定
   - "最近改的那些页面帮我检查一下" → 按时间戳扫描最近变更的原型/组件
3. **用户未指定范围（默认）** → 执行增量扫描（见下方默认流程）

**默认增量扫描流程**：

1. **读取上次 Review 时间** → 从 `src/docs/review-log.md` 获取最后一条日志的时间戳
2. **扫描变更文件** → 以该时间戳为基准，检测自上次 Review 以来发生变更的文件
   - 扫描范围：`src/prototypes/`、`src/components/`
   - 使用 `find` 或 `git diff --name-only` 等方式获取变更文件列表
3. **生成待审清单** → 展示待审查的原型/组件列表，等待用户确认

**首次执行**：若 `review-log.md` 不存在或为空，则扫描所有原型和组件。

### 步骤 3：展示待审清单

向用户展示范围检测结果，格式如下：

```text
📋 上次设计 Review：YYYY-MM-DD HH:mm（或「首次 Review」）
🎨 审查依据：<主题名> DESIGN.md

📝 待审查范围：

🔸 原型：
  - xxx-page（新增 / 修改）
  - yyy-page（修改）

🔸 组件：
  - zzz-button（新增）

是否按以上范围执行 Review？
```

等待用户确认后再继续。用户可在此时调整范围。

### 步骤 4：执行审查

用户确认后，逐个审查目标原型/组件，分两个维度产出发现。

> **子代理委托（推荐）**：当待审范围包含 **3 个及以上** 原型/组件时，建议为每个目标分别启动一个子代理（browser_subagent 或等效机制），并行执行审查。每个子代理负责：
> 1. 读取目标原型/组件的全部源码（`.tsx` / `.css` / `.module.css` 等）
> 2. 依据下方规则执行 Part A 检查
> 3. 返回结构化的发现列表（JSON 或 Markdown 表格）
>
> 主流程汇总所有子代理结果后，统一生成 Part B 建议和最终报告。

#### Part A：规范合规性检查

##### 检查依据优先级

每个主题的规范不同，因此 **以步骤 1 加载的 DESIGN.md 中定义的规则为准**，而非下方通用检查表。

具体优先级：

1. **主题 DESIGN.md 中的「禁止做法」/ 「使用约束 · 必须遵守」** → 对应 🔴 Critical
2. **主题 DESIGN.md 中的「建议做法」** → 违反时对应 🟡 Warning
3. **主题 DESIGN.md 中定义的 Design Token**（颜色、间距、圆角、阴影、排版等） → 硬编码偏离时对应 🟡 Warning
4. **主题 DESIGN.md 中定义的组件体系** → 自行重写已有组件对应 🔵 Info
5. **下方通用检查表** → 仅作为 DESIGN.md 未涵盖维度的补充

##### 通用检查表（补充）

> 以下维度仅在主题 DESIGN.md 未对该维度做出明确规定时使用。如 DESIGN.md 已有更具体的要求，以 DESIGN.md 为准。

| 检查维度 | 检查内容 |
|---------|---------|
| **色彩** | 是否使用了设计系统定义的颜色变量；是否存在硬编码颜色值 |
| **字体** | 字体家族、字号、字重是否符合设计系统定义 |
| **间距** | 内外边距是否使用标准间距值 |
| **圆角** | border-radius 是否使用设计系统定义的标准值 |
| **阴影** | box-shadow 是否使用设计系统定义的阴影层级 |
| **组件使用** | 是否复用了主题已提供的组件（Button、Card、Input 等），而非自行重写 |
| **布局** | 是否遵循设计系统的布局模式和栅格规范 |
| **可访问性** | 色彩对比度（WCAG 2.1 AA）、语义化标签、交互元素可达性 |
| **响应式** | 是否遵循设计系统的断点规范 |

##### 严重度分级

- 🔴 **Critical** — 违反主题「禁止做法」或「必须遵守」的强制规则
- 🟡 **Warning** — 偏离「建议做法」或硬编码了 Design Token 已定义的值
- 🔵 **Info** — 优化建议（如可复用已有组件但自行实现了类似组件）

#### Part B：主题扩展建议

识别原型/组件中值得纳入设计系统的新模式：

| 识别维度 | 说明 |
|---------|------|
| **新增设计元素** | 原型中出现的、设计系统尚未定义的颜色、字体、间距等，且有复用价值 |
| **新增组件模式** | 原型中自行实现的 UI 组件，如果有通用性，建议提取到主题 `components/` |
| **重复模板** | 多个原型中出现类似的页面结构/布局模式，建议提取为主题 `templates/` |
| **新增交互模式** | 与现有组件不同的交互模式（如新的表单验证、加载态等） |

### 步骤 5：生成 Review 报告

使用 `/skills/design-review/references/review-report-template.md` 模板，生成结构化报告并直接展示给用户。

报告应包含：
- 审查摘要（范围、依据、统计）
- Part A 规范违规清单（表格）
- Part B 主题扩展建议清单（表格）
- 建议优先级排序

### 步骤 6：追加 Review 日志

审查完成后，在 `src/docs/review-log.md` 追加一条日志记录。

- 日志模板来源：`src/docs/templates/review-log-template.md`
- 若 `review-log.md` 不存在，先基于模板创建
- 日志采用紧凑格式，一行一条
- 当 `review-log.md` 达到或超过 `500` 行时，删除最旧的 `50` 行业务日志，再追加 `trim` 日志记录裁剪动作
- 日志只追加，不改写历史

## 输出文件

- Review 报告：直接在对话中展示（不写入文件）
- Review 日志：`src/docs/review-log.md`（追加）

## 约束

1. **只读审查** — Review 过程不修改任何原型或组件代码，仅产出建议
2. **不修改主题** — Part B 仅提出建议，不自动修改主题文件
3. **用户确认** — 范围和依据必须经用户确认后再执行审查
4. **增量优先** — 默认只审查上次 Review 以来的变更，避免重复审查

## 参考

`rules/design-guide.md` | `rules/theme-guide.md` | `rules/memory-system-guide.md`
