forge-design-impl

name	forge-design-impl
description	设计实现：把 DESIGN.md 转成代码，只改样式不改逻辑；CSS 优先、Token 驱动、反 AI 模板、原子提交，以真实截图和 CSS 断言验证。 触发方式：用户说"实现设计"、"forge-design-impl"、设计文档确认后需要写代码时。

文档落地路径：遵循 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/raw 只在追溯旧决策时读取。 详细规则见 ~/.claude/skills/_shared/current-doc-loading.md。

/forge-design-impl：设计实现

将 DESIGN.md 的设计规范转化为代码。只改样式和布局，不改业务逻辑。

前置条件

1. DESIGN.md 必须存在且已通过 forge-design 审核（评分 ≥ B）
2. 如果有 .features/{feature-id}/status.md，确认 design 行为 [✅ 已完成]
3. 读取 docs/README.md、docs/INDEX.md、docs/DESIGN.md 当前真相源和本次涉及的模块附录，理解设计体系 token、组件规范、页面布局
4. 如果 .features/{feature-id}/feature-spec.md、DESIGN.md 或模块附录中有 Image 2 / Figma / 视觉稿链接，读取并作为观感参考；实现真相源仍是 DESIGN.md 的 token 和组件规则

---

流程

读取 DESIGN.md → 识别实现清单 → 逐项实现 → 每项自检 → 原子提交 → 全部完成后质量验证

---

第1步：识别实现清单

从 DESIGN.md 中提取需要实现的设计变更：

1. 读取 .features/{feature-id}/status.md / feature spec 中的设计交付项；如需追溯历史，再读 docs/CHANGELOG.md 顶部索引和相关 DESIGN-CHANGELOG.md 条目
2. 列出具体实现项，每项包含：
   • 变更内容（如"卡片组件圆角从 8px 改为 12px"）
   • 涉及文件（定位 CSS/样式文件）
   • 预计改动量（小/中/大）
3. 向用户展示清单，确认后开始实现
4. 若存在视觉稿，额外列出：
   • 视觉稿路径
   • 用户确认的关键观感（如信息密度、主次层级、空态情绪）
   • 实现后需要用真实截图对比的页面/状态

---

第2步：实现设计变更

实现原则

1. CSS 优先

• 优先修改 CSS/样式文件，而非组件结构
• CSS 修改更安全、更可逆
• 只在布局变更时才改 HTML 结构

2. Token 驱动

• 所有样式值引用 DESIGN.md 定义的 token
• 不硬编码颜色值、字号、间距
• 使用 CSS 变量或 Tailwind 配置中的 token

3. 遵循现有代码风格

• 不引入新的 CSS 方法论
• 如果项目用 Tailwind，用 Tailwind；如果用 CSS Modules，用 CSS Modules
• 不为"更好"而重写不相关的样式

4. 响应式必须

• 所有变更都要考虑移动端
• 移动端不是缩小版桌面——要有独立的设计意义
• 断点处理遵循 DESIGN.md 定义的断点

反 AI 模板编码指导

实现时主动避免以下泛用模式：

排版：

• 不要所有文本都 text-align: center
• 标题用 DESIGN.md 指定的字体，不要默认 Inter
• 行高、字间距遵循设计体系，不用浏览器默认值

配色：

• 不要用紫色渐变做英雄区背景
• 不要用彩色圆圈包裹图标
• 颜色来自 token，不要随意用 Tailwind 调色板

布局：

• 不要千篇一律的三列等宽网格
• 不要所有区块等高
• 留白要有意——不是统一的 py-20
• 圆角要有层级——按钮小圆角，卡片中圆角，模态大圆角

组件：

• 不要左边框高亮卡片（border-left: 3px solid accent）
• 不要用 emoji 做列表图标
• 不要装饰性浮动色块

2026-07 增量（对照 anthropics/frontend-design 最新版）：

• 不要"暖奶油色三件套"（#F4F1EA 类背景 + 高对比衬线 + 土红 accent）——AI 默认审美之一
• 不要"暗底 + 酸绿/朱红单色 accent"——同上
• 数字标记（01/02/03）只在内容真是序列/时间线时才用，不做装饰
• 显示字体与正文字体不要来自同一家族；字体是页面个性的载体，不选中性保险款
• 不堆砌散落的动画效果；大胆只花在一个签名元素上，周围保持克制
• Chanel 原则：交付前回看一眼，移除一件装饰

组件选择指导

组件选型遵循 shadcn/ui 官方分类，按需查官方文档。

无障碍要求：

• 所有交互组件必须键盘可操作
• Dialog/Sheet 必须有焦点锁定（focus trap）
• 表单必须有 visible label（不只是 placeholder）
• 错误消息靠近输入字段

---

第3步：逐项实现 + 原子提交

每个实现项完成后：

3.1 自检

1. 读取 DESIGN.md 对应规范
2. 对比实现结果是否一致
3. 检查响应式表现（心理模拟移动端效果）
4. 检查是否引入了 AI 模板痕迹

3.2 提交

git add <只改动的文件>
git commit -m "style(design): 简短描述变更内容"

• 每个逻辑单元一个提交
• 不打包多个不相关的设计变更
• 提交格式：style(design): 具体描述

---

第4步：质量验证

所有变更实现后：

4.1 设计一致性检查

1. 对比 DESIGN.md 和实际渲染结果
2. 检查 token 是否正确引用（grep 硬编码值）
3. 检查响应式断点是否按规范处理
4. 如果有 Image 2 视觉稿，启动页面后截取真实截图，做定性对比：
   • 信息层级是否一致
   • 密度和留白是否接近
   • 主操作、状态、空态/错态是否覆盖
   • 明显偏离时回到 forge-design 记录设计差异，而不是擅自改 DESIGN.md

注意： Image 2 不是 QA 证据，也不是像素级规范。最终验收证据必须是真实截图、CSS 属性和行为断言。

4.2 AI 模板痕迹扫描

过一遍 10 个反面模式，确认实现中没有引入泛用感

4.3 向用户展示结果

+====================================================+
|              设计实现完成                              |
+====================================================+
| 项目：[项目名]                                        |
| 实现项：X 项                                          |
| 提交数：X 个                                          |
| 文件变更：[列出修改的样式/布局文件]                     |
| Token 引用率：[X%]（vs 硬编码值）                      |
| AI 痕迹检查：[通过/发现N项]                            |
| 下一步：forge-qa 验证             |
+====================================================+

---

Feature 状态管理

操作规则

1. 启动时：确认 design 行为 [✅ 已完成]，将 design-impl 行（或 eng 行）更新为 [🔄 进行中]
2. 完成后：更新为 [✅ 已完成]

---

重要规则

1. 只改样式和布局，不改业务逻辑。 如果需要改 JS 逻辑，那是 forge-eng 的工作。
2. DESIGN.md 是唯一真相源。 不要"改进"设计——按文档实现。有异议回 forge-design 讨论。
3. CSS 优先。 能用 CSS 解决的不改 HTML 结构。
4. Token 驱动。 不硬编码颜色/字号/间距值。
5. 原子提交。 每个逻辑单元一个 commit。
6. 反 AI 模板。 实现中主动避免泛用模式。
7. 响应式不是可选的。 每个变更都必须考虑移动端。