Vibeflow Design

设计文档生成

以审批通过的 brief.md 为输入。提出实现方案，逐节获得设计审批，产出回答 HOW 的设计文档。

此 skill 已吸收 brainstorming 核心行为：当无 brief 或问题不清晰时，先进行问题探索再进入技术设计。

启动宣告： "正在使用 vibeflow-design — 设计阶段（含问题探索）。"

反模式 A："SRS 足够详细可以直接编码了"

SRS 描述系统做什么。设计文档描述怎么做。即使需求很清晰，实现方案（架构、数据模型、技术栈选择）也需要显式决策和用户审批。

反模式 B："这太简单不需要设计"

每个项目都需要设计。一个 todo list、一个函数工具、一个配置变更——所有项目都需要。"简单"项目正是未经审视的假设造成最多浪费的地方。设计可以很短（真正简单的项目几句话），但你必须展示并获得批准。

检查清单

按顺序完成以下步骤：

0. [问题探索] — 如果无 brief 或问题不清晰，先厘清问题和方向
1. 读取 brief 和 UCD（如需） — 从 docs/changes/<change-id>/
2. 探索技术上下文 — 现有代码、框架、部署环境
3. 读取项目规则 — 从 rules/ 提取本次设计适用的约束并写入设计文档
4. 提出 2-3 个方案 — 带权衡和推荐
5. 逐节设计审批 — 架构、数据模型、API、UI/UX、测试、部署（用户参与式审批）
6. AI 深度审查 — eng review + design review（用户审批后执行）
7. 范围决策 — 基于三方意见判断范围是否需要调整
8. 编写设计文档 — 保存到 docs/changes/<change-id>/design.md
9. 阶段收口确认 — 展示本阶段产物和方案，由用户确认是否进入 tasks
10. 过渡到 tasks — 进入 vibeflow-tasks 生成全量交付计划，并停在人工确认闸门

终止状态是进入 vibeflow-tasks，并在 tasks 人工确认通过前不得进入 build。

步骤 0：问题探索（仅当无 SRS 或问题不清晰时）

当存在 docs/changes/<change-id>/brief.md 且问题已清晰时，跳过此步骤，直接进入步骤 1。

当无 SRS 或问题定义模糊时，先通过问题探索厘清方向：

0.1 检查已有 brief

优先检查是否存在 docs/changes/<change-id>/brief.md：

• 如果存在：读取其内容作为当前 change 的问题定义和边界输入
• 如果不存在：继续以下探索步骤

0.2 探索项目上下文

1. 检查当前项目状态（文件、文档、最近提交）
2. 在提问之前评估范围：如果请求描述多个独立子系统，立即标记并帮助分解
3. 如果项目范围过大（需要多个独立子系统），帮助用户分解为子项目

0.3 逐个提问澄清

一次只问一个问题。优先使用多选题。

通过 AskUserQuestion 提问，聚焦于理解：

• 目的 — 用户真正想要解决的是什么？
• 约束 — 有什么限制条件？（技术栈、时间、资源）
• 成功标准 — 怎么算"做好了"？

使用 AskUserQuestion 格式：

1. Re-ground： 陈述项目和当前问题。（1-2 句）
2. Simplify： 用普通高中生能理解的简单语言解释问题。不用行话，用具体例子。
3. 推荐： RECOMMENDATION: Choose [X] because [one-line reason]
4. 选项： 字母选项 A) ... B) ... C) ...

0.4 提出方案

展示 2-3 个实现方案并带有明确权衡：

## 方案 A：[名称]
**摘要**：[1-2 句]
** Effort**:  [S/M/L/XL]
**风险**:    [低/中/高]
**优点**:    [2-3 点]
**缺点**:    [2-3 点]
**复用**:    [现有代码/模式]

规则：

• 一个必须是"最小可用"（文件最少、diff 最小）
• 一个必须是"理想架构"（最佳长期轨迹）
• 一个可以是创意/差异化路径

RECOMMENDATION: Choose [X] because [one-line reason]

0.5 用户审批方案

使用 AskUserQuestion 展示方案并请求选择：

• 展示推荐的方案及理由
• 等待用户确认或选择其他方案

0.6 探索结论并入设计文档

将问题探索结论写入最终设计文档的"问题定义"和"方案选择"章节，并合并到当前 change 的正式产物中。

步骤 1：读取 Brief 和 UCD（如需）并提取设计输入

1.0 判断是否需要 UCD

1. 运行 python scripts/get-vibeflow-paths.py --json
2. 读取 docs/changes/<change-id>/brief.md
3. 检查 SRS 中是否包含 UI 相关功能需求（FR 含用户界面、页面或组件）
4. 检查 .vibeflow/workflow.yaml 中的 template：
   • prototype / api-standard → 通常无前端 UI，跳过 UCD
   • web-standard / enterprise → 通常有 UI，执行 UCD 子步骤
5. 如判断跳过 UCD，告知用户："SRS/模板 无 UI 需求 — 跳过视觉风格定义"

1.1 读取现有 UCD（如存在）

• 读取 docs/changes/<change-id>/ucd.md（如已存在）
• 提取 UCD 风格 Token：颜色、排版、间距、组件目录
• 将 Token 注入设计文档的 UI/UX 章节

1.2 生成 UCD 内容（如不存在且需要 UI）

当 SRS 有 UI 需求且无现有 UCD 文档时，执行以下子步骤生成风格指南：

前端设计约束加载：

• 先读取 skills/vibeflow-design/references/frontend-design-constraints.md
• 这些约束仅在本次设计涉及前端/UI 时生效
• 在进入视觉风格方案前，先完成下方 4 个前置问题

1.2.0 锁定前端设计方向

在写任何 UI/UX 方案前，先向用户明确这 4 个问题：

1. 谁在用，使用场景是什么
2. 审美方向是什么
3. 用户最后会记住什么
4. 硬约束是什么（框架、无障碍、性能、终端设备、品牌限制等）

规则：

• 一次只推进必要问题，不要堆一串开放式追问
• 审美方向必须具体命名，禁止使用 clean and modern 这类空话
• 在进入后续子步骤前，用一句话复述最终选定的视觉方向
• 必须明确本项目采用的单一样式策略：Tailwind only / CSS Modules only / CSS-in-JS only

1.2.1 定义视觉风格方向

向用户展示 2-3 个视觉风格选项：

## 风格 A：[名称]
**调性**：[1-2 句描述视觉感受]
**色彩方向**：[主色调倾向 — 暖/冷/中性，高/低对比]
**排版方向**：[衬线/无衬线，几何/人文，密度]
**布局方向**：[卡片/列表，紧凑/宽松，固定/流式]
**目标用户契合**：[最适合哪些 SRS 用户画像]

等待用户选择或提供方向。

1.2.2 生成风格 Token

定义锚定整个风格系统的具体设计 Token：

颜色调色板：

| Token | Hex | 用途 | 对比度 |
|-------|-----|------|--------|
| --color-primary | #XXXXXX | 主要操作、链接 | >= 4.5:1 |
| --color-bg-primary | #XXXXXX | 主背景 | |
| --color-text-primary | #XXXXXX | 正文 | >= 4.5:1 |

所有对比度必须满足 WCAG AA（正文 4.5:1，大文本 3:1）。

排版比例： 字体族、大小、字重、行高、用途。

• 明确 display font 和 text font 的分工
• 不要把 Inter、Roboto、system-ui 当作主展示字体

间距与布局： 间距 token（--space-xs/sm/md/lg/xl）、圆角（--radius-sm/md/lg）、阴影（--shadow-sm/md/lg）。

• 必须说明整体空间策略：高密度 / 宽松留白
• 如果桌面审美与移动端约束冲突，要在设计文档中写出 tradeoff

图标风格： 线框/填充/双色、图标库（如 Lucide Icons）。

动效预算：

• 说明关键动效放在哪些状态
• entrance 200-400ms，exit 150-250ms
• 只保留影响感知和反馈的动效，不要把装饰性微动效写满全局

1.2.3 生成组件提示词（如 UI 清单存在）

对 UI 清单中的每种组件类型产出文生图提示词：

### 组件：[组件名]
**变体**：默认、悬停、激活、禁用、错误、加载

#### 基础提示词
> [详细文生图提示词，引用颜色 Token、排版 Token、间距]

1.2.4 生成页面提示词（如页面存在）

对每个关键页面/屏幕产出整页文生图提示词。

1.3 提取关键设计驱动因素

无论是否执行 UCD 子步骤，统一提取：

• 功能范围 — FR 数量、优先级分布、依赖链
• NFR 阈值 — 影响架构的性能目标、可靠性、可扩展性
• 约束 — 限制技术/方案选择的硬限制
• 接口需求 — 外部系统、协议、数据格式
• 用户画像 — 影响 API/UI 设计决策的技术水平
• UCD 风格 Token（如已生成或存在）— 颜色、排版、间距、组件目录 -> 指导 UI/UX 章节

1.4 列出开放问题

列出必须在设计前解决的 SRS 开放问题。

1.5 读取现有代码结构与本次影响面（现有项目改动）

如项目不是从空仓开始，设计阶段默认读取：

• docs/overview/CURRENT-STATE.md

如上述影响分析文件不存在，先运行：

• python scripts/map-change-impact.py --project-root . --source design

设计文档必须显式吸收以下内容：

• 重点模块
• 关键入口
• 风险提示
• 建议先读

步骤 2：探索技术上下文

1. 探索项目将要构建的现有代码/仓库
2. 识别 SRS 中未提及的技术约束（如单体仓库结构、CI/CD 管线、现有库）
3. 检查设计文档模板

步骤 3：读取项目规则并写入设计约束

如果项目根目录存在 rules/，这是设计阶段的一等输入，不是实现阶段才补读的附件。

1. 判断本次设计的主技术栈语言。
2. 运行：

python scripts/vibeflow_rules.py --project-root . --stage design --language <language> --format markdown --design-section

3. 将输出原样写入 docs/changes/<change-id>/design.md 的固定章节：

## Project Rules And Constraints

4. 后续架构、模块边界、接口兼容性、测试策略都必须显式遵守该章节。
5. 如果某条规则需要例外，必须在设计文档中写清：
   • 例外原因
   • 风险
   • 回收计划

禁止跳过： 当 rules/ 存在时，不得省略 ## Project Rules And Constraints 章节。

步骤 4：提出方案

展示 2-3 个实现方案并带有明确权衡：

## 方案 A：[名称]
**原理**：[1-2 句]
**优点**：[要点列表]
**缺点**：[要点列表]
**最适用于**：[条件]
**NFR 影响**：[该方案如何影响 SRS NFR 阈值]
**第三方依赖**：[关键库/框架及版本]

## 推荐：方案 [X]
**理由**：[为何最适合 SRS 约束和 NFR]

每个方案必须对照 SRS 约束和 NFR 阈值评估。无法满足"Must" NFR 的方案被淘汰。

步骤 5：逐节审批

非简单项目逐节展示并获得审批：

1. 架构 — 系统组件、逻辑视图、技术栈决策
   • 必须包含 逻辑视图（Mermaid graph）显示层/包/模块及依赖方向
   • 必须包含 组件图（Mermaid graph）显示运行时组件和交互
   • 必须论证技术栈选择与 SRS 约束的关系
2. 关键功能设计 — 每个关键功能或功能组一章
   • 每章必须至少包含：
     • 类图（Mermaid classDiagram）
     • 一个行为图：序列图（sequenceDiagram）或流程图（flowchart）
   • 所有图表必须使用 Mermaid 格式
3. 数据模型 — 模式、关系、存储策略
   • 必须使用 Mermaid ER 图（erDiagram）
4. API / 接口设计 — 端点、契约、协议
5. UI/UX 方案（如适用）— 布局策略、交互模式
   • 如 UCD 存在：必须引用 UCD 风格 Token 和组件目录
   • 必须通过 frontend-design-constraints.md 自查常见模板味陷阱，避免默认 hero / 默认卡片网格 / 默认导航栏
6. 第三方依赖 — 所有库/框架带精确版本号
   • 验证依赖间互相兼容
   • 验证与目标运行时版本兼容
   • 记录每个依赖的许可证类型
7. 测试策略 — 测试类型、覆盖率目标、工具
8. 部署/基础设施（如适用）— 托管、CI/CD、环境
9. 开发计划 — 里程碑、任务分解、优先级排序
   • 必须定义有明确退出标准的里程碑
   • 必须将功能分解为优先级任务（P0-P3）
   • 必须展示依赖链（Mermaid graph）标识关键路径
   • 必须包含风险评估和缓解策略
   • 前后端配对排序：当项目同时有后端和前端功能时，按后端 A -> 前端 A -> 后端 B -> 前端 B 排序

简单项目（< 5 个功能）：合并所有章节为单次审批步骤，但仍需包含必要图表和依赖版本。

步骤 6：AI 深度审查（用户审批后执行）

用户审批设计后，执行 AI 独立深度审查——这是 AI 质量把关，不重复用户审批。

5.1 工程审查

调用 vibeflow-plan-eng-review 对设计文档进行工程评审：

Skill: vibeflow-plan-eng-review

评审内容：架构设计、数据流、测试策略、性能风险、安全边界。

完成后将结论写入 docs/changes/<change-id>/design.md 的 ## Engineering Review 小节。

5.2 设计审查

调用 vibeflow-plan-design-review 对设计文档进行七轮设计评审：

Skill: vibeflow-plan-design-review

评审内容：信息架构、交互状态、用户旅程、AI 污染风险、设计系统一致性、响应式与无障碍。

完成后将结论写入 docs/changes/<change-id>/design.md 的 ## Design Review 小节。

5.3 审查结论汇总

提取两个 review 的关键发现：

## AI 审查结论

**日期**：YYYY-MM-DD
**设计文档**：`docs/changes/<change-id>/design.md`

### 工程审查（vibeflow-plan-eng-review）
- Architecture: [N] issues
- Code Quality: [N] issues
- Test Coverage: [N] gaps
- Performance: [N] issues
- **严重问题**： [列出 critical issues，需在 scope decision 前处理]

### 设计审查（vibeflow-plan-design-review）
- Information Architecture: [N]/10
- Interaction States: [N]/10
- User Journey: [N]/10
- AI Slop Risk: [N]/10
- Design System: [N]/10
- Responsive & A11y: [N]/10
- **待解决设计问题**： [列出影响范围的问题]

步骤 7：范围决策

基于用户审批的设计方案 + eng review + design review 三方意见，综合判断范围是否需要调整。

6.1 质疑范围

6.2 范围决策

产出三选一的决策：

扩展（Expand）：eng/design review 发现当前范围遗漏了高价值、低成本的功能。

保持（Hold）：设计合理，eng/design review 无重大问题。

缩减（Reduce）：eng/design review 发现范围过大或风险过高。

6.3 用户确认范围

通过 AskUserQuestion 展示 AI 审查结论和范围决策建议：

1. Re-ground： 陈述项目、已审批的设计、AI 审查关键发现。（1-2 句）
2. Simplify： 用普通高中生能理解的语言解释 eng/design review 发现了什么风险。
3. 推荐： RECOMMENDATION: [Expand / Hold / Reduce] — [one-line reason]
4. 选项： A) 接受推荐 B) 调整范围 C) 先解决 critical issues 再决定

6.4 更新设计文档

如果范围有调整，将决策记录写入设计文档末尾：

## 范围决策

**决策**：[Expand / Hold / Reduce]
**理由**：[简要说明]
**调整**：[如范围有变化，列出具体调整内容]
**eng review 发现**：[N] issues（critical: [N]）
**design review 发现**：[N]/10 overall

步骤 8：编写设计文档

保存到 docs/changes/<change-id>/design.md。

执行交接硬要求：

• 当 rules/ 存在且有适用规则时，设计文档必须包含 ## Project Rules And Constraints
• 设计文档必须包含且只包含一个可解析的 Build Contract TOML 代码块
• 每个可实施 feature 必须包含一个可解析的 Implementation Contract TOML 代码块
• Implementation Contract 至少要写出：feature_id、title、priority、dependencies、file_scope、verification_commands 或 verification_steps
• Build 阶段以这些 TOML 契约作为 feature 权威输入；tasks.md 由下一阶段 vibeflow-tasks 单独生成，用来回答“如何按稳定顺序落地”

步骤 9：阶段收口确认

设计阶段完成后，必须向用户展示：

• design.md 的关键方案摘要
• Build Contract 与 Implementation Contract 的覆盖范围
• Engineering Review 结论
• Design Review 结论
• 最终范围决策

然后明确请用户确认：

• 是否接受本阶段产物
• 是否进入 tasks

未确认前不得进入 tasks。

步骤 10：过渡到 tasks

设计文档保存并提交后：

1. 总结初始化需要的关键输入：
   • 来自 SRS：约束、假设、NFR、用户画像、术语表、功能需求 -> 功能清单
   • 来自设计：技术栈、架构决策 -> tech_stack、项目骨架
2. 在用户确认后进入 vibeflow-tasks 生成执行级任务计划

图表要求

所有架构和设计视图必须使用 Mermaid 语法。

红线

集成

调用者： vibeflow-router（design 阶段） 依赖： docs/changes/<change-id>/brief.md；可选 docs/changes/<change-id>/ucd.md 链接到： vibeflow-tasks（scope decision 通过后） 产出：

• docs/changes/<change-id>/design.md（设计文档，含 UI/UX 章节、工程审查、设计审查与范围决策）

UCD 行为说明：

• SRS 有 UI 需求 + ucd.md 已存在：读取 UCD 作为输入，跳过 UCD 生成
• SRS 有 UI 需求 + 无 ucd.md：执行 UCD 子步骤（步骤 1.2）生成风格 Token 和提示词，并保存到 docs/changes/<change-id>/ucd.md
• SRS 无 UI 需求或 template 为 api-standard/prototype：跳过 UCD，告知用户
• 无论 UCD 是读取还是生成，最终都内联到设计文档的 UI/UX 章节中
• 当前端/UI 适用时，必须额外遵守 skills/vibeflow-design/references/frontend-design-constraints.md