a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
172 lines
7.5 KiB
Markdown
172 lines
7.5 KiB
Markdown
---
|
||
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`
|