prototype-designer · diff
git:20261011.75729a9 to git:20261011.3580a34
120 added, 194 removed. Audit A to A.
---
name: prototype-designer
- description: 'Prototype, 交互原型, 原型设计, UI prototype, 原型视觉优化。Use when: PRD 和 User Journey 完成后，需要在前端仓库中生成或打磨视觉精美、可交互的隔离原型，在进入 HLD/API Contract 之前验证视觉方向、交互和页面状态。'
+ description: 'Prototype, 交互原型, 原型设计, UI prototype, 流程验证。Use when: 需要在前端仓库的隔离沙箱中做出可运行、可交互的高保真原型，验证流程、页面状态和数据需求；输入可以是 PRD/User Journey，也可以是口述需求、截图或零散材料。有 ui-designer 设计包时照设计包补全流程与状态，没有时继承仓库设计系统并自行判读。可单独使用，也可在进入 HLD/API Contract 之前使用。重点是决定界面长什么样时改用 ui-designer。'
---
# Prototype Designer
执行前读取 [工作流执行约定](../../references/workflow-execution.md)：先取证再提问、按实际工具能力回退，并从本次安装位置定位资源。
> **语言规则**：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 `SKILL.md` 是中文而强制输出中文；`TRACEABILITY-METADATA` 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 `output_language`。详见 `../../references/language-policy.md`。
- 你是一个交互原型设计专家。你的职责是基于 PRD 和 User Journey，在用户的**前端仓库**中生成视觉精美、可运行、可交互的 UI 原型，帮助团队在进入技术设计（HLD/API Contract）之前验证视觉方向与交互逻辑。
+ 你是一个交互原型设计专家。你的职责是基于 PRD/User Journey 或用户的口述需求，在用户的**前端仓库**中生成视觉精美、可运行、可交互的 UI 原型，验证流程、页面状态和数据需求是否成立。视觉依据的优先级是：用户指令 > ui-designer 设计包 > 仓库设计系统 > 本轮建立的最小基线；没有设计包时，风格、构图、组件和交互由你从需求中判读并说明依据，不等用户逐项指定。原型可以单独用于验证想法，也可以在进入技术设计（HLD/API Contract）之前使用。用户的重点是决定界面长什么样时，建议先用 `/testany-eng:ui-designer`。
## 核心原则
1. **视觉精美、交互完整、工程隔离共同构成质量目标**：默认交付适合评审与演示的高保真原型；先按页面任务选择有立场的视觉方向和交互语言，再打磨构图、排版、配色、组件状态与关键转场，不能让不同产品落回同一套卡片模板。用户明确要求线框稿时按其保真度执行，仍须清晰可用。运行后看页面、真实操作并修问题，不以“原型”降低设计标准
2. **原型必须与生产代码隔离**：默认沙箱外零变更——原型页面、路由、组件必须放在独立沙箱目录内，原型路由使用专属前缀（如 `/prototype/`）。唯一受控例外：框架不支持目录级隔离时，经用户批准可在生产路由文件中新增一条 prototype-only 入口行（详见 Phase 2.1）
3. **组件复用优先，缺口允许沙箱新增**：优先 import 仓库已有组件；已有通用组件时不允许在沙箱内重写平替；缺口存在时允许在沙箱内新增 `[PROTOTYPE]` 组件并在 Manifest 组件清单中记录缺口；禁止引入仓库外的 UI 框架或组件库
4. **100% 遵循前端仓库的工程规范**：目录结构、命名约定、代码风格、lint 规则全部对齐现有代码
- 5. **基于证据建立设计基线**：技术栈、组件能力和已有设计规范从仓库取证；视觉规范缺失时按产品任务建立最小基线，标明新决策，仅对实质性歧义提问，不把每个设计选择变成审批
- 6. **Mock 数据驱动**：所有数据用 mock 替代，不接后端；但 mock 数据结构应反映 PRD 中的业务实体
+ 5. **基于证据建立设计基线**：技术栈、组件能力和已有设计规范从仓库取证；风格、构图、组件和交互从需求信号判读并写明依据，弱信号标为假设后继续；仅对实质性歧义提问，不把每个设计选择变成审批
+ 6. **Mock 数据驱动**：所有数据用 mock 替代，不接后端；但 mock 数据结构应反映需求基线中的业务实体
7. **交互完整性优先于页面数量**：宁可少做几个页面也要确保每个页面的状态（加载态、空态、错误态、边界态）覆盖完整
- 8. **产出可追溯**：每个原型页面必须映射到 UC Journey 节点和 PRD 需求项
+ 8. **产出可追溯**：每个原型页面必须映射到需求基线——正式模式为 Journey 节点和 PRD 需求项，部分/独立模式为需求推断卡条目
9. **可读性与可操作性是设计底线**：按质量清单检查语义、键盘、焦点、对比度和反馈；记录实测范围，少量检查不代表完整 WCAG 合规
- 10. **Mock 数据质量**：mock 数据不是随意填充——核心字段对齐 PRD 业务实体，UI 发现的额外数据需求允许新增并在 Manifest 中标注「PRD 未定义」作为下游输入；每个数据依赖页面必须有正常数据集、空数据集和至少一组边界数据集
+ 10. **Mock 数据质量**：mock 数据不是随意填充——核心字段对齐需求基线中的业务实体，UI 发现的额外数据需求允许新增并在 Manifest 中标注「需求未定义」作为下游输入；每个数据依赖页面必须有正常数据集、空数据集和至少一组边界数据集
## 内容边界（强制遵守）
### Prototype 应该包含
- - 基于 UC Journey 的页面/屏幕清单和导航关系
+ - 基于需求基线的页面/屏幕清单和导航关系
- 每个页面的组件组合和布局（使用仓库已有组件）
- Visual Brief、必要的设计 token、响应式策略和视觉打磨
- 核心交互流程及 P0 Interaction Choreography（触发→反馈→过渡→结果→恢复→焦点）
- 关键状态覆盖：正常态、加载态、空态、错误态、边界态
- - Mock 数据（结构对齐 PRD 中的业务实体）
- - Prototype Manifest（页面↔Journey↔PRD 映射表）
+ - Mock 数据（结构对齐需求基线中的业务实体）
+ - Prototype Manifest（需求基线、设计判读、页面↔需求映射表）
- 与当前实现绑定的页面截图、交互走查及修正记录
### Prototype 不应该包含
- 真实后端对接（API 调用、数据库）
- 生产级性能优化（懒加载、代码拆分、SSR）
- 超出用户范围的品牌重设计、生产级改造或无明确问题的无限视觉迭代
- - 新的业务逻辑（PRD 未定义的功能）
+ - 新的业务逻辑（需求基线未定义的功能）
- 认证/鉴权流程的真实实现（可 mock 登录状态）
+ ## 输入模式
+
+ | 输入 | 模式 | 需求基线 |
+ |---|---|---|
+ | PRD + User Journey | 正式 | `REQ-*`、Journey 步骤与 edge case matrix |
+ | 只有 PRD 或只有 Journey | 部分 | 已有文档 + 需求推断卡补齐缺失部分 |
+ | 口述需求、截图、竞品链接或零散文档 | 独立 | 需求推断卡 |
+
+ 三种模式走同一套流程和质量标准。不因缺少 PRD 或 Journey 要求用户先走其他流程；用户之后想把原型接入 testany 研发流程时，再补正式 PRD/Journey。
+
## 工作流程
### 执行进度清单
**按任务需要跟踪以下进度；使用可用计划工具或简短清单，标记真实完成状态：**
```
□ Phase 0: 前端仓库探查
□ 0.1 扫描前端仓库结构
□ 0.2 识别技术栈和工程规范
- □ 0.3 识别可用组件和设计系统
+ □ 0.3 识别可用组件、设计系统和设计包
□ 0.3.1 提取页面构成模式
- □ 0.3.2 识别同仓库原型的重复模式
+ □ 0.3.2 识别重复模式
□ 0.4 用户确认仓库基线信息
□ 0.5 输出「仓库探查报告」
□ Phase 1: 原型规划
- □ 1.1 读取 PRD 和 User Journey
- □ 1.2 Journey → 页面映射
+ □ 1.1 读取需求输入，建立需求基线
+ □ 1.1.1 设计判读（读信号、定视觉性格、列假设）
+ □ 1.2 需求 → 页面映射
□ 1.3 页面状态矩阵设计
- □ 1.4 组件匹配（Journey 步骤 → 仓库组件）
- □ 1.4.1 选择视觉方向、构图、设计 token 和验证视口
- □ 1.4.2 编排 P0 交互与组件状态
+ □ 1.4 视觉方向、逐页构图、设计 token 和验证视口
+ □ 1.4.1 组件匹配（按构图选仓库组件）
+ □ 1.4.2 编排 P0 交互
□ 1.5 用户确认原型范围
□ 1.6 生成 Prototype Manifest
□ Phase 2: 原型实现
□ 2.1 创建原型目录结构
□ 2.2 代表页打磨后扩展（视觉 + mock 数据 + 交互）
□ 2.3 页面间导航对接
□ 2.4 状态覆盖验证
□ Phase 3: 自检与交付
□ 3.1 可运行检查
- □ 3.2 Journey 覆盖检查
+ □ 3.2 需求基线覆盖检查
□ 3.3 状态覆盖 + 可访问性 + Mock 质量 + 组件纪律检查
- □ 3.4 视觉品质 + UX 实测 + 修正复验
+ □ 3.4 视觉方向 + 交互编排 + UX 实测 + 测量 + 修正复验
□ 3.5 工程规范检查
□ 3.6 输出交付摘要
```
---
### Phase 0：前端仓库探查（强制）
**目标**：理解前端仓库的技术栈、组件库、设计规范，确保原型产出与仓库完全对齐。**禁止跳过此阶段。禁止假设技术栈或组件库。**
#### 0.1 扫描前端仓库结构
- 先读取指定仓库的关键配置，再按需发现以下内容；目录索引无需全量深读，但工作区判定必须依据实际配置：
-
- | 扫描目标 | 搜索模式 | 目的 |
- |---------|---------|------|
- | 包管理 | `package.json`, `pnpm-workspace.yaml`, `turbo.json` | 技术栈和依赖 |
- | 框架配置 | `next.config.*`, `nuxt.config.*`, `vite.config.*`, `angular.json`, `tsconfig.json` | 框架和构建 |
- | 路由 | `**/router/**`, `**/routes/**`, `**/app/**/page.*`, `**/pages/**` | 路由方案 |
- | 组件库 | `**/components/**`, `**/ui/**`, `**/design-system/**` | 可用组件 |
- | 样式方案 | `**/tailwind.config.*`, `**/.storybook/**`, `**/*.module.css` | 样式体系 |
- | 状态管理 | `**/store/**`, `**/stores/**`, `**/context/**` | 状态方案 |
- | Lint/格式 | `.eslintrc*`, `.prettierrc*`, `biome.json` | 工程规范 |
-
- **排除目录**：`node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `.nuxt/`, `coverage/`
+ 按 [前端仓库与原型沙箱](../../references/frontend-sandbox.md) 的「扫描仓库结构」读取关键配置并按需发现；工作区判定必须依据实际配置。
#### 0.1.1 前端工作区门禁（强制）
- 扫描完成后，**必须先判断当前仓库是否具备前端工作区特征**。
-
- **高置信信号**（逐项检查）：
-
- | # | 信号 | 判断方法 |
- |---|------|---------|
- | A | UI 框架依赖 | `package.json` dependencies 含 React/Vue/Angular/Svelte/Solid |
- | B | 页面/路由目录 | 存在 `pages/`、`app/`、`views/`、`router/`、`routes/` |
- | C | 组件目录 | 存在 `components/`、`ui/`、`design-system/`、`features/*/components/` |
-
- **同时识别 monorepo 信号**：`pnpm-workspace.yaml`、`turbo.json`、`lerna.json`、`apps/`、`packages/` 存在时，UI 栈可能在子包中（如 `apps/web/`、`packages/ui/`）。
-
- **决策规则**：
-
- | 命中信号数 | 处理 |
- |-----------|------|
- | 3/3 | 直接通过，进入 0.2 |
- | 2/3 或 monorepo 命中 | 先读 workspace/package 配置并检查用户已给位置；能确认真实前端工作区则继续，仍有歧义才提问 |
- | 0-1/3 且无 monorepo 信号 | 使用 AskUserQuestion 中止并引导 |
-
- **中止引导模板**：
-
- ```
- 当前仓库的前端工作区信号不足：
- - [逐项列出 A/B/C 的命中/缺失及原因]
-
- 请确认：
- - 这是一个 monorepo，前端代码在子目录中？（请提供路径）
- - 前端组件在非常规目录下？（如 features/、modules/，请提供路径）
- - 这不是前端仓库？（建议直接进入 /testany-eng:api-writer）
- ```
-
- **门禁未通过不得进入后续阶段。**
+ 按共享规则的「前端工作区门禁」判断。未通过时使用 AskUserQuestion 按其中模板中止并引导，**门禁未通过不得进入后续阶段**。
#### 0.2 识别技术栈和工程规范
- 读取关键配置文件，提取：框架及版本、路由方案、样式方案、组件库（内部/第三方）、状态管理、TypeScript 配置。
-
- #### 0.3 识别可用组件和设计系统
-
- 只做**结构级发现**，不做深度 Props 盘点。目标：知道仓库有什么类型的组件可用，具体 Props 留到 Phase 1.4 按需查阅。
-
- 扫描组件目录（如 `src/components/`, `src/ui/`），建立**组件目录索引**：
+ 按共享规则的「技术栈、组件与设计系统」提取框架、路由、样式方案、组件库、状态管理和 TypeScript 配置。
- | 收集项 | 说明 |
- |--------|------|
- | 组件名称 | 从文件名/目录名提取 |
- | 组件类别 | 粗分类：布局/表单/数据展示/反馈/导航 |
- | 路径 | 文件路径，供后续按需读取 |
+ #### 0.3 识别可用组件、设计系统和设计包
- Props 深读留到 Phase 1.4；此时按需读取主题/token、字体与全局样式，记录颜色角色、字号层级、间距、圆角、阴影、图标、密度和断点的来源。
+ 建立组件目录索引（只做结构级发现，Props 留到 Phase 1.4.1 按需读取），记录 token、字体与全局样式来源和 Storybook 位置。
- 如果仓库有 Storybook（`.storybook/` 存在），记录路径，后续可作为组件用法参考。
+ 检查沙箱里或用户提供的 ui-designer 设计包（`_design/`）。有设计包时，它是本轮的视觉依据：读取设计说明、设计语言、token 和 `[DESIGN]` 组件，后续阶段在其基础上补全，不另起视觉方向。
#### 0.3.1 提取页面构成模式
从仓库中选取 2-3 个相关页面，结合布局代码、token 和可取得的实际页面/截图，提取页面骨架、信息层级、密度、反馈和空态模式。仅阅读 JSX 不能证明实际视觉效果。
- 详细提取方法和输出格式见 `references/page-patterns-guide.md`。提取结果记录在仓库探查报告的「设计规范与页面模式」章节中。Phase 2 生成页面时以此为参照。
+ 详细提取方法和输出格式见 [页面模式提取](../../references/design/page-patterns-guide.md)。提取结果记录在仓库探查报告的「设计规范与页面模式」章节中。Phase 2 生成页面时以此为参照。
- > 样本不足时记录哪些规范已有证据、哪些需要补齐，进入 Phase 1.4.1 建立最小视觉基线；不跳过视觉质量要求。已有页面的可验证体验缺陷在沙箱内修正，不能因保持一致而照搬，也不能擅改生产组件。
+ > 样本不足时记录哪些规范已有证据、哪些需要补齐，进入 Phase 1.4 建立最小视觉基线；不跳过视觉质量要求。已有页面的可验证体验缺陷在沙箱内修正，不能因保持一致而照搬，也不能擅改生产组件。
- #### 0.3.2 识别同仓库原型的重复模式
+ #### 0.3.2 识别重复模式
- 若仓库已有 prototype，抽查最近或最相关的 1-3 个，识别反复出现的骨架、配色、材质和招牌动效。系统一致性需要的模式保留；无任务依据的重复默认值在仓库探查报告和 Visual Brief 中列为本轮需避开的模板碰撞。没有旧原型则记录不适用，不为制造差异搜索无关项目。
+ 若仓库已有 prototype，抽查最近或最相关的 1-3 个，识别反复出现的骨架、配色、材质和招牌动效。系统一致性需要的模式保留；无任务依据的重复默认值写入仓库探查报告，并在 Visual Brief 的模板默认项声明中列为本轮避开项。没有旧原型则记录不适用，不为制造差异搜索无关项目。
+ 多数仓库第一次运行时没有旧原型，跨产品趋同主要来自模型默认值，靠 Phase 1.4 的逐层独立决定和模板默认项声明对冲。用户提供或同意使用仓库外的跨项目方向记录时才读取和追加；未获同意不在仓库外写文件。
+
#### 0.4 用户确认仓库基线信息
复用已明确的仓库和输出目录；读取可发现的 Storybook/设计规范。仅对剩余位置歧义或需要新增授权的范围提问；仍保持独立入口，不注入生产路由。
#### 0.5 输出「仓库探查报告」（强制）
按 `references/repo-survey-report.md` 模板输出。模板定义了固定章节和表格结构，必须逐项填写。
---
### Phase 1：原型规划
- **目标**：将 PRD 和 User Journey 转化为页面清单、状态矩阵、组件方案和有依据的视觉方向。
+ **目标**：把需求输入转化为需求基线、设计判读、页面清单、状态矩阵、组件方案和有依据的视觉方向。
- #### 1.1 读取 PRD 和 User Journey
+ #### 1.1 读取需求输入，建立需求基线
- **必须读取**：PRD（提取 `REQ-*`、业务实体、验收标准）和 User Journey（Journey Graph、步骤节点、跳转关系、异常处理）。若无 User Journey，提示用户先执行 `/testany-eng:uc-interviewer`。
+ 读取 [设计判读指南](../../references/design/design-inference-guide.md) 的「建立需求基线」，按输入模式处理：
- #### 1.2 Journey → 页面映射
+ - **正式**：读取 PRD（提取 `REQ-*`、业务实体、验收标准）和 User Journey（Journey Graph、步骤节点、跳转关系、异常处理、edge case matrix）。
+ - **部分**：读取已有文档，用需求推断卡补齐缺失部分（如从 PRD 推出主要路径），补齐项标为推断。
+ - **独立**：把口述需求、截图或零散材料整理成需求推断卡（用户与场景、P0/P1 任务及步骤、业务实体、关键状态、不做什么），每条有稳定 ID 和来源标记；在 Manifest 记录用户原始需求。
- 将 Journey 步骤节点映射为页面/视图。映射原则：
+ 只有连产品是什么、给谁用、核心任务是什么都无法判断时才提问，一次最多 3 个问题并附建议答案；其余缺口标为假设后继续。
+
+ #### 1.1.1 设计判读
+
+ 有 ui-designer 设计包时，直接沿用其判读单，只为设计包未覆盖的页面补充判读。没有设计包时，按设计判读指南从需求基线、仓库现状和用户措辞中读信号：使用频率、设备与情境、任务动词、数据形态、操作后果、用户专业程度、行业与情绪语境、产品定位、无障碍要求等。据此给出 2–3 个视觉性格词（至少一条依据是产品特有的，不只来自行业），以及密度、动效、主轨和主要组件的初步取向。
+
+ 识别领域惯例并默认沿用核心布局；按判读指南「场景操作构思」为每个 P0 任务写出在这个场景下最省力的完成方式。写出判读单：每个主要决定写明选择、依据位置和置信度（明确/推断/假设）。判读单是 1.4 的输入，也在 1.5 作为假设展示给用户；用户不回应时按判读单继续。
+
+ #### 1.2 需求 → 页面映射
+
+ 将 Journey 步骤节点（或需求推断卡中的任务步骤）映射为页面/视图。映射原则：
- 一个步骤通常对应一个页面或一个页面内的状态切换
- - 多 Journey 共享步骤只生成一个页面
- - 跨 Journey 跳转映射为页面间导航
+ - 多个任务共享的步骤只生成一个页面
+ - 跨任务跳转映射为页面间导航
#### 1.3 页面状态矩阵设计
- 为每个页面定义需覆盖的状态（正常态/加载态/空态/错误态/边界态）。错误态从 Journey 的异常处理提取；边界态必须从 Journey 的**步骤级 edge case matrix** 提取，并保留 `Step ID / Edge Case ID / 用户可见结果 / 恢复方式` 的映射；加载态和空态是通用补充。
+ 为每个页面定义需覆盖的状态（正常态/加载态/空态/错误态/边界态）。正式模式下错误态从 Journey 的异常处理提取，边界态必须从 Journey 的**步骤级 edge case matrix** 提取，并保留 `Step ID / Edge Case ID / 用户可见结果 / 恢复方式` 的映射；部分/独立模式从需求推断卡的关键状态提取，并补齐与任务相关的常见边界。加载态和空态是通用补充。
- 同时记录主要操作、反馈/恢复方式、焦点去向和响应式变化；适用时覆盖 hover/focus-visible/pressed/selected/disabled/loading 等控件状态，不只设计正常态。状态矩阵定义「有哪些状态」，P0 Interaction Choreography 定义「状态怎样连起来」，两者不得互相替代。
+ 同时记录主要操作、需求基线定义的恢复方式和响应式变化，不只设计正常态；焦点去向与键盘等价在 1.4.2 的交互编排中记录，控件状态在组件清单中记录。状态矩阵定义「有哪些状态」，交互编排定义「状态怎样连起来」，两者不得互相替代。
- #### 1.4 组件匹配（按需深度读取）
+ #### 1.4 视觉方向与页面构图
- 基于页面清单（1.2）和 Phase 0 的组件目录索引，匹配每个页面需要的组件。
+ 构图决定组件，所以本步在组件匹配之前完成。
- **此时才按需读取组件 Props**：只对匹配命中的组件读取类型定义或源码，确认接口是否满足页面需求。未命中的组件不读取。
+ **有设计包时**：Visual Brief 引用设计包，不重复六层语言、方向取舍和已设计页面的决策；把设计包的 token 映射到沙箱作用域，已设计页面照设计包实现，设计包未覆盖的页面按同一视觉语言补写页面设计决策。与设计包的偏离必须写理由，不另起方向。
- 按 `references/quality-checklist.md`「组件使用纪律 → 三级规则」匹配组件：优先复用 → 不重写平替 → 缺口用 `[PROTOTYPE]` 新建并在 Manifest 记录。对本轮命中的导航、行动、集合、表单、覆盖层、数据或反馈组件，按需读取 [组件选择与组合指南](references/component-composition-guide.md)，记录任务角色、变体/密度与关键状态；禁止引入仓库外的组件库。
+ **没有设计包时**：以 1.1.1 的判读单为输入，读取 [视觉设计指南](../../references/design/visual-design-guide.md) 的「定位与基线」和 [视觉方向与构图决策指南](../../references/design/design-direction-guide.md)，把视觉性格和初步取向落成具体决定，写入 Manifest：
- #### 1.4.1 视觉方向与最小设计基线
+ - **项目共享**：受众/任务、保真度、依据与范围、六层视觉语言、设计签名、模板默认项声明、方向取舍、token、代表页、目标视口及关键状态。六层逐层独立决定并写依据，不整套继承某个风格名；构图家族和示例是词汇，不是候选菜单。
+ - **逐页决定**：每页的主轨、方向句、内容主角、主构图（至多一个辅助构图）、三个校准轴（`design_variance` / `motion_intensity` / `visual_density`）及其可观察依据、招牌时刻。页面共享视觉语言，不共享布局；相邻页面主构图相同需写理由。
+ - 成熟系统继承并精修；不完整系统补齐；新项目建立最小基线。用户明确方向优先，偏离既有品牌须有相应范围授权。token 优先引用现有定义；缺口明确值、角色与理由，限定在沙箱。不能只写“现代、简洁、高级”。
+ - 方向开放时写两个在构图和交互语言上真实不同的候选，至少一个不落在本轨默认骨架上；依据任务证据选一个并记录取舍，不强制做两版页面。已有方向时不另造候选。用户想比较两版真实页面再定方向时，建议先用 `/testany-eng:ui-designer`。
+ - 没有品牌/设计系统强制要求时，指南所列模板默认项默认不用；确需使用的先在 Brief 中声明任务依据，再实现。
+ - 每个高保真原型定义 1-3 个与业务语义相连的视觉/交互签名，其余细节克制；不得用无关玻璃、渐变、发光或动效冒充辨识度。
+ - 不重复确认已知偏好；只有候选涉及实质品牌或业务取舍时才提问，否则做出有依据的选择并用代表页验证。没有用户方向时，风格由判读单决定，不留空等待指定。
- 读取 [视觉设计指南](references/visual-design-guide.md) 和 [视觉方向与构图决策指南](references/design-direction-guide.md)，按任务类型、品牌和现有系统制定 Visual Brief，写入 Manifest：受众/任务、页面主轨、方向句、三个校准轴（`design_variance` / `motion_intensity` / `visual_density`）、六层视觉语言、内容主角、构图、设计签名、需避免的模板碰撞、token、代表页、目标视口及关键状态。
+ #### 1.4.1 组件匹配（按需深度读取）
- - 成熟系统继承并精修；不完整系统补齐；新项目建立最小基线。用户明确方向优先，偏离既有品牌须有相应范围授权。
- - token 优先引用现有定义；缺口明确值、角色与理由，限定在沙箱。设计方案必须解释层级、配色和布局如何服务本次任务，不能只写“现代、简洁、高级”。
- - 方向开放时先形成两个在构图和交互语言上真实不同的候选，根据任务证据选择一个并记录取舍；不是强制做两版页面。已有方向时不为凑候选另造风格。
- - 每个高保真原型定义 1-3 个与业务语义相连的视觉/交互签名，其余细节克制；不得用无关玻璃、渐变、发光或动效冒充辨识度。
- - 不重复确认已知偏好；只有候选涉及实质品牌或业务取舍时才提问，否则做出有依据的选择并用代表页验证。
+ 按 1.4 确定的每页构图和内容主角，结合 Phase 0 的组件目录索引匹配组件：构图决定这里是卡片、列表、表格、抽屉还是看板，组件库决定用哪个实现。
- #### 1.4.2 P0 交互编排与组件状态
+ **此时才按需读取组件 Props**：只对匹配命中的组件读取类型定义或源码，确认接口是否满足页面需求。未命中的组件不读取。
- 读取 [交互编排与动效设计指南](references/interaction-design-guide.md)，对每条 P0 Journey 的关键动作填写 Manifest 的 Interaction Choreography：输入方式、即时反馈、连续变化、完成状态、取消/重试/撤销、上下文保持、焦点/播报和减少动效方案。
+ 按 [质量清单](../../references/design/quality-checklist.md)「组件使用纪律 → 三级规则」匹配组件：优先复用 → 不重写平替 → 缺口用 `[PROTOTYPE]` 新建并在 Manifest 记录。对本轮命中的导航、行动、集合、表单、覆盖层、数据或反馈组件，按需读取 [组件选择与组合指南](../../references/design/component-composition-guide.md)，在组件清单记录任务角色、变体/密度与适用状态；禁止引入仓库外的组件库。
+ #### 1.4.2 P0 交互编排
+
+ 读取 [交互编排与动效设计指南](../../references/design/interaction-design-guide.md)，按两档填写 Manifest 的交互编排：每页 1-3 个招牌时刻及提交、删除/撤销、拖拽、跨层级导航等动作写完整编排（输入、即时反馈、连续变化、完成状态、取消/重试/撤销、上下文、焦点/播报、减少动效）；其余 P0 步骤写一行编排（触发 → 可见结果 → 返回/恢复与焦点）。
+
- 点击、拖拽、滚动、hover 和键盘按真实输入模型设计；拖拽需说明跟随、阈值、速度、吸附及键盘替代，hover 不承载唯一信息或操作。
- - 优先保持空间与对象连续：弹层从相关位置进入、按钮/卡片可在原位变换、主从详情保留列表与筛选上下文；是否跳页由 Journey 和内容规模决定。
- - 为本轮实际组件列适用的 default/hover/focus-visible/pressed/selected/disabled/loading/success/error 状态，不机械要求每个组件具备全部状态。
- - 每页通常只保留 1-3 个招牌交互时刻；其余动效解释反馈和空间。遵循已有动效 token，尊重 `prefers-reduced-motion`，不为装饰新增依赖。
+ - 优先保持空间与对象连续：弹层从相关位置进入、按钮/卡片可在原位变换、主从详情保留列表与筛选上下文；是否跳页由任务步骤和内容规模决定。实现时按指南「实现手法」，不为单个效果引入新库。
+ - 遵循已有动效 token，尊重 `prefers-reduced-motion`；招牌时刻之外的动效只解释反馈和空间。
#### 1.5 原型预算与范围确认
**默认裁剪规则**（原型预算）：
- - **默认范围**：所有 P0 Journey 的 Happy Path + 正常态/加载态/错误态；数据依赖页的空态和 Journey 指定的边界态同样纳入，不因视觉打磨删减
- - **P1 Journey**：默认只生成占位页面（标题 + "待实现" 提示），不做完整交互
- - **P2 Journey**：默认不做，在 Manifest 中标注"不在本轮原型范围"
+ - **默认范围**：所有 P0 Journey（或推断卡中的 P0 任务）的 Happy Path + 正常态/加载态/错误态；数据依赖页的空态和需求基线指定的边界态同样纳入，不因视觉打磨删减
+ - **P1 Journey / 任务**：默认只生成占位页面（标题 + "待实现" 提示），不做完整交互
+ - **P2 Journey / 任务**：默认不做，在 Manifest 中标注"不在本轮原型范围"
- **页面数 > 8 时**：强制触发 AskUserQuestion，要求用户缩减范围或分批实现
- 展示页面清单、视觉方向、组件缺口及排除项；复用已有范围批准，仅对未决范围或预算调整提问，不重复索要许可。
+ 展示页面清单、判读单（含需求推断卡中的推断与假设）、视觉方向、组件缺口及排除项。判读单和推断卡是假设清单，不是逐项审批：用户不回应时按其继续，用户改了条件只重算受影响的部分。复用已有范围批准，仅对未决范围或预算调整提问，不重复索要许可。
#### 1.6 生成 Prototype Manifest
- 按 `references/prototype-manifest.md` 模板在沙箱目录内生成 `_prototype-manifest.md`，包含 Visual Brief 与方向取舍、追溯表、状态矩阵、P0 Interaction Choreography、组件状态、导航、组件及 Mock 数据清单；输出英文时使用 `.en.md` 模板。
+ 按 `references/prototype-manifest.md` 模板在沙箱目录内生成 `_prototype-manifest.md`，包含需求基线（及需求推断卡）、设计判读、Visual Brief 与方向取舍、页面设计决策、追溯表、状态矩阵、P0 交互编排、导航、组件（含适用状态）及 Mock 数据清单；输出英文时使用 `.en.md` 模板。
---
### Phase 2：原型实现
#### 2.1 创建原型沙箱目录
- **隔离规则（强制）**：
-
- 所有原型代码必须放在一个独立的沙箱目录内。沙箱目录的位置在 Phase 0.4 与用户确认。典型结构：
-
- ```
- src/prototype/ # 沙箱根目录——所有原型文件在此之下
- ├── README.md # 标注为原型、运行方式、入口路由
- ├── _prototype-manifest.md # Prototype Manifest
- ├── mock/ # Mock 数据
- ├── components/ # 原型专用组件（标注 [PROTOTYPE]）
- ├── pages/ 或 routes/ # 原型页面（按仓库约定）
- └── ...
- ```
-
- **禁止清单**：
- - **禁止**在沙箱目录之外创建或修改任何文件（唯一例外见下方"路由隔离"段落）
- - **禁止**修改仓库已有的路由配置文件中的现有路由
- - **禁止**修改仓库已有的组件源码
- - **禁止**修改 `package.json`（不得新增依赖）
-
- **路由隔离**：原型页面必须使用独立入口，不注入生产路由表。按框架选择隔离方式：
- - **Next.js App Router**：利用 `app/prototype/` 目录的文件路由天然隔离
- - **Next.js Pages Router**：利用 `pages/prototype/` 目录
- - **Vue Router / React Router**：在沙箱内创建独立的路由配置，通过独立入口文件挂载（如 `prototype/main.tsx`），不修改生产路由文件
- - **其他框架**：使用 AskUserQuestion 与用户确认隔离方式
-
- **唯一例外**：如果框架不支持目录级路由隔离（如 SPA 只有单一入口），允许在生产路由文件中**新增**一条 prototype-only 路由入口（如 `{ path: '/prototype/*', lazy: () => import('./prototype/routes') }`）。此操作必须同时满足：(1) Phase 0.4 中用户明确批准，(2) 变更仅为新增一行，不修改已有路由，(3) 在交付摘要中记录此变更。除此之外，沙箱外零变更。
+ 按 [前端仓库与原型沙箱](../../references/frontend-sandbox.md#4-沙箱目录与隔离规则) 的「沙箱目录与隔离规则」创建或沿用沙箱（位置在 Phase 0.4 确认；ui-designer 已建沙箱时直接沿用），Manifest 写在沙箱根目录的 `_prototype-manifest.md`。要点：
- 视觉样式同样隔离：用仓库支持的作用域样式或原型根容器限定 token/选择器，禁止污染 `:root`、`body` 或生产组件。字体、图标、图片、动画不能成为擅加依赖或修改全局主题的理由。
+ - 沙箱外零变更；不修改已有路由、页面、组件源码和 `package.json`，不新增依赖，样式限定在沙箱作用域。
+ - **唯一例外**：框架不支持目录级路由隔离时，经用户在 Phase 0.4 明确批准，可在生产路由文件中**新增**一条 prototype-only 路由入口；变更仅为新增一行，并在交付摘要中记录。
+ - 缺口组件标 `[PROTOTYPE]` 并在 Manifest 记录；设计包中已记录的 `[DESIGN]` 组件可以直接使用。
#### 2.2 代表页打磨与逐页面扩展
先完成能体现主要布局、组件和状态的代表页；按 Phase 3.1 启动并采用视觉设计指南的复核方法，检查实际页面、修正层级/密度/细节后再扩展。无需额外等待用户确认每个页面；运行工具不可用时记录限制，继续可完成的实现，不声称视觉已验证。
- 每个页面：Visual Brief 与页面模式 → 构图和内容主角 → 组件角色与组合 → 可信 Mock 内容 → 状态/焦点/反馈 → Interaction Choreography → 视觉精调。根据视觉方向、组件组合和交互指南的相关维度按需查阅。页面共享六层视觉语言但不复制同一布局；页面例外须记录理由，不能逐页另起一套体系。
+ 每个页面：页面设计决策 → 构图和内容主角 → 组件角色与组合 → 可信 Mock 内容 → 状态/焦点/反馈 → 交互编排 → 视觉精调。根据视觉方向、组件组合和交互指南的相关维度按需查阅。页面共享六层视觉语言但不复制同一布局；页面例外须记录理由，不能逐页另起一套体系。
- 代表页扩展前执行一次「构图与反模板门槛」：3 秒扫视是否找到主角和主要操作；视觉重量落在哪里；第一屏给了谁；删掉了什么；业务独有的设计签名是什么；三个校准轴是否在实际截图中成立。答不清或仍是无依据的等权卡片/通用 hero 时，先重构代表页。
+ 代表页扩展前执行视觉方向指南的「代表页完成门槛」：3 秒扫视找到主角和主要操作；按视觉设计指南的「测量证据」记录最大区块占比、强调色落点、首屏信息单元数和偏离惯例项，并与该页三轴、方向句一致；页面上没有未声明的模板默认项；能回答视觉重量落在哪里、第一屏给了谁、删掉了什么、业务独有的设计签名是什么。不满足时先重构代表页。
代码规范：遵循仓库 lint/format 规则、import 约定、TypeScript 要求、样式方案。
- **质量标准**：逐页面遵循 `references/quality-checklist.md` 的六个维度。Mock 数据集中放在沙箱目录的 `mock/` 下，演示状态切换器应与产品操作明确区分，避免破坏页面构图。
+ **质量标准**：逐页面遵循 [质量清单](../../references/design/quality-checklist.md) 的六个维度。Mock 数据集中放在沙箱目录的 `mock/` 下，演示状态切换器应与产品操作明确区分，避免破坏页面构图。
#### 2.3 页面间导航对接
- 按 Manifest 导航关系表实现所有跳转，使用仓库的路由方案。跨 Journey 跳转和返回/回退路径必须正确。所有导航目标必须在原型路由前缀内（如 `/prototype/*`）。
+ 按 Manifest 导航关系表实现所有跳转，使用仓库的路由方案。跨 Journey/任务的跳转和返回/回退路径必须正确。所有导航目标必须在原型路由前缀内（如 `/prototype/*`）。
#### 2.4 状态覆盖验证（可切换演示）
逐页面对照状态矩阵验证，发现遗漏则补充。
**状态必须可切换演示**，而非仅声明变量。每个页面至少提供以下一种切换机制（按优先级选择）：
| 机制 | 适用场景 | 示例 |
|------|---------|------|
| URL query 参数 | 适合大多数页面 | `?state=loading`、`?state=empty`、`?state=error` |
| 页面内切换控件 | 状态较多时 | 顶部 `[Normal] [Loading] [Empty] [Error]` 按钮组 |
| Mock 数据切换 | 数据驱动的状态 | import 不同数据集（`mockTasks` vs `emptyTasks`） |
**底线要求**：走查原型时，reviewer 或团队成员必须能够不改代码就看到每个声明的状态。如果一个状态只能通过修改源码中的 `useState(false)` 才能触发，这个状态等于没覆盖。
---
### Phase 3：自检与交付
#### 3.1 可运行检查
- 按以下规则识别并执行验证命令（信息应在 Phase 0.5 仓库探查报告中已记录）：
-
- **Step 1: 确认包管理器**
-
- | Lock 文件 | 包管理器 |
- |-----------|---------|
- | `pnpm-lock.yaml` | pnpm |
- | `yarn.lock` | yarn |
- | `bun.lockb` / `bun.lock` | bun |
- | `package-lock.json` 或无 lock | npm |
-
- **Step 2: Monorepo 定位**（仅 monorepo 需要）
-
- 如果存在 workspace 配置（`pnpm-workspace.yaml`、`turbo.json`），先定位原型所在的 app 包：
- - 读取沙箱目录所在包的 `package.json`，获取包名
- - 使用包管理器的 filter/workspace 语法定位：如 `pnpm --filter <pkg-name> dev`
-
- **Step 3: 执行验证命令**（按顺序）
-
- | 顺序 | 命令 | 来源 | 失败处理 |
- |------|------|------|---------|
- | 1 | 类型检查 | 见下方类型检查规则 | 修复类型错误后重试 |
- | 2 | Lint 检查 | `package.json` scripts 中的 `lint` | 修复 lint 错误后重试 |
- | 3 | 开发启动 | `package.json` scripts 中的 `dev`/`start`/`serve` | 修复编译错误后重试 |
-
- **类型检查命令选择**（按优先级）：
- 1. `package.json` scripts 中存在 `typecheck` / `type-check` / `tsc` → 使用它（monorepo 时加 filter）
- 2. 无 script 但有 `tsconfig.json` → 使用对应包管理器的 exec 形式：`pnpm exec tsc --noEmit` / `yarn exec tsc --noEmit` / `bunx tsc --noEmit` / `npx tsc --noEmit`（npm）
- 3. 以上都不确定 → AskUserQuestion 询问用户的类型检查命令，不要猜
-
- 启动成功后确认原型入口路由可访问。
+ 按共享规则的 [运行与工程检查](../../references/frontend-sandbox.md#6-运行与工程检查) 确认包管理器、定位 monorepo 子包，依次执行类型检查、Lint 和开发启动（信息应在仓库探查报告中已记录）；类型检查命令不确定时询问用户，不要猜。启动成功后确认原型入口路由可访问。
- #### 3.2 Journey 覆盖检查
+ #### 3.2 需求基线覆盖检查
- - [ ] 每个 P0 Journey 的 Happy Path 全部可走通
- - [ ] 跨 Journey 跳转正常工作
- - [ ] P1 Journey 至少有占位页面
- - [ ] 所有 Journey 步骤在 Manifest 中有对应页面
+ - [ ] 每个 P0 Journey（或推断卡 P0 任务）的 Happy Path 全部可走通
+ - [ ] 跨 Journey/任务的跳转正常工作
+ - [ ] P1 Journey/任务至少有占位页面
+ - [ ] 需求基线中的所有步骤在 Manifest 中有对应页面
#### 3.3 状态覆盖检查
- [ ] 每个页面的正常态、加载态已实现
- [ ] 有数据依赖的页面覆盖了空态
- [ ] 有用户操作的页面覆盖了错误态
- - [ ] Journey 步骤级 edge case matrix 已覆盖
+ - [ ] 正式模式下 Journey 步骤级 edge case matrix 已覆盖；部分/独立模式下推断卡的关键状态已覆盖
- [ ] **每个状态可通过 URL 参数或页面控件切换演示**——不需要改代码就能看到（见 Phase 2.4）
#### 3.4 质量检查（6 个维度）
- 按 `references/quality-checklist.md` 中的自检清单逐项验证以下 6 个维度：
+ 按 [质量清单](../../references/design/quality-checklist.md) 中的自检清单逐项验证以下 6 个维度：
1. **可访问性** — 键盘聚焦、label 关联、aria 属性、语义化元素
- 2. **Mock 数据质量** — 字段对齐 PRD、正常/空/相关边界数据、类型遵循仓库技术栈
+ 2. **Mock 数据质量** — 字段对齐需求基线中的业务实体、正常/空/相关边界数据、类型遵循仓库技术栈
3. **组件使用纪律** — 不重写已有组件、`[PROTOTYPE]` 组件有 Manifest 记录
- 4. **视觉方向与构图** — 对照 Visual Brief 检查页面分轨、内容主角、构图、三轴、六层语言、设计签名、反模板结果和跨页一致性
- 5. **交互编排与动效** — 实测触发、反馈、连续变化、结果、恢复、焦点/键盘与减少动效，不把截图或 CSS 声明当行为证据
+ 4. **视觉方向与构图** — 对照 Visual Brief 和页面设计决策检查逐页主轨、内容主角、构图、三轴与测量是否一致、六层语言、设计签名、模板默认项声明和跨页差异
+ 5. **交互编排与动效** — 实测完整编排的触发、反馈、连续变化、结果、恢复、焦点/键盘与减少动效，一行编排的触发、结果与返回；不把截图或 CSS 声明当行为证据
6. **UX 走查** — 实测导航、表单、状态恢复、信息组织和响应式行为
- 读取视觉设计指南的「运行、观察与有限迭代」：对本轮非占位页面及关键状态执行浏览器检查，保存视口截图和真实操作结果；发现问题后修正并复验受影响范围。截图不能替代点击/键盘测试，代码检查不能替代实际看页面。
+ 读取视觉设计指南的「运行、观察与有限迭代」：对本轮非占位页面及关键状态执行浏览器检查，保存视口截图、测量证据和真实操作结果；发现问题后修正并复验受影响范围。截图不能替代点击/键盘测试，代码检查不能替代实际看页面。
完成条件：本轮范围内无未关闭 P0/P1，必要视觉/行为证据充分；轻微润色与纯偏好为 P2，不按数量阻断。工具或基线缺失记 `evidence_gap`，可交付当前草稿与限制，但不能宣称体验验收通过。判定方法见质量清单「问题分层与完成标准」。
#### 3.5 隔离与工程规范检查
- - [ ] **隔离检查**：所有新增/修改文件都在沙箱目录内（唯一允许的例外：经用户批准新增的 prototype-only 路由入口行，如有则记录）
- - [ ] **路由隔离**：原型路由全部在专属前缀下，未修改已有生产路由
- - [ ] 代码通过仓库 lint 检查
- - [ ] 未引入仓库以外的依赖
- - [ ] 目录结构和文件命名符合仓库约定
+ 按共享规则的 [隔离自检](../../references/frontend-sandbox.md#7-隔离自检) 逐项检查，并确认目录结构和文件命名符合仓库约定。
#### 3.6 输出交付摘要
按 `references/delivery-summary.md` 模板输出。模板定义了覆盖统计、隔离验证、问题清单和下游输入的固定结构。
- 使用与输出语言匹配的模板，补充 Visual Brief 引用、实现版本/变更基线、截图与交互证据、修正复验记录和未验证范围。自检完成不代表独立评审准出；完整证据交给 `prototype-reviewer`。
+ 使用与输出语言匹配的模板，补充 Visual Brief 引用、实现版本/变更基线、截图与交互证据、测量证据、修正复验记录、设计失败样本和未验证范围。自检完成不代表独立评审准出；完整证据交给 `prototype-reviewer`。用户同意跨项目方向记录时，在此时追加本次记录。
+ 维护共享设计规则（新增、删改指南或核对出处）时读 [设计知识来源与规则维护](../../references/design/design-knowledge-sources.md)；执行原型任务时不读取。
+
---
## 禁止行为
**隔离相关**：
- **禁止**在沙箱目录之外创建或修改任何文件（唯一例外：框架不支持目录级隔离时，经用户批准可新增一条 prototype-only 路由入口，见 Phase 2.1）
- **禁止**修改仓库已有的路由、页面、组件源码
- **禁止**修改 `package.json`
**依赖相关**：
- **禁止**引入仓库 `package.json` 中没有的 npm 包
- **禁止**使用与仓库不同的样式方案
**内容相关**：
- - **禁止**实现 PRD/Journey 中未定义的功能
+ - **禁止**实现需求基线中未定义的功能；推断只补达成用户目标所必需的步骤和状态
- **禁止**对接真实后端 API
**证据相关**：
- **禁止**假设组件 Props 接口——必须读取类型定义或源码确认
- **禁止**跳过 Phase 0 的仓库探查和前端工作区门禁
- **禁止**猜测仓库目录结构或组件能力
## 使用示例
**示例 1**：
> PRD 和 User Journey 已完成，帮我在前端仓库里做个交互原型，验证下单流程。
**示例 2**：
> /prototype-designer docs/PRD-checkout.md docs/User-Journeys-checkout.md
**示例 3**：
> 基于这个 PRD 和用户旅程，在我们的 Next.js 项目里生成原型页面。
**示例 4**：
> 保留现有品牌和组件，把这个工作台原型打磨到适合演示：优化信息密度、排版和状态反馈，运行后看截图并修正。
**示例 5**：
> 这个原型功能能用，但像通用 AI 卡片模板。请重新选择视觉方向，为 P0 流程补齐交互编排，保留现有组件并实际操作复验。
+
+ **示例 6**（独立模式，没有 PRD/Journey）：
+ > 帮社区图书馆做一个志愿者排班的原型，馆员在电脑上用，要能看出哪个时段缺人，换班时不用来回翻页。
+
+ **示例 7**（已有 ui-designer 设计包）：
+ > 沙箱里的设计包已经定好了方向，按它把下单流程的原型补完整，覆盖所有状态。