# Dwf Design

> 当用户需要单独执行 DWF 工作流的设计稿阶段时必须使用本技能。它从已有需求文档、用户提供的 Figma/设计链接、图片素材或简短设计要求中生成或记录目标 spec 目录下 `02-设计稿/设计稿.md`，必要时保存设计图片到 `02-设计稿/images/`，并请求用户确认。适用于“生成设计稿”“补充设计稿”“根据需求文档写设计说明”“记录 Figma 设计稿”“抽离设计稿步骤”等场景。可独立运行，也可作为 dwf-orchestrator 编排的工作流的一部分（state.json 中存在 `status: active` 且 `current_step: design` 的 spec 时进入工作流模式）。

- Skill: `xiao0916/dwf-design` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add xiao0916/dwf-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiao0916/dwf-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: xiao0916 (https://skillmd.com/u/xiao0916)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiao0916/dwf-design

---


# dwf-design

本技能用于单独执行 DWF 工作流的“设计稿”阶段。它只负责收集、生成或记录设计稿信息，产出目标 spec 目录下 `02-设计稿/设计稿.md`；独立运行时不启动完整开发工作流，工作流模式下按 `.dwf/state.json` 继续当前阶段。

<HARD-GATE>
以下规则不可违反：

1. **只处理设计稿阶段。**
   本技能默认只创建或更新目标 spec 目录下 `02-设计稿/设计稿.md`，以及必要的 `02-设计稿/images/` 图片目录。不创建其它阶段文档或代码。

2. **目标 spec 目录由运行模式决定，不由本技能臆造。**
   - 工作流模式：读取 `.dwf/state.json`，在 `specs` 数组中找 `status: "active"` 且 `current_step: "design"` 的 spec，以 `.dwf/specs/{spec.name}` 作为目标 spec 目录。若该 spec 的 `shared_ref` 非空（兄弟 spec），优先读取 `.dwf/specs/{shared_ref}/01-需求/需求文档.md` 作为需求依据，而非本 spec 内的需求文档。
    - 独立模式：`.dwf/state.json` 不存在或不存在满足条件的 active spec。用 `question` 询问用户目标目录，默认提议 `.dwf/specs/{今日日期}-{seq}-feat-{描述}`，其中 `seq` 扫描 `.dwf/specs/` 现有 spec 目录名中的最大序号 +1（无则 001），由用户确认或修改。

3. **独立模式下不要创建或推进 `.dwf/state.json`。**
   独立模式只写目标 spec 目录下的设计稿与该 spec 的 `_meta.json`（如本技能创建该 spec）。不要把项目推进到 breakdown、plans、todos 或 code。只有工作流模式下才在用户确认后更新 state.json 中该 spec 的 `current_step`。

4. **不要创建完整工作流目录。**
   除目标 spec 目录下的 `02-设计稿/` 外，不要主动创建 `01-需求/`、`03-需求分析/`、`04-技术方案/`、`05-实现清单/`。不要修改已有需求文档。

5. **确认前不要覆盖已有设计稿文档。**
   如果目标 spec 目录下 `02-设计稿/设计稿.md` 已存在，先读取并告知用户已有文档，询问是保留、修改还是替换。用户确认前不要覆盖。

6. **全程使用中文。**
   除非用户明确要求使用其他语言，所有与用户的交互、设计澄清问题、生成文档、标题、标签、表格内容、说明文字、测试记录、审计结论和产物说明都必须使用中文。代码、文件路径、命令、API 名、技术术语、第三方库名、设计工具名和用户提供的原文内容可以保留英文。

</HARD-GATE>

## 触发后流程

### 1. 探查上下文

- 检查 `.dwf/state.json` 是否存在，确定运行模式（见步骤 2）。
- 如果目标 spec 目录下 `02-设计稿/设计稿.md` 存在，先读取并按“已有文档处理”执行。
- 读取需求依据：目标 spec 目录下 `01-需求/需求文档.md` 若存在则读取；工作流模式下若该 spec 的 `shared_ref` 非空，优先读取 `.dwf/specs/{shared_ref}/01-需求/需求文档.md`。
- 如果用户提供本地文件路径，读取文件内容；如果是图片，记录图片路径并在可能时复制或引用到目标 spec 目录下 `02-设计稿/images/`。
- 如果用户提供 Figma、网页、飞书或其他外部链接，根据链接类型使用相应技能读取或记录链接；无法读取时也要把链接写入设计稿来源。
- 如果用户只给出简短想法，先澄清会影响设计方向的最少信息。

### 2. 判断运行模式与目标 spec 目录

读取 `.dwf/state.json`：

- **工作流模式**：在 `specs` 数组中找到 `status: "active"` 且 `current_step: "design"` 的 spec。目标 spec 目录为 `.dwf/specs/{spec.name}/`。若 `spec.design_skipped` 为 true（用户在需求阶段已选择跳过设计稿），直接在目标 spec 目录下 `02-设计稿/设计稿.md` 写"设计稿阶段已跳过，无设计稿。"，把 `design_skipped: true` 与 `design` 加入 `affected_stages` 排除后确认推进。
  - 设计稿完成并经用户确认后，把该 spec 的 `current_step` 更新为 `"breakdown"`、把 `design` 追加到 `confirmed_stages`，同步 `_meta.json` 与顶层 `updated_at`。
  - 遵循 dwf-orchestrator 的确认机制，不跳过用户确认。

- **独立模式**：`.dwf/state.json` 不存在，或不存在满足条件的 active spec。
  - 用 `question` 询问用户目标 spec 目录，默认提议 `.dwf/specs/{今日日期}-{seq}-feat-{描述}`（`seq` 扫描 `.dwf/specs/` 现有 spec 目录名中的最大序号 +1，无则 001），由用户确认或修改。
  - 如目标 spec 目录不存在，创建它及其下 `02-设计稿/`、`02-设计稿/images/`。
  - 在该 spec 目录下写一份初始 `_meta.json`（`name` 为目录名、`status: "active"`、`current_step: "design"`、`is_shared_context: false`、`shared_ref: null` 等）。
  - 不要创建 `.dwf/state.json`，不推进完整工作流。
  - 设计稿阶段完成后请求用户确认，确认后停止。

### 3. 判断设计稿来源

根据输入选择一种方式：

- **提供链接：** 记录设计稿 URL、文件名或页面名；如果能获取截图，保存到 `02-设计稿/images/`。
- **提供图片：** 将图片信息整理进设计稿文档；如果需要复制图片，保存到 `02-设计稿/images/`。
- **AI 生成：** 基于需求文档和用户描述生成设计说明；如环境允许，可生成 HTML/CSS mockup 截图或图片产物并保存到 `02-设计稿/images/`。
- **跳过：** 将 `02-设计稿/设计稿.md` 写为“设计稿阶段已跳过，无设计稿。”，并说明后续阶段需要基于需求文档推进。

### 4. 澄清缺失信息

信息不足时一次只问一个问题，优先澄清：

1. 目标端：PC 端、移动端或双端。
2. 设计稿来源：链接、图片、AI 生成或跳过。
3. 关键页面数量与页面名称。
4. 期望风格、品牌色、字体或参考产品。
5. 关键交互与响应式要求。

如果可以合理假设，先明确写入“待确认项”，不要为了细枝末节阻塞产出。

### 5. 生成设计稿文档

读取本技能目录下 `references/design_template.md` 作为模板保存到目标 spec 目录下：

```text
{目标 spec 目录}/02-设计稿/设计稿.md
```

生成规则：

- 使用模板中的结构：项目名称、设计稿来源、链接、设计稿图片、设计说明、响应式适配和待确认项。
- 项目名称优先来自需求文档（目标 spec 或共享上下文 spec 的 `01-需求/需求文档.md`）；缺失时从用户描述中提取，仍不明确则写“待确认”。
- 设计说明应覆盖整体风格、主色调、字体、间距规范、关键页面描述和关键交互。
- 如果没有真实图片，不要伪造截图路径；可以写“暂无图片”并在待确认项中标注。
- 如果生成或保存了图片，使用相对路径 `images/<文件名>` 在文档中引用，图片放在目标 spec 目录下 `02-设计稿/images/`。

### 6. 请求用户确认

生成文档后，向用户展示保存位置和简要摘要，并请求确认：

- 如果用户确认，说明设计稿阶段已完成。
- 如果用户提出修改意见，更新 `02-设计稿/设计稿.md`，并再次请求确认。
- 如果用户要求跳过，按“跳过”格式更新设计稿文档。

确认完成后：

- 独立模式：停止，不自动进入需求分析、技术方案、实现清单或编码。
- 工作流模式：更新该 spec 的 `current_step` 为 `"breakdown"`、把 `design` 追加到 `confirmed_stages`，同步 `_meta.json` 与 `updated_at`，由 dwf-orchestrator 推进。

## 已有文档处理

如果目标文件已存在：

1. 读取 `{目标 spec 目录}/02-设计稿/设计稿.md`。
2. 总结当前文档的项目名称、设计稿来源和主要设计内容。
3. 询问用户要如何处理：
   - 保留现有设计稿，仅查看或总结。
   - 基于现有设计稿修改。
   - 替换为新设计稿。
4. 只有用户明确选择修改或替换后，才能写入文件。

修改已有文档时，保留原有结构，除非用户要求重写。不要创建 `设计稿-v2.md` 之类的新版本文件，除非用户明确要求。

## 完成前检查

结束前确认：

- 只创建或更新了目标 spec 目录下 `02-设计稿/设计稿.md` 和必要图片。
- 独立模式下没有创建 `.dwf/state.json`。
- 独立模式下没有创建除目标 spec 目录 `02-设计稿/` 外的其它阶段目录。
- 独立模式下没有推进后续阶段。
- 工作流模式下只在用户确认后更新该 spec 的 `current_step` 为 `breakdown`。
- 文档内容为中文。
- 文档遵循本技能目录下 `references/design_template.md`。
- 已说明保存路径和下一步需要用户确认的事项。