design-review

Files (2)

• SKILL.md
• review-report-template.md · references/

SKILL.md (first lines)

# 设计 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** — 优化建议（如可复用已有组件但自行实现了类似组件）

From liuqiao666/ProtoFlow, Apache-2.0.

More from liuqiao666/ProtoFlow