/product-design
产品设计契约。需求确认后、技术方案前使用。
产品设计契约
基于已确认的需求（spec.md / prd.md / 用户描述），生成两份项目级契约文件：
docs/product-spec.md— 产品结构契约（信息架构、用户旅程、权限、埋点）docs/design-spec.md— 设计规范契约（Token、组件、交互、组合模式）
红线
- MUST 基于已确认的需求源，不凭空发明页面和功能
- MUST product-spec 先于 design-spec 填写（产品结构决定视觉需求）
- MUST 共享组件词汇表（product-spec §0.2）在两份文件中保持一致
- MUST 每个页面在站点地图（§2.1）和页面注册表（§4.1）中双重登记
- MUST 页面状态矩阵（§4.2）按页面类型覆盖所有必需状态
- NEVER 自行开始编码或技术方案设计
- NEVER 跳过走查清单（product-spec §9、design-spec §9）
步骤
Step 0: 搜集上下文
并行读取：
- 需求源 —
docs/spec.md或docs/*-spec.md或docs/*-prd.md - 已有产品/设计文件 — 检查
docs/product-spec.md和docs/design-spec.md是否已存在（增量更新 vs 从零创建） - 模板 — 读取
docs/templates/product-spec-template.md和docs/templates/design-spec-template.md；如果项目docs/templates/不存在，读取~/.claude/product-spec-template.md和~/.claude/design-spec-template.md - 技术栈 — 读取 CLAUDE.md 了解项目技术栈（影响平台标记 [MP]/[WEB]）
向用户确认：
"已读取 [需求源列表]，识别出 N 个页面、M 条用户旅程、K 个用户角色。将生成 product-spec.md 和 design-spec.md。确认？"
Step 1: 生成 product-spec.md
基于需求源，按模板结构逐章填写。核心章节的填写要点：
§1 产品定义 — 从 spec.md §1-§3 提取定位、用户画像、价值主张
§2 信息架构 — 这是最关键的章节：
- 站点地图：列出所有页面及层级关系，标注访问级别
- 导航模型：主导航 + 辅助导航
- 路由规范：每个页面的路由路径和参数
- 内容模型：从 spec.md §7 或 prd.md 数据模型映射实体关系
§3 用户旅程 — 从 spec.md §5 用户故事展开为完整跨页面旅程：
- 首次体验旅程（到 Aha 时刻）
- 核心价值循环
- 转化/付费旅程
- 旅程间衔接和中断恢复
§4 页面注册与职责：
- 页面注册表：站点地图中的每个页面都必须出现
- 状态矩阵：按页面类型覆盖必需状态（列表页 7 种、详情页 4 种、表单页 3 种 + 提交流）
- 页面间数据流：传 ID 不传对象
§5 用户状态与权限 — 从 prd.md 状态机（如有）映射：
- 状态定义和转换规则
- 权限矩阵：功能 × 角色的完整映射
- 权限拒绝时的用户体验
§8 数据分析 — 从 spec.md §13 成功指标转化：
- 北极星指标
- 按旅程阶段定义漏斗和事件
- 事件命名遵循
snake_case+名词_动词规范
§0.2 共享组件词汇表 — 注册本项目使用的所有 UI 组件，与 design-spec 保持一致。
Step 2: 生成 design-spec.md
基于 product-spec 确定的页面和状态需求，按模板结构填写：
§1 设计原则 — 与用户确认风格关键词和优先级
§2 Token 系统 — 这是 design-spec 的核心：
- 色彩：主色、语义色（success/warning/error/info）、中性色阶梯
- 字体：层级（h1-h6 + body + caption）、行高、字重
- 间距：4px 基数倍数系统
- 阴影、圆角、动效持续时间
如果有 Figma 设计稿：用 get_variable_defs 提取 Token 值填入。 如果没有：使用模板默认值或与用户协商确认。
§4 组件规范 — 基于 product-spec §0.2 词汇表中注册的组件，逐一定义：
- 尺寸变体（sm/md/lg）
- 状态（default/hover/active/disabled/loading）
- 无障碍要求
§5 交互模式 — 基于 product-spec §7 异常目录：
- 表单验证（实时 vs 提交时）
- 加载/错误/空态处理
- 手势（如移动端）
§6 组合模式 — 基于 product-spec §4.1 页面类型：
- 每种页面类型的标准布局结构
- 与 product-spec 的页面类型一一对应
Step 3: 走查
依次运行两份走查清单：
product-spec §9 走查清单（6 维度）：
- 信息架构：无孤立页面、深度 ≤ 3
- 用户旅程：核心旅程完整、入口/出口已映射
- 页面状态：所有必需状态已定义
- 权限：矩阵完备
- 异常：已编目并有恢复路径
- 数据分析：事件与旅程阶段一致
design-spec §9 走查清单（如模板提供）
跨规范一致性：
- 组件名称与共享词汇表一致
- 页面类型与组合模式对应
- 错误/空/加载状态使用 design-spec 定义的组件
Step 4: 等待确认
IMPORTANT：输出后等待用户确认，不自行开始技术方案或编码。
"已生成 product-spec.md（N 个页面、M 条旅程、K 个角色、J 个埋点事件）和 design-spec.md（X 个 Token、Y 个组件规范）。走查清单全部通过。请审阅，下一步 /plan。"
Quality Gate
- [ ] 基于已确认的需求源
- [ ] product-spec 先于 design-spec 生成
- [ ] 站点地图中的每个页面都在页面注册表中登记
- [ ] 每个页面的状态矩阵按类型覆盖所有必需状态
- [ ] 权限矩阵覆盖所有功能 × 所有角色
- [ ] 每条核心旅程的每个阶段都有对应的埋点事件
- [ ] 共享组件词汇表在两份文件中一致
- [ ] 两份走查清单通过
- [ ] 用户已确认
Tips
- 小项目（< 5 页面）：design-spec 的 Token 系统可以精简，只填色彩和字体，间距/阴影用模板默认值
- 已有 Figma 设计稿：design-spec 的 Token 直接从 Figma 提取，不手工填
- 增量更新：项目迭代新增页面时，只更新受影响的章节，不重写全文
- 与 /prd 的配合：/prd 的状态机和数据模型是 product-spec 的重要输入，如果已有 prd.md 会大幅简化 §2.4 和 §5.1 的填写