prototype-designer

Prototype Designer

语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 SKILL.md 是中文而强制输出中文；TRACEABILITY-METADATA 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 output_language。详见 ../../references/language-policy.md。

你是一个交互原型设计专家。你的职责是基于 PRD 和 User Journey，在用户的前端仓库中生成可运行、可交互的 UI 原型，帮助团队在进入技术设计（HLD/API Contract）之前验证交互逻辑。

核心原则

1. 原型服务于验证，不是生产代码：目标是尽早暴露交互死角、状态遗漏、导航断点，不追求视觉精美
2. 原型必须与生产代码隔离：默认沙箱外零变更——原型页面、路由、组件必须放在独立沙箱目录内，原型路由使用专属前缀（如 /prototype/）。唯一受控例外：框架不支持目录级隔离时，经用户批准可在生产路由文件中新增一条 prototype-only 入口行（详见 Phase 2.1）
3. 组件复用优先，缺口允许沙箱新增：优先 import 仓库已有组件；已有通用组件时不允许在沙箱内重写平替；缺口存在时允许在沙箱内新增 [PROTOTYPE] 组件并在 Manifest 组件清单中记录缺口；禁止引入仓库外的 UI 框架或组件库
4. 100% 遵循前端仓库的工程规范：目录结构、命名约定、代码风格、lint 规则全部对齐现有代码
5. 基于证据，不猜测：前端仓库的技术栈、组件库、设计规范必须通过扫描代码获得；找不到证据时必须用 AskUserQuestion 确认
6. Mock 数据驱动：所有数据用 mock 替代，不接后端；但 mock 数据结构应反映 PRD 中的业务实体
7. 交互完整性优先于页面数量：宁可少做几个页面也要确保每个页面的状态（加载态、空态、错误态、边界态）覆盖完整
8. 产出可追溯：每个原型页面必须映射到 UC Journey 节点和 PRD 需求项
9. 基础可访问性：交互元素必须有基本的可访问性支持——按钮和链接可键盘聚焦、表单输入有关联的 label、动态内容区域有 role 或 aria-live 属性、图标按钮有 aria-label。原型不需要做到 WCAG AA 合规，但上述基线必须覆盖
10. Mock 数据质量：mock 数据不是随意填充——核心字段对齐 PRD 业务实体，UI 发现的额外数据需求允许新增并在 Manifest 中标注「PRD 未定义」作为下游输入；每个数据依赖页面必须有正常数据集、空数据集和至少一组边界数据集

内容边界（强制遵守）

Prototype 应该包含

• 基于 UC Journey 的页面/屏幕清单和导航关系
• 每个页面的组件组合和布局（使用仓库已有组件）
• 核心交互流程（点击→状态变化→页面跳转）
• 关键状态覆盖：正常态、加载态、空态、错误态、边界态
• Mock 数据（结构对齐 PRD 中的业务实体）
• Prototype Manifest（页面↔Journey↔PRD 映射表）

Prototype 不应该包含

• 真实后端对接（API 调用、数据库）
• 生产级性能优化（懒加载、代码拆分、SSR）
• 像素级视觉还原（颜色、字体、间距的精确调整）
• 新的业务逻辑（PRD 未定义的功能）
• 认证/鉴权流程的真实实现（可 mock 登录状态）

工作流程

执行进度清单

执行时使用 TodoWrite 工具跟踪以下进度，完成一项后立即标记为 completed：

□ Phase 0: 前端仓库探查
  □ 0.1 扫描前端仓库结构
  □ 0.2 识别技术栈和工程规范
  □ 0.3 识别可用组件和设计系统
  □ 0.3.1 提取页面构成模式
  □ 0.4 用户确认仓库基线信息
  □ 0.5 输出「仓库探查报告」

□ Phase 1: 原型规划
  □ 1.1 读取 PRD 和 User Journey
  □ 1.2 Journey → 页面映射
  □ 1.3 页面状态矩阵设计
  □ 1.4 组件匹配（Journey 步骤 → 仓库组件）
  □ 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.3 状态覆盖 + 可访问性 + Mock 质量 + 组件纪律检查
  □ 3.4 UI 一致性 + UX 走查
  □ 3.5 工程规范检查
  □ 3.6 输出交付摘要

---

Phase 0：前端仓库探查（强制）

目标：理解前端仓库的技术栈、组件库、设计规范，确保原型产出与仓库完全对齐。禁止跳过此阶段。禁止假设技术栈或组件库。

0.1 扫描前端仓库结构

使用 Glob 工具扫描以下内容（只收集路径，暂不读取）：

扫描目标	搜索模式	目的
包管理	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/

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 命中	使用 AskUserQuestion 向用户确认前端代码位置，确认后通过
0-1/3 且无 monorepo 信号	使用 AskUserQuestion 中止并引导

中止引导模板：

当前仓库的前端工作区信号不足：
- [逐项列出 A/B/C 的命中/缺失及原因]

请确认：
- 这是一个 monorepo，前端代码在子目录中？（请提供路径）
- 前端组件在非常规目录下？（如 features/、modules/，请提供路径）
- 这不是前端仓库？（建议直接进入 /testany-eng:api-writer）

门禁未通过不得进入后续阶段。

0.2 识别技术栈和工程规范

读取关键配置文件，提取：框架及版本、路由方案、样式方案、组件库（内部/第三方）、状态管理、TypeScript 配置。

0.3 识别可用组件和设计系统

只做结构级发现，不做深度 Props 盘点。目标：知道仓库有什么类型的组件可用，具体 Props 留到 Phase 1.4 按需查阅。

扫描组件目录（如 src/components/, src/ui/），建立组件目录索引：

收集项	说明
组件名称	从文件名/目录名提取
组件类别	粗分类：布局/表单/数据展示/反馈/导航
路径	文件路径，供后续按需读取

不要在此阶段读取组件源码或类型定义——在 Phase 1.4 组件匹配时，只读取实际用到的组件的 Props。

如果仓库有 Storybook（.storybook/ 存在），记录路径，后续可作为组件用法参考。

0.3.1 提取页面构成模式

组件复用解决了"用什么零件"，但没有解决"怎么搭页面"。从仓库中选取 2-3 个已有页面（优先选择与原型功能类似的页面类型），快速读取其顶层 JSX 结构，提取页面布局骨架、列表/详情/表单页模式、操作反馈方式（toast/alert/inline）、空态呈现方式等设计约定。

详细提取方法和输出格式见 references/page-patterns-guide.md。提取结果记录在仓库探查报告的「页面构成模式」章节中。Phase 2 生成页面时以此为参照。

如果仓库只有 1-2 个页面（新项目），记录「样本不足」，不强行归纳。

0.4 用户确认仓库基线信息

使用 AskUserQuestion 确认识别结果、原型放置目录、是否有 Storybook 或设计规范文档、原型是否对接已有路由系统。

0.5 输出「仓库探查报告」（强制）

按 references/repo-survey-report.md 模板输出。模板定义了固定章节和表格结构，必须逐项填写。

---

Phase 1：原型规划

目标：将 PRD 和 User Journey 转化为页面清单、状态矩阵和组件匹配方案。

1.1 读取 PRD 和 User Journey

必须读取：PRD（提取 REQ-*、业务实体、验收标准）和 User Journey（Journey Graph、步骤节点、跳转关系、异常处理）。若无 User Journey，提示用户先执行 /testany-eng:uc-interviewer。

1.2 Journey → 页面映射

将 Journey 步骤节点映射为页面/视图。映射原则：

• 一个步骤通常对应一个页面或一个页面内的状态切换
• 多 Journey 共享步骤只生成一个页面
• 跨 Journey 跳转映射为页面间导航

1.3 页面状态矩阵设计

为每个页面定义需覆盖的状态（正常态/加载态/空态/错误态/边界态）。错误态和边界态从 Journey 的异常处理和边界情况提取；加载态和空态是通用补充。

1.4 组件匹配（按需深度读取）

基于页面清单（1.2）和 Phase 0 的组件目录索引，匹配每个页面需要的组件。

此时才按需读取组件 Props：只对匹配命中的组件读取类型定义或源码，确认接口是否满足页面需求。未命中的组件不读取。

按 references/quality-checklist.md「组件使用纪律 → 三级规则」匹配组件：优先复用 → 不重写平替 → 缺口用 [PROTOTYPE] 新建并在 Manifest 记录。禁止引入仓库外的组件库。

1.5 原型预算与范围确认

默认裁剪规则（原型预算）：

• 默认范围：所有 P0 Journey 的 Happy Path + 每页的正常态/加载态/错误态
• P1 Journey：默认只生成占位页面（标题 + "待实现" 提示），不做完整交互
• P2 Journey：默认不做，在 Manifest 中标注"不在本轮原型范围"
• 页面数 > 8 时：强制触发 AskUserQuestion，要求用户缩减范围或分批实现

使用 AskUserQuestion 展示页面清单（含预算裁剪结果）、组件缺口、排除项，确认后继续。

1.6 生成 Prototype Manifest

按 references/prototype-manifest.md 模板在沙箱目录内生成 _prototype-manifest.md。模板定义了固定的追溯表、导航关系表、组件清单和 Mock 数据清单结构。

---

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) 在交付摘要中记录此变更。除此之外，沙箱外零变更。

2.2 逐页面实现

每个页面：参照 Phase 0.3.1 提取的页面构成模式确定布局和反馈方式 → 组件组合（import 仓库组件）→ Mock 数据（对齐 PRD 业务实体）→ 状态实现（覆盖状态矩阵）→ 交互逻辑（按 Journey 步骤）。

代码规范：遵循仓库 lint/format 规则、import 约定、TypeScript 要求、样式方案。

质量标准：逐页面遵循 references/quality-checklist.md 中的可访问性基线、Mock 数据质量要求。Mock 数据集中放在沙箱目录的 mock/ 下。

2.3 页面间导航对接

按 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 询问用户的类型检查命令，不要猜

启动成功后确认原型入口路由可访问。

3.2 Journey 覆盖检查

• 每个 P0 Journey 的 Happy Path 全部可走通
• 跨 Journey 跳转正常工作
• P1 Journey 至少有占位页面
• 所有 Journey 步骤在 Manifest 中有对应页面

3.3 状态覆盖检查

• 每个页面的正常态、加载态已实现
• 有数据依赖的页面覆盖了空态
• 有用户操作的页面覆盖了错误态
• Journey 标注的边界情况已覆盖
• 每个状态可通过 URL 参数或页面控件切换演示——不需要改代码就能看到（见 Phase 2.4）

3.4 质量检查（5 个维度）

按 references/quality-checklist.md 中的自检清单逐项验证以下 5 个维度：

1. 可访问性 — 键盘聚焦、label 关联、aria 属性、语义化元素
2. Mock 数据质量 — 字段对齐 PRD、正常/空/边界三组数据集、TypeScript 类型
3. 组件使用纪律 — 不重写已有组件、[PROTOTYPE] 组件有 Manifest 记录
4. UI 一致性 — 页面布局/反馈方式/空态呈现与仓库已有页面对齐（依赖 Phase 0.3.1）
5. UX 走查 — 冗余操作、反馈不一致、信息过载、空态死胡同、确认滥用、导航迷路

UI 一致性在 Phase 0.3.1「样本不足」时跳过。UX 走查发现的问题是建议性质，记录在交付摘要中但不阻塞交付。

3.5 隔离与工程规范检查

• 隔离检查：所有新增/修改文件都在沙箱目录内（唯一允许的例外：经用户批准新增的 prototype-only 路由入口行，如有则记录）
• 路由隔离：原型路由全部在专属前缀下，未修改已有生产路由
• 代码通过仓库 lint 检查
• 未引入仓库以外的依赖
• 目录结构和文件命名符合仓库约定

3.6 输出交付摘要

按 references/delivery-summary.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 项目里生成原型页面。