vibeflow-ucd

UI 组件设计 (UCD) 风格指南生成

以审批通过的 SRS 为输入。分析 UI 相关需求，定义视觉风格方向，产出包含文生图模型提示词的 UCD 风格指南 — 确保所有前端功能共享统一的视觉语言。

在你展示 UCD 风格指南并获得用户批准之前，不得调用任何设计技能、实现技能、编写任何代码。此规则适用于每个含 UI 功能的项目。

适用条件

此阶段在 SRS 审批后、设计前运行。适用于：

• 审批通过的 SRS 包含 UI 相关功能需求（FR-xxx 含用户界面、页面或组件）
• docs/changes/<change-id>/ucd.md 不存在

如 SRS 无 UI 功能：宣布"SRS 中未检测到 UI 功能 — 跳过 UCD 阶段"，并立即进入 vibeflow-design。

检查清单

按顺序完成以下步骤：

1. 读取审批通过的概要边界 — 从 docs/changes/<change-id>/brief.md
2. 提取 UI 范围 — 识别所有 UI 相关需求和用户画像
3. 定义视觉风格方向 — 提出 2-3 个风格选项
4. 生成组件级提示词 — 每种 UI 组件类型的文生图提示词
5. 生成页面级提示词 — 每个关键页面/屏幕的文生图提示词
6. 定义风格 Token — 颜色、排版、间距、图标
7. 展示并审批 UCD — 非简单项目逐节审批
8. 保存 UCD 文档 — docs/changes/<change-id>/ucd.md 并提交
9. 过渡到设计 — 进入 vibeflow-design

终止状态是进入 vibeflow-design。

步骤 1：读取 SRS 并提取 UI 范围

1. 运行 python scripts/get-vibeflow-paths.py --json
2. 读取 docs/changes/<change-id>/brief.md（如存在 legacy requirements.md，仅作补充）
3. 提取 UI 相关输入：
   • 用户画像 — 技术水平、无障碍需求、设备偏好
   • 含 UI 的功能需求 — 屏幕、页面、表单、仪表盘、数据可视化
   • NFR 易用性要求 — 无障碍标准（WCAG 等级）、响应式断点、国际化
   • 约束 — 品牌指南、平台限制、浏览器支持
   • 接口需求 — 外部 UI 组件、需要集成的设计系统
4. 构建 UI 清单 — 列出 SRS 暗示的每个不同的屏幕/页面/组件类型
5. 如 SRS 缺乏足够 UI 细节 -> 通过 AskUserQuestion 向用户询问

步骤 2：定义视觉风格方向

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

## 风格 A：[名称]（如"简洁商务"、"大胆现代"、"柔和极简"）
**调性**：[1-2 句描述视觉感受]
**色彩方向**：[主色调倾向 — 暖/冷/中性，高/低对比]
**排版方向**：[衬线/无衬线，几何/人文，密度]
**布局方向**：[卡片/列表，紧凑/宽松，固定/流式]
**目标用户契合**：[最适合哪些 SRS 用户画像]
**参考风格**：[借鉴的设计语言 — Material、Ant、Apple HIG 等]

## 推荐：风格 [X]
**理由**：[为什么最适合 SRS 的画像、约束和 NFR]

等待用户选择或提供方向。整合反馈后再继续。

步骤 3：生成风格 Token

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

3.1 颜色调色板

| Token | Hex | 用途 | 对比度 |
|-------|-----|------|--------|
| --color-primary | #XXXXXX | 主要操作、链接、激活状态 | >= 4.5:1（白底） |
| --color-primary-hover | #XXXXXX | 主色悬停态 | |
| --color-secondary | #XXXXXX | 次要操作、强调色 | >= 4.5:1（白底） |
| --color-bg-primary | #XXXXXX | 主背景 | |
| --color-bg-secondary | #XXXXXX | 卡片/区块背景 | |
| --color-text-primary | #XXXXXX | 正文 | >= 4.5:1（主背景上） |
| --color-text-secondary | #XXXXXX | 说明文字、提示 | >= 3:1（主背景上） |
| --color-success | #XXXXXX | 成功状态 | |
| --color-warning | #XXXXXX | 警告状态 | |
| --color-error | #XXXXXX | 错误状态、破坏性操作 | |
| --color-border | #XXXXXX | 默认边框 | |

• 所有对比度必须至少满足 WCAG AA（正文 4.5:1，大文本 3:1）
• 如 SRS 指定 WCAG AAA，则比率需达 7:1 / 4.5:1

3.2 排版比例

| Token | 字体族 | 大小 | 字重 | 行高 | 用途 |
|-------|--------|------|------|------|------|
| --font-heading-1 | [字体] | [大小] | [字重] | [行高] | 页面标题 |
| --font-heading-2 | [字体] | [大小] | [字重] | [行高] | 章节标题 |
| --font-heading-3 | [字体] | [大小] | [字重] | [行高] | 卡片标题 |
| --font-body | [字体] | [大小] | [字重] | [行高] | 正文 |
| --font-body-small | [字体] | [大小] | [字重] | [行高] | 说明、提示 |
| --font-label | [字体] | [大小] | [字重] | [行高] | 表单标签、按钮 |
| --font-code | [字体] | [大小] | [字重] | [行高] | 代码片段 |

3.3 间距与布局

| Token | 值 | 用途 |
|-------|-----|------|
| --space-xs | [值] | 紧凑内边距 |
| --space-sm | [值] | 默认内边距 |
| --space-md | [值] | 区块间距 |
| --space-lg | [值] | 页面区域间距 |
| --space-xl | [值] | 主要布局分隔 |
| --radius-sm | [值] | 按钮、输入框 |
| --radius-md | [值] | 卡片 |
| --radius-lg | [值] | 模态框、对话框 |
| --shadow-sm | [值] | 细微层次感 |
| --shadow-md | [值] | 卡片、下拉菜单 |
| --shadow-lg | [值] | 模态框、覆盖层 |

3.4 图标与图像

- **图标风格**：[线框/填充/双色] [圆角/锐利] [线条粗细]
- **图标库**：[推荐库及版本，如 Lucide Icons 0.263.0]
- **插画风格**：[扁平/等距/3D/手绘] [色彩处理]
- **摄影处理**：[如适用 — 滤镜、叠加、裁切规则]

步骤 4：生成组件级提示词

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

提示词结构

### 组件：[组件名]
**SRS 追溯**：[FR-xxx, NFR-xxx]
**变体**：[列出变体 — 默认、悬停、激活、禁用、错误、加载]

#### 基础提示词
> [详细的文生图提示词，描述在审批风格下的视觉外观。包括：布局结构、按名称引用颜色 Token、排版 Token、间距、边框处理、阴影、状态指示器。精确描述比例、对齐和视觉层次。]

#### 变体提示词
> **悬停态**：[相对基础的变化]
> **错误态**：[相对基础的变化]
> **加载态**：[相对基础的变化]
> **深色模式**（如适用）：[相对基础的变化]

#### 风格约束
- [约束 1 — 如"按钮高度必须精确为 40px 以满足触控目标"]
- [约束 2 — 如"错误文本必须出现在输入框下方，不得为提示框"]

必需组件类型

至少生成以下组件类型的提示词（仅当 UI 清单中确实不存在时跳过）：

类别	组件
导航	顶栏/导航栏、侧边栏、面包屑、标签页、分页
输入	文本输入、多行文本、选择/下拉、复选框、单选、开关、日期选择
操作	主按钮、次按钮、图标按钮、链接按钮、浮动按钮
反馈	提示/吐司、模态/对话框、进度条、骨架屏、空状态
数据展示	表格、卡片、列表项、标签/徽章、头像、工具提示
布局	页面外壳、表单布局、网格/瀑布流、分隔线

步骤 5：生成页面级提示词

对 UI 清单中识别的每个关键页面/屏幕，产出整页文生图提示词。

### 页面：[页面名]
**SRS 追溯**：[FR-xxx]
**用户画像**：[该页面的主要用户]
**入口**：[用户如何到达此页面]

#### 布局描述
[描述页面布局：头部位置、内容区域、侧边栏（如有）、底部。指定栅格结构、关键断点的响应式行为。]

#### 整页提示词
> [完整页面的详细文生图提示词。引用步骤 4 中定义的组件名称。描述空间关系、视觉层次、内容流、关键交互。如适用包含移动端/平板的响应式说明。]

#### 关键交互
- [交互 1 — 如"点击表格行打开右侧详情面板"]
- [交互 2 — 如"表单失焦验证，显示行内错误"]

#### 响应式行为
- **桌面 (>= 1024px)**：[布局描述]
- **平板 (768-1023px)**：[布局变化]
- **移动 (< 768px)**：[布局变化]

步骤 6：展示并审批 UCD

非简单项目逐节展示：

1. 视觉风格方向 — 调性、色彩倾向、排版方向
2. 风格 Token — 颜色调色板、排版比例、间距、图标
3. 组件提示词 — 展示一两个代表性组件供审批，然后再生成其余
4. 页面提示词 — 关键页面供审批

逐节展示。等待用户反馈。整合变更后再进入下一节。

简单项目（< 3 个 UI 页面）：合并所有章节为单次审批步骤。

步骤 7：保存 UCD 文档

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

文档结构：

# <项目名> — UCD 风格指南

**日期**：YYYY-MM-DD
**状态**：已审批
**概要引用**：docs/changes/<change-id>/brief.md

## 1. 视觉风格方向
[选定风格，理由]

## 2. 风格 Token
### 2.1 颜色调色板
### 2.2 排版比例
### 2.3 间距与布局
### 2.4 图标与图像

## 3. 组件提示词
### 3.1 [组件名]
...

## 4. 页面提示词
### 4.1 [页面名]
...

## 5. 风格规则与约束
[跨领域规则：无障碍、动效、响应式、深色模式]

步骤 8：过渡到设计

UCD 文档保存并提交后：

1. 总结设计阶段需要的关键输入：
   • 来自 SRS：功能需求、NFR、约束
   • 来自 UCD：风格 Token、组件目录、页面布局 -> 指导设计文档中的 UI/UX 章节和前端架构
2. 进入 vibeflow-design 开始设计

提示词编写规则

1. 具体，不模糊 — "8px 圆角卡片，1px solid #E5E7EB 边框，16px 内边距，白色背景带 0 2px 4px rgba(0,0,0,0.05) 阴影"胜过"一个漂亮的卡片"
2. 引用 Token，不用原始值 — 在提示词中使用 Token 名称以便设计变更传播
3. 包含空间关系 — "图标 16px，位于标签文本左侧 8px，垂直居中"
4. 描述状态，不仅是默认态 — 每个交互元素需要悬停、激活、禁用、错误状态
5. 指定响应式意图 — 组件/页面在各断点如何适配
6. 锚定 SRS 画像 — 提示词应服务于定义的用户类型

集成

调用者： 用户主动调用（可选独立入口） 依赖： docs/changes/<change-id>/brief.md（可选补读 legacy requirements.md） 链接到： vibeflow-design（UCD 审批后） 产出： docs/changes/<change-id>/ucd.md

注意： UCD 已并入 vibeflow-design 的步骤 1。如通过 vibeflow-design 进入设计流程，UCD 会自动在内联生成，无需先运行此 skill。 此 skill 作为可选独立入口保留——当用户想单独生成 UCD 再合并到设计时使用。