# Forge Design Impl

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

- Skill: `yike-gunshi/forge-design-impl` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yike-gunshi/forge-design-impl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yike-gunshi/forge-design-impl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: yike-gunshi (https://skillmd.com/u/yike-gunshi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yike-gunshi/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 提交

```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 验证             |
+====================================================+
```

---

## 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. **响应式不是可选的。** 每个变更都必须考虑移动端。