23 - 产品设计契约
1. 定位
产品设计契约是体系生命周期中需求确认之后、技术方案之前的阶段，用两份文件消除产品侧和 UI 侧的不确定性：
| 文件 | 解决什么问题 | 核心内容 |
|---|---|---|
product-spec.md | 功能怎么运转 | 信息架构、用户旅程、权限矩阵、埋点规格 |
design-spec.md | 界面长什么样 | Design Token、组件规范、交互模式、组合模式 |
为什么需要这个阶段：没有这两份文件，AI 在生成 UI 代码时只能临时协商——每次会话重新猜测页面结构、路由关系、权限控制、颜色体系。多页面项目的视觉一致性和产品完整性无法保证。
2. 在生命周期中的位置
/spec → spec.md（做什么）
↓
/prd → prd.md（数据怎么建模）← 可选，中大型功能
↓
/product-design → product-spec.md + design-spec.md（怎么组织 + 怎么看）← 本阶段
↓
/plan → 技术方案（怎么建）
↓
/ui-page → 页面骨架（有规范输入，不再盲飞）
↓
美化阶段 → 有 Token 约束，多页面视觉统一与上游的关系
| 上游产出 | 本阶段如何使用 |
|---|---|
| spec.md §5 用户故事 | 展开为 product-spec 的完整用户旅程（跨页面流程图） |
| spec.md §7 数据模型 | 映射为 product-spec 的内容模型和页面间数据流 |
| spec.md §3 目标用户 | 充实 product-spec 的用户画像和权限角色 |
| spec.md §13 成功指标 | 转化为 product-spec 的埋点漏斗和北极星指标 |
| prd.md 状态机 | 映射为 product-spec 的用户状态机和权限矩阵 |
与下游的关系
| 下游环节 | 如何消费本阶段产出 |
|---|---|
| /plan | 页面注册表（→ PS:4.1）提供完整的新增页面清单和路由树，plan 据此估计工作量 |
| /ui-page | 读取 product-spec 的页面状态矩阵（→ PS:4.2）和 design-spec 的组件规范，生成符合规范的骨架代码 |
| 美化阶段 | design-spec 的 Token 系统提供确定的色值/间距/字体，不再每次临时协商 |
| /test | product-spec 的用户旅程直接转化为 E2E 测试用例 |
| /review | design-spec 的 AI 行为契约（→ DS:0.2）提供审查基准 |
3. 两份文件的协同方式
填写顺序
product-spec 先行。产品结构决定视觉需求，不能反过来：
- product-spec.md — 先定义信息架构（有哪些页面）、用户旅程（页面间怎么跳转）、页面状态矩阵（每个页面有哪些状态需要设计）
- design-spec.md — 基于 product-spec 确定的页面和状态，定义 Token 系统、组件规范、交互模式
共享组件词汇表
两份文件通过 product-spec §0.2 的共享组件词汇表对齐：
- product-spec 中写"弹出 Modal"时，指的是 design-spec §4.6 定义的完整 Modal 组件及其所有视觉规则
- 项目新增自定义组件时，必须同时在词汇表中注册
- 交叉引用约定：
→ DS:4.1指 design-spec 第 4.1 节，→ PS:3.2指 product-spec 第 3.2 节
走查闭环
product-spec §9 提供完整的走查清单，覆盖：
- 信息架构一致性（无孤立页面）
- 用户旅程完整性（入口/出口已映射）
- 页面状态覆盖率（每种类型的必需状态都已定义）
- 权限矩阵完备性（所有功能 × 所有角色）
- 跨规范一致性（组件名称、页面类型与 design-spec 对齐）
4. 项目文件约定
两份文件在项目中的位置：
project-root/
├── docs/
│ ├── product-spec.md # 产品结构契约（从模板生成）
│ ├── design-spec.md # 设计规范契约（从模板生成）
│ ├── prd/ # 工程级 PRD（已有）
│ └── ...模板来源：docs/templates/design-spec-template.md 和 docs/templates/product-spec-template.md。
通过 /product-design Skill 驱动填写流程（见 02-Skills 技能体系）。
5. 模板内容概览
product-spec-template.md（688 行）
| 章节 | 内容 | 下游消费者 |
|---|---|---|
| §0 使用说明 | 标记约定、共享词汇表、交叉引用 | 所有环节 |
| §1 产品定义 | 定位、用户画像、价值主张 | /spec 验证对齐 |
| §2 信息架构 | 站点地图、导航模型、路由规范、内容模型 | /plan, /ui-page |
| §3 用户旅程 | 首次体验、核心循环、转化付费、支线旅程、旅程衔接 | /test（E2E 用例） |
| §4 页面注册与职责 | 页面注册表、状态矩阵、页面间数据流 | /ui-page |
| §5 用户状态与权限 | 状态机、权限矩阵、权限拒绝行为 | /ui-page, /review |
| §6 通知与消息 | 通知类型、渠道、规则 | 编码实现 |
| §7 异常旅程 | 异常目录、降级策略、数据边界 | /ui-page, /test |
| §8 数据分析 | 北极星指标、漏斗、事件命名、必采属性 | 编码实现 |
| §9 走查清单 | 6 维度完整走查 | /review |
| §10 国际化 | i18n 范围和架构影响 | /plan |
design-spec-template.md（~800 行）
| 章节 | 内容 | 下游消费者 |
|---|---|---|
| §0 使用说明 | AI 行为契约（生成 UI 前的 5 项检查） | 所有 UI 生成环节 |
| §1 设计原则 | 风格关键词、约束、优先级 | 美化阶段 |
| §2 Token 系统 | 色彩、字体、间距、阴影、圆角、动效 | /ui-page, 美化阶段 |
| §3 布局系统 | 安全区、内容宽度、响应式断点、栅格 | /ui-page |
| §4 组件规范 | Button、Form、Card、Dialog、Toast 等全量状态 | /ui-page |
| §5 交互模式 | 表单验证、加载/错误/空态、手势、无障碍 | /ui-page |
| §6 组合模式 | 列表页、详情页、表单页、设置页、结果页布局 | /ui-page |
| §7 图标与图片 | 图标规范、图片比例、占位 | 美化阶段 |
| §8 文案规范 | 标题/正文/按钮文案、日期/数字格式 | 编码实现 |
| §9 设计走查 | 完整走查清单 | /review |
6. 与 Figma MCP 的关系
如果项目配置了 Figma MCP（见 doc-11 §4.3）：
- 有 Figma 设计稿：design-spec.md 的 Token 值从 Figma 提取（
get_variable_defs），模板提供结构，Figma 提供数值 - 无 Figma 设计稿：design-spec.md 的 Token 值手动填写或使用模板默认值，AI 美化时严格遵循
两种路径的共同点：design-spec.md 始终是 AI 生成 UI 代码时的唯一权威来源。Figma 是数据输入渠道，不是替代品。
关联文档：00-总体架构 | 02-Skills 技能体系 | 07-人的操作手册 | 11-UI 开发策略关联 Skill：/product-design | /ui-page | /spec关联模板：docs/templates/design-spec-template.md | docs/templates/product-spec-template.md