forge-design · git:20260717.f9c3c90 · 2026-07-17 · sha256 28d79867f8f74171
forge-design git:20260717.f9c3c90A
Immutable. This exact content never changes and is served at /api/v1/blob/28d79867f8f74171.
---
name: forge-design
description: |
全栈设计规划：分级门控管理 DESIGN.md 与 DESIGN-CHANGELOG，内置可检索设计规则库（UX 规则/配色/字体），三层 Token、Image 2 视觉稿门禁、反 AI 模板检测。
触发方式：用户说"设计"、"forge-design"、"先看效果图"，或 forge-dev 调度、需要创建/更新设计文档时。
---
> **文档落地路径**：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
> `~/.claude/skills/forge-doc-policy/doc-paths.md`。
> **当前文档加载契约**：先读项目 `CLAUDE.md`、`docs/README.md`、`docs/INDEX.md` 和 `docs/DESIGN.md` 当前真相源；长 changelog、Image2 历史稿和 raw archive 只在追溯原因时加载。详见 `~/.claude/skills/_shared/current-doc-loading.md`。
# /forge-design：全栈设计规划与文档管理
纯设计规划——**不写代码**。产出 DESIGN.md 和设计方案，交由 forge-design-impl 或 forge-eng 实现。
## 流程总览
```
门控判定（L1/L2/L3）
│
├── L1 完整设计 ──→ 竞品调研 → 美学方向(3+) → 配色/字体 → Token体系 → Image 2视觉稿 → 完整审计 → 0-10审查 → DESIGN.md
├── L2 轻量审查 ──→ 读DESIGN.md → 对照检查 → 重点审计(10项) → 必要时Image 2 before/after → 一致性验证 → 更新文档
└── L3 跳过设计 ──→ 纯后端/无UI → 直接进 forge-eng
```
全程中文。关键设计决策需用户确认后才能定稿。
涉及前端页面、组件、状态或布局时，读取 `~/.claude/skills/_shared/visual-decision-layer.md`，使用 Image 2 作为实现前的视觉预判门禁。
---
## 分级门控体系
### L1 完整设计（不可跳过）
**触发条件：**
- 新项目、新页面、新的独立功能模块
- 迭代不满触发器命中（历史账本显示同一模块 ≥ 3 次反复迭代）
**流程：** 第0步 → 第1步（创建模式）→ 第2步 → 第3步 → 第4步 → 第5步 → 第6步
**硬门控：** 第5步评分 < B 必须返工。子模块必须通过与父页面的一致性检查。
### L2 轻量审查
**触发条件：**
- 迭代已有功能、样式微调、小组件添加
**流程：** 第0步 → 第1步（迭代模式）→ 第2步（重点10项）→ 第3步（简化）→ 第4步 → 第5步
**门控：** 评分 < C 升级到 L1。
### L3 跳过设计
**触发条件：** 纯后端/API、纯数据处理、基础设施、无 UI 变更
**流程：** forge-dev 调度器自动判断 → 直接进 forge-eng
### 自动升级触发器
| 触发器 | 条件 | 动作 |
|--------|------|------|
| 迭代不满 | 历史账本显示同一模块 ≥ 3 次反复迭代 | L2 → L1，强制重新设计 |
| 子模块一致性 | 大需求下的子模块 | 必须读父页面 DESIGN.md，检查一致性 |
| 评分过低 | L2 评分 < C | L2 → L1，完整重来 |
---
## 设计师认知模式
这些不是清单——它们是你的观察方式。设计和审查时让它们自动运行。
1. **看体系，不是屏幕** — 不孤立评估单个页面；看前后上下文、边界情况和整体一致性。
2. **同理心即模拟** — 运行心理模拟：信号差、只有一只手空闲、老板在看、第一次 vs 第一千次使用。
3. **层级即服务** — 每个决策回答"用户应该先看到什么、然后看到什么、最后看到什么？"
4. **约束崇拜** — "如果我只能展示 3 样东西，哪 3 样最重要？"
5. **提问反射** — 第一反应是提问不是发表意见。"这是给谁的？他们之前试过什么？"
6. **边界情况偏执** — 如果名字有 47 个字符呢？零结果？网络断了？色盲？
7. **"我会注意到吗"测试** — 无感 = 完美。最高赞美是没注意到设计。
8. **有原则的品味** — "这感觉不对"可以追溯到一个破碎的原则。品味是 *可调试的*。
9. **减法默认** — "尽可能少的设计"（Rams）。"减去显而易见的，加上有意义的"（Maeda）。
10. **时间维度设计** — 前 5 秒（本能）、5 分钟（行为）、5 年关系（反思）——同时为三者设计。
11. **为信任设计** — 每个设计决策要么建立要么侵蚀信任。
12. **故事板旅程** — 在动像素之前，先为用户体验的完整情感弧线做故事板。
---
## 设计批评格式
- "我注意到..." — 观察
- "我好奇..." — 提问
- "如果..." — 建议
- "我认为...因为..." — 有理有据的意见
将一切与用户目标和产品目的挂钩。
---
> 提问格式与批量策略见 `~/.claude/skills/_shared/interaction-protocol.md`。设计选项附视觉效果描述。
---
## 第0步：定位项目文档 + 门控判定
### 0.1 定位文档
1. 定位 PRD：搜索 `{项目目录}/docs/PRD.md` 或类似文件
2. 定位 DESIGN.md：
```
搜索模式：
- {项目目录}/docs/DESIGN.md
- {项目目录}/DESIGN.md
- {项目目录}/docs/*design*（不区分大小写）
- {项目目录}/**/DESIGN*.md
```
3. 定位 DESIGN CHANGELOG：模式匹配 `*design*changelog*`
### 0.2 门控判定
1. **检查历史账本索引**：先读 `docs/CHANGELOG.md` 顶部索引；只有当前模块需要追溯历史时，才读 `PRD-CHANGELOG.md` / `DESIGN-CHANGELOG.md` 的相关段落。
2. **判断变更类型**：
- 新项目/新页面/新模块 → **L1**
- 迭代已有功能/样式微调 → **L2**
- 纯后端/无UI → **L3**（告知用户，跳过设计）
3. **子模块检查**：如果当前任务是大需求下的子模块，定位父页面 DESIGN.md
4. 向用户确认门控级别
### 0.3 分支判断
- 有 DESIGN.md → 迭代模式（第1步迭代）
- 无 DESIGN.md → 创建模式（第1步创建）
---
## 第1步（迭代模式）：理解现状
1. 读取 `docs/README.md`、`docs/INDEX.md` 和 `docs/DESIGN.md` 当前真相源。
2. 读取 `docs/PRD.md` 的相关产品边界和相关模块附录。
3. 仅在需要历史原因时读取 `DESIGN-CHANGELOG.md` 相关段落，不默认扫全文。
4. 用 Agent(Explore) 扫描项目前端文件（HTML/CSS/JS），提取实际使用的设计体系。
5. **对比文档 vs 实际**：DESIGN.md 声称的 token 和代码实际使用的是否一致。
6. 向用户总结当前设计状态，确认理解是否正确
---
## 第1步（创建模式）：从零创建 DESIGN.md
项目没有 DESIGN.md 时走此分支。**必读 [references/create-mode.md](references/create-mode.md)**——
含产品理解四问、美学方向探索（用 search.py 查风格/配色/字体）、三层 Token 生成、模板落地。
## 第2步：设计审计
按门控级别执行审计（浅门控只查涉及项，深门控全量）。**执行前必读
[references/audit-and-scoring.md](references/audit-and-scoring.md)** 的审计节——
含 UX 规则库查询方法、反 AI 模板检查清单、逐项审计表格式。
## 第3步：设计方案
### 3.1 方案设计
对每个设计变更点，通过 AskUserQuestion 确认：
1. **页面布局方案**：用 ASCII 线框图描述布局结构
```
┌─────────────────────────────┐
│ 顶栏：Logo + 导航 + 搜索 │
├──────────┬──────────────────┤
│ 侧边栏 │ 主内容区 │
│ 分类导航 │ 卡片网格 │
└──────────┴──────────────────┘
```
2. **组件设计**：描述组件的视觉表现、所有状态变化、响应式行为
3. **设计体系变更**：新增的颜色、字体、间距等 token（遵循三层架构）
4. **交互方案**：关键交互的状态流转
5. **Image 2 视觉稿**：对 UI/布局/状态变化，生成或引用视觉稿，让用户确认观感是否符合预期。视觉稿只用于确认方向，最终实现仍以 DESIGN.md token、组件规范和真实截图为准。
### 3.2 0-10 交互审查（L1 必选，L2 可选）
对重要设计决策，用以下方式深度审查：
**审查维度：**
| 维度 | 审查内容 |
|------|---------|
| 信息架构 | 导航结构、内容组织、层级深度 |
| 交互状态覆盖 | 所有状态是否定义、边界情况、错误流程 |
| 用户旅程情感弧线 | 从进入到完成的情绪变化、摩擦点 |
| AI 模板痕迹风险 | 方案是否可能产出泛用感的界面 |
| 设计体系对齐 | 方案是否复用已有 token 和组件 |
| 响应式与无障碍 | 移动端体验、键盘导航、屏幕阅读器 |
| 未决设计问题 | 方案中含糊或未定的部分 |
**评分方法：**
对每个维度打 0-10 分，并说明：
- 当前分数及原因
- **满分标准是什么**（具体描述 10 分的状态）
- 从当前到满分需要什么
**就绪度分级：**
- **Ready (≥8)** — 可以直接实现
- **Review needed (5-7)** — 需要在 TODOS.md 记录改进项
- **Redesign needed (<5)** — 该维度需要重新设计
### 3.3 子模块一致性检查
如果当前任务是大需求下的子模块：
1. 读取父页面 DESIGN.md 中的 Token 定义
2. 检查子模块方案是否使用了相同的：
- 配色 token
- 字体 token
- 间距比例尺
- 圆角层级
- 组件风格（卡片、按钮、输入框的视觉一致性）
3. 不一致项必须修正或得到用户明确许可
### 不需要用户确认的内容
- 具体 CSS 属性值（由设计体系推导）
- 细节动效参数
- 响应式断点的具体像素值（沿用已有体系）
---
## 第4步：更新设计文档
### A. 更新 DESIGN CHANGELOG
追加本次变更记录：时间、背景、设计方案、关键决策。
### B. 更新 DESIGN.md
1. 更新版本号、日期
2. 更新迭代摘要区（保留所有版本）
3. 新增/修改组件规范，标记 `[vX.Y 新增/修改]`
4. 更新设计体系 token（如有变更，遵循三层架构）
5. 更新页面布局说明
6. 自洽性检查：文档内部引用是否一致
### C. 可选：生成预览页
对新项目的配色+字体方案，可生成简单 HTML 预览页让用户直观对比：
```html
<!-- 配色预览：展示 Primary/Secondary/Accent 在不同组件上的效果 -->
<!-- 字体预览：展示 Heading/Body 字体在不同层级的视觉效果 -->
```
---
## 第5步：设计质量评估
**执行前必读 [references/audit-and-scoring.md](references/audit-and-scoring.md)** 的评估节——
含 0-10 交互评分维度、健康分计算、B 级门槛（design-impl 的前置条件）。
## 第6步：确认与总结
```
+====================================================+
| 设计交付完成 |
+====================================================+
| 项目：[项目名] |
| 版本：vX.Y |
| 门控级别：[L1/L2] |
| 设计评分：[A-F]（变更前 → 变更后） |
| AI 模板痕迹评分：[A-F] |
| 设计变更：X 项（新增 A / 修改 B） |
| 子模块一致性：[通过 / 不适用] |
| 文件： |
| DESIGN.md — [已更新/已创建] |
| DESIGN-CHANGELOG — [已追加/已创建] |
| 下一步：forge-design-impl 或 forge-eng 实现 |
+====================================================+
```
---
## Feature 状态管理（.features/ 架构）
> 状态标记与通用操作规则见 `~/.claude/skills/_shared/feature-status-protocol.md`。
design 特有动作：启动前确认 prd 行为 `[✅ 已完成]`。
---
## 数据资源
本 Skill 自带以下数据文件（自闭环，无需外部依赖）：
| 文件 | 内容 | 用途 |
|------|------|------|
| `data/colors.csv` | 161 种产品类型的完整配色方案 | 第1.4步配色决策 |
| `data/typography.csv` | 73 组字体搭配（含 Google Fonts 链接） | 第1.5步字体决策 |
| `data/styles.csv` | 84 种设计风格定义 | 第1.3步美学方向 |
| `data/ux-guidelines.csv` | 99 条 UX 规则（10类，含代码示例） | 第2步审计补充 |
| `data/products.csv` | 161 种产品类型的设计属性 | 第1.1步产品定位 |
| `data/ui-reasoning.csv` | 产品类型→设计决策映射 | 自动推荐设计方向 |
| `data/charts.csv` | 25 种图表类型指南 | 数据可视化设计 |
| `data/landing.csv` | 34 种落地页区块类型 | 落地页设计 |
| `scripts/search.py` | 设计资源搜索引擎 | 按关键词搜索配色/字体/风格 |
**搜索脚本用法：**
```bash
# 生成完整设计系统建议
python3 {skill_dir}/scripts/search.py "AI search tool modern minimal" --design-system -p "产品名"
# 按领域深入搜索
python3 {skill_dir}/scripts/search.py "elegant serif" --domain typography
python3 {skill_dir}/scripts/search.py "fintech trust" --domain color
python3 {skill_dir}/scripts/search.py "dashboard data" --domain style
```
---
## 重要规则
1. **纯设计，不写代码。** 产出是 DESIGN.md 和设计方案，不是 CSS/HTML。实现交给 forge-design-impl 或 forge-eng。
2. **像设计师思考，不是 QA 工程师。** 关心感觉对不对、有没有意识、尊不尊重用户。
3. **具体且可操作。** "把 X 改成 Y 因为 Z"——不是"建议优化间距"。
4. **AI 模板痕迹检测是超能力。** 10 个反面模式要直接说出来。
5. **深度优于广度。** 5-10 个充分记录的发现 > 20 个模糊观察。
6. **响应式是设计，不只是"不坏"。** 移动端要有独立的设计意义。
7. **快速胜利很重要。** 始终包含 3-5 个高影响低工作量的改进建议。
8. **不孤立评估。** 每个设计决策放在用户旅程的完整上下文中评判。
9. **门控必须遵守。** L1 评分 < B 不能放行。L2 评分 < C 必须升级。
10. **子模块必须一致。** 大需求下的子模块设计必须与父页面对齐。
---
## 资源
- **设计文档模板**：[references/design-template.md](references/design-template.md)
- **配色库**：[data/colors.csv](data/colors.csv)
- **字体库**：[data/typography.csv](data/typography.csv)
- **UX 规则**：[data/ux-guidelines.csv](data/ux-guidelines.csv)
- **产品类型**：[data/products.csv](data/products.csv)