文档落地路径：遵循 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体系 → forge-design-lab 工作台（布局/比例/密度）→ 完整审计 → 0-10审查 → DESIGN.md
  ├── L2 轻量审查 ──→ 读DESIGN.md → 对照检查 → 重点审计(10项) → 涉及布局/组件时调 forge-design-lab → 一致性验证 → 更新文档
  └── L3 跳过设计 ──→ 纯后端/无UI → 直接进 forge-eng

全程中文。关键设计决策需用户确认后才能定稿。 涉及前端页面、组件、状态或布局时，读取 ~/.claude/skills/_shared/visual-decision-layer.md：布局、比例、密度、栏宽、一屏几张这类决策走 forge-design-lab 工作台门禁（真 token、真像素的骨架，用户在上面改值、判断、保存）；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. 边界情况覆盖 — 超长文本（47 字符的名字）、零结果、网络断开、色盲，每项至少检查一次。
3. 减法检查 — 交付前问"如果只能展示 3 样东西，留哪 3 样？"，其余降级或删除。
4. 体系一致 — 不孤立评估单个页面；对照前后页面和已有 token 检查一致性。

完整的 12 条设计师认知模式与设计批评话术（背景素养）见 references/create-mode.md。

---

提问格式与批量策略见 ~/.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—— 含产品理解四问、美学方向探索（用 search.py 查风格/配色/字体）、三层 Token 生成、模板落地。

第2步：设计审计

按门控级别执行审计（浅门控只查涉及项，深门控全量）。执行前必读 references/audit-and-scoring.md 的审计节—— 含 UX 规则库查询方法、反 AI 模板检查清单、逐项审计表格式。

第3步：设计方案

3.1 方案设计

对每个设计变更点，通过 AskUserQuestion 确认：

1. 页面布局方案：用 ASCII 线框图描述布局结构

   ┌─────────────────────────────┐
   │  顶栏：Logo + 导航 + 搜索   │
   ├──────────┬──────────────────┤
   │  侧边栏   │   主内容区       │
   │  分类导航  │   卡片网格       │
   └──────────┴──────────────────┘
   

2. 组件设计：描述组件的视觉表现、所有状态变化、响应式行为

3. 设计体系变更：新增的颜色、字体、间距等 token（遵循三层架构）

4. 交互方案：关键交互的状态流转

5. 工作台门禁（forge-design-lab，必调）：凡是页面、组件、布局、状态的决策，调用 forge-design-lab：它先用线框确认区域与模块清单，再在真 token、真像素的骨架上让用户逐层审查、改值、保存；本步的 ASCII 线框图只是开场，最终比例以工作台为准。DESIGN.md 里的页面级 token 表由它导出的 tokens.json 生成，不手写。

6. Image 2 视觉稿（辅助）：只在气质、风格方向不明时生成 1-3 张让用户判断观感；不用它判断比例、密度和一屏几张。

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（如有变更，遵循三层架构；页面级/组件级 token 表以 forge-design-lab 生成的区块为准，不手改）
5. 更新页面布局说明（比例与尺寸引用工作台 token，不写死数字）
6. 自洽性检查：文档内部引用是否一致

C. 可选：生成预览页

对新项目的配色+字体方案，可生成简单 HTML 预览页让用户直观对比：

<!-- 配色预览：展示 Primary/Secondary/Accent 在不同组件上的效果 -->
<!-- 字体预览：展示 Heading/Body 字体在不同层级的视觉效果 -->

D. 同步需求设计文档

调用 forge-feature-doc 更新页面布局、状态一览、交互与细节三部分（设计阶段用骨架截图；没有骨架就画页面示意）。DESIGN.md 写给实现看，读者看的是那一份。

---

第5步：设计质量评估

执行前必读 references/audit-and-scoring.md 的评估节—— 含 0-10 交互评分维度、健康分计算、B 级门槛（design-impl 的前置条件）。

第6步：确认与总结

+====================================================+
|              设计交付完成                              |
+====================================================+
| 项目：[项目名]                                        |
| 版本：vX.Y                                           |
| 门控级别：[L1/L2]                                     |
| 设计评分：[A-F]（变更前 → 变更后）                      |
| AI 模板痕迹评分：[A-F]                                 |
| 设计变更：X 项（新增 A / 修改 B）                      |
| 子模块一致性：[通过 / 不适用]                           |
| 文件：                                                |
|   工作台页面包       — [docs/assets/visuals/<page>/ 或 不适用] |
|   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	设计资源搜索引擎	按关键词搜索配色/字体/风格

搜索脚本用法：

# 生成完整设计系统建议
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

设计文档模板：references/design-template.md

---

重要规则

1. 纯设计，不写产品代码。 产出是 DESIGN.md、设计方案，以及 forge-design-lab 的骨架页面包（设计产物，不是产品代码）。实现交给 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. 子模块必须一致。 大需求下的子模块设计必须与父页面对齐。