---
name: forge-design-impl
description: '设计实现：将 DESIGN.md 转化为代码。反AI模板编码、shadcn/ui组件推荐、Token驱动样式、CSS优先修改、原子提交。读取 Image 2/Figma 视觉稿作观感参考，最终以真实截图和 CSS 断言验证。从 forge-design 接力，或 forge-eng 调用。触发方式：用户说"实现设计"、"forge-design-impl"、设计文档确认后需要写代码时使用。'
---

> **文档落地路径**：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
> `~/claudecode_workspace/工具/forge-cookbook/skills/forge-doc-policy/doc-paths.md`。

# /forge-design-impl：设计实现

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

## 前置条件

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

---

## 流程

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

---

## 第1步：识别实现清单

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

1. 读取 DESIGN CHANGELOG 最新条目，确定本次变更范围
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 做列表图标
- 不要装饰性浮动色块

### 组件选择指导

如果项目使用 shadcn/ui 或类似组件库：

| 组件类别 | 推荐组件 | 使用场景 |
|----------|---------|---------|
| **表单** | Input, Select, Textarea, Checkbox, Radio, Switch, Slider | 数据输入 |
| **布局** | Card, Separator, Tabs, Accordion, Collapsible | 内容组织 |
| **叠加层** | Dialog, Sheet, Popover, Tooltip, HoverCard | 辅助信息 |
| **反馈** | Alert, Toast, Progress, Skeleton | 状态反馈 |
| **导航** | NavigationMenu, Breadcrumb, Pagination, Command | 导航系统 |
| **展示** | Table, Badge, Avatar, Calendar | 数据展示 |

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

---

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

每个实现项完成后：

### 3.1 自检

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

### 3.2 提交

```bash
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 验证 或 cn-qa-design 设计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. **响应式不是可选的。** 每个变更都必须考虑移动端。