product-interface-spec

Files (25)

• SKILL.md
• specification-template.md · assets/
• READING_GUIDE.md · examples/
• continuation.md · examples/
• example-a-functional-design-walkthrough.md · examples/
• example-a-p02-source.md · examples/
• example-a-pattern.md · examples/
• example-a-source-excerpts.md · examples/
• example-a-source-provenance.json · examples/
• 00-scope-and-sources.md · examples/example-b-install-plan/
• 01-feature-catalog.md · examples/example-b-install-plan/
• 02-navigation-and-layout.md · examples/example-b-install-plan/
• 03-journeys-and-states.md · examples/example-b-install-plan/
• 04-surface-registry.md · examples/example-b-install-plan/
• 05-task-plan.md · examples/example-b-install-plan/
• 06-review-report.md · examples/example-b-install-plan/
• delivery.json · examples/example-b-install-plan/
• product-excerpts.md · examples/example-b-install-plan/source-snapshots/
• provenance.json · examples/example-b-install-plan/source-snapshots/
• tasks.md · examples/example-b-install-plan/source-snapshots/
• delivery-contract.md · references/
• design-workflow.md · references/
• review-checklist.md · references/
• test_validate_delivery.py · scripts/
• validate_delivery.py · scripts/

SKILL.md (first lines)

# 详细功能设计计划

产出能让产品、设计、开发和测试共同使用的规格：**用户目标 → 功能 → 页面 → 操作 → 状态变化 → 结果 → 验收证据**。页面、按钮和异常分支都应有业务归属，避免以若干正常态截图宣称完整设计。

核心交付是三条主线：**完整的功能清单与逐模块详规、走得通的交互流程、可直接接手的逐页界面结构**，再从它们推导计划任务。先读 [固定工作法](references/design-workflow.md)，按其步骤执行。不得用文件数量、JSON 校验或少量设计图代替内容深度。

## 强制交付合同

完整整理与计划请求必须先读取 [固定交付合同 v1](references/delivery-contract.md)，依次执行来源→功能→导航→流程→Surface→任务→审阅，不得自行删减阶段、合并交付文件或省略必填字段。任务计划是必交付内容。已存在的规格/任务作为唯一事实源，本技能产物提供结构化追踪视图。

按合同创建固定七份 Markdown 和 `delivery.json`；有既有文件时引用并补齐，不覆盖人工决定。读取 [固定文档模板](assets/specification-template.md)及[审阅清单](references/review-checklist.md)。最终执行 `python3 <skill>/scripts/validate_delivery.py <PACKAGE> --require-ready`，通过后才允许报告“按固定模式整理完成”。语义审阅不能由脚本通过替代，未解决阻断必须保留。

## 必须参照已有成果

首次完整整理必须读取 [示例阅读指南](examples/READING_GUIDE.md)、[示例项目A 原成果摘录](examples/example-a-source-excerpts.md)及 [示例项目A 导入参与人员贯穿示例](examples/example-a-functional-design-walkthrough.md)，按 00–06 学习从真实功能到界面、交互和任务的展开过程。[示例项目A P02 示例](examples/example-a-pattern.md)用于另一业务链对照；[示例项目B 教学包](examples/example-b-install-plan/00-scope-and-sources.md)仅在需要了解固定文件和机器索引的组织方式时参考。接续已有项目再读 [接续示例](examples/continuation.md)。不得复制示例菜单、技术栈、数量、待确认规则或审阅 pass；示例不是目标项目需求事实源。

## 确定模式与授权

- “怎么做/审查/解释”：可以在回复中给方法或只读审查，不因技能触发就创建文件。
- “整理/输出计划/写文档”：写入用户指定目录；未指定则延续项目文档组织，先报告拟交付位置。
- 已有规格：从现有产物继续，保留 ID、人工修改和执行状态。只读参考仓库用于提取方法，不迁入其业务需求或状态。
- 视觉生成、业务实现、安装工具、初始化规格体系、提交发布分别受当前授权约束；本技能不自动启动这些阶段。

## 1. 建立证据与范围

确认目标仓库、分支/工作区和适用指令，识别 OpenSpec、Spec Kit 或已有设计流程；同一变更只有一个规格事实源，不另造任务系统。按需使用现有语义索引定位实现，不为文档任务自动安装或初始化工具。

建立简短来源表：来源/位置/日期/适用版本/支持的结论/证据等级。区分用户确认、现行规格、源码事实、运行证据、目标设计、旧原型和历史完成声明。只读必要的代表文件并沿引用追溯；声称“全部审阅”必须有完整覆盖记录。

出现冲突时登记双方依据与影响。文件更晚、标题含“最终”或原型更漂亮，不足以证明覆盖了已确认决定。用户明确的新决定优先；无法确定时保留既有已确认范围，将新建议标为提案。只对影响后续工作的关键歧义提问，其余部分继续整理。

## 2. 从业务目标建立功能清单

先明确用户/角色、对象、作用域、状态、触发条件和可观察结果，再定页面。必须先写全量功能总表，再逐模块按固定工作法的十项内容展开详规；每个功能包含稳定 ID、用户目标、前置条件、输入/输出、权限范围、主路径、异常与恢复、关联页面、验收、来源和成熟度。只有模块名、功能名和优先级的表格不合格。

用已知接口核实行为；尚无实现时写目标用例，不编造命令或 API。按钮会改变业务状态时，明确提交、接纳、执行、成功、未知的区别。不能把“文件存在/进程在线/请求返回/页面提示”当成最终业务结果。

## 3. 信息架构与页面结构

区分产品端、全局外壳、业务域、导航入口、页面、局部页签和动作层。详情、向导、确认不是天然的一级菜单。写清对象上下文及切换后哪些数据/草稿保留、清除或重新校验。

每个页面说明用户要回答的问题、进入和退出路径，以及从上到下/从左到右的内容结构、主次操作、滚动区域、焦点和空/失败状态。每个主页面或结构不同的子页必须有布局分区表或文字线框，列出真实字段与操作；仅写“顶部+侧栏+内容区”不合格。使用 Mermaid 表达信息架构、跨页流程、复杂状态机；图必须引用实际页面/功能 ID，不只画抽象技术层。

不要把示例项目的固定菜单、角色、屏数、视口、抽屉宽度或视觉风格当通用规则。

## 4. 展开用户流程和交互 Surface

每条核心旅程覆盖：入口 → 前置检查 → 输入 → 预览/必要审批 → 提交 → 处理中 → 结果 → 后续去向；按业务补充取消、失败、离线、冲突、拒绝、中断和恢复。无关分支标“不适用+理由”，不机械给每个按钮增加确认。

主链图必须配逐操作转换表：起点、动作、校验、业务变化、成功/失败去向、取消/返回与数据保留。图中没有错误分支、按钮去向写“依 Registry”而未实际查明、任务执行顺序冒充用户流程，均不合格。

沿用已有编号并在机器索引中显式登记类型与父关系；新项目统一使用 `P01` 主页面、`P01-01` 子视图、`P01-A01` 动作、`P01-S01` 状态、`P01-E01` 阻断、`P01-R01` 结果、`G01` 全局交互。ID 是语义定位符，不等于必须画一张整页图。

满足业务信息结构改变、新向导步骤、独立 Drawer/Modal、权限或高风险判断、重要错误/结果时独立编号。普通分页、hover/focus、Tooltip、无业务差异的 Skeleton 放组件状态板，防止为增加数量而拆分。

每个 Surface 使用[模板](assets/specification-template.md)定义触发、前提、上下文、必需信息、主/次操作、状态转换、成功/失败去向、返回行为与验收。不能仅列“加载/错误/成功”而不说明具体内容和可执行下一步。

## 5. 跨端与设计依赖

若存在多个界面实现，先遵循用户要求确定“业务等价”或“视觉及交互一致”。要求一致时，固定共同导航、内容、资产、状态、文案和操作合同；技术组件不同不能作为任意改变界面的理由。

按交付粒度描述外壳/父页依赖：新页面建立内容结构；状态变体继承父页；抽屉/弹窗覆盖父页并保留上下文；纯跳转动作只标触发与目的地。是否需正式视觉审批遵循项目流程，不凭本技能新增强制审批。

界面验收、业务运行和平台支持分别记录。目标尺寸来自项目，不从历史示例推断。需要成对视觉验收时统一数据、字体、语言、主题、缩放、状态和尺寸，记录具体容差。

## 6. 交付与检查

完整交付固定包含合同规定的七份 Markdown 与机器索引，不按规模合并或删减。使用[模板](assets/specification-template.md)，不适用字段写具体理由；缺失信息登记 blocker，不用空模板冒充完成。正式实施任务引用已有规格体系；新设计细节若改变需求，先按项目流程更新正式规格，不形成两套冲突的事实源。

逐项执行[审阅清单](references/review-checklist.md)。结构检查验证 ID 唯一、链接存在、功能/Surface/流程相互引用和覆盖；产品审查另外检查信息充分、操作合理、权限与副作用正确，结构检查不能替代它。

最终说明文件入口、实际覆盖范围、关键设计决定、未解决项、已执行验证与尚未运行的证据。已有页面数/任务数不得自动转化为“完整产品已设计/实现”。

## 计划任务必填

从功能和 Surface 推导设计、实现和验证任务，按项目当前授权范围制定计划。每项写依赖、阶段、责任角色、输入、产物、验收和验证方法；映射原任务源中的唯一定位。除总表外，按固定工作法提供任务执行说明，明确第一屏问题、对象/导航、业务字段、父页依赖、允许变化、动作去向与状态验收（简单任务可内联）。检查全部功能/Surface 均有任务，依赖无环，无无输入产物或只有“完善页面”的空泛任务。只完成规划不得勾选实现。

From full-stack-skills/design-skills, Apache-2.0.

More from full-stack-skills/design-skills