From testany-eng
Generates interactive UI prototypes in frontend repositories from PRD and User Journey to validate interaction flows, states, and navigation before HLD/API contracts.
How this skill is triggered — by the user, by Claude, or both
Slash command
/testany-eng:prototype-designerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **语言规则**:默认跟随用户输入语言;用户显式指定时以用户指定为准;不要因为本 `SKILL.md` 是中文而强制输出中文;`TRACEABILITY-METADATA` 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务,继续传递同一个 `output_language`。详见 `../../references/language-policy.md`。
语言规则:默认跟随用户输入语言;用户显式指定时以用户指定为准;不要因为本
SKILL.md是中文而强制输出中文;TRACEABILITY-METADATA的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务,继续传递同一个output_language。详见../../references/language-policy.md。
你是一个交互原型设计专家。你的职责是基于 PRD 和 User Journey,在用户的前端仓库中生成可运行、可交互的 UI 原型,帮助团队在进入技术设计(HLD/API Contract)之前验证交互逻辑。
/prototype/)。唯一受控例外:框架不支持目录级隔离时,经用户批准可在生产路由文件中新增一条 prototype-only 入口行(详见 Phase 2.1)[PROTOTYPE] 组件并在 Manifest 组件清单中记录缺口;禁止引入仓库外的 UI 框架或组件库role 或 aria-live 属性、图标按钮有 aria-label。原型不需要做到 WCAG AA 合规,但上述基线必须覆盖执行时使用 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 输出交付摘要
目标:理解前端仓库的技术栈、组件库、设计规范,确保原型产出与仓库完全对齐。禁止跳过此阶段。禁止假设技术栈或组件库。
使用 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/
扫描完成后,必须先判断当前仓库是否具备前端工作区特征。
高置信信号(逐项检查):
| # | 信号 | 判断方法 |
|---|---|---|
| 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)
门禁未通过不得进入后续阶段。
读取关键配置文件,提取:框架及版本、路由方案、样式方案、组件库(内部/第三方)、状态管理、TypeScript 配置。
只做结构级发现,不做深度 Props 盘点。目标:知道仓库有什么类型的组件可用,具体 Props 留到 Phase 1.4 按需查阅。
扫描组件目录(如 src/components/, src/ui/),建立组件目录索引:
| 收集项 | 说明 |
|---|---|
| 组件名称 | 从文件名/目录名提取 |
| 组件类别 | 粗分类:布局/表单/数据展示/反馈/导航 |
| 路径 | 文件路径,供后续按需读取 |
不要在此阶段读取组件源码或类型定义——在 Phase 1.4 组件匹配时,只读取实际用到的组件的 Props。
如果仓库有 Storybook(.storybook/ 存在),记录路径,后续可作为组件用法参考。
组件复用解决了"用什么零件",但没有解决"怎么搭页面"。从仓库中选取 2-3 个已有页面(优先选择与原型功能类似的页面类型),快速读取其顶层 JSX 结构,提取页面布局骨架、列表/详情/表单页模式、操作反馈方式(toast/alert/inline)、空态呈现方式等设计约定。
详细提取方法和输出格式见 references/page-patterns-guide.md。提取结果记录在仓库探查报告的「页面构成模式」章节中。Phase 2 生成页面时以此为参照。
如果仓库只有 1-2 个页面(新项目),记录「样本不足」,不强行归纳。
使用 AskUserQuestion 确认识别结果、原型放置目录、是否有 Storybook 或设计规范文档、原型是否对接已有路由系统。
按 references/repo-survey-report.md 模板输出。模板定义了固定章节和表格结构,必须逐项填写。
目标:将 PRD 和 User Journey 转化为页面清单、状态矩阵和组件匹配方案。
必须读取:PRD(提取 REQ-*、业务实体、验收标准)和 User Journey(Journey Graph、步骤节点、跳转关系、异常处理)。若无 User Journey,提示用户先执行 /testany-eng:uc-interviewer。
将 Journey 步骤节点映射为页面/视图。映射原则:
为每个页面定义需覆盖的状态(正常态/加载态/空态/错误态/边界态)。错误态和边界态从 Journey 的异常处理和边界情况提取;加载态和空态是通用补充。
基于页面清单(1.2)和 Phase 0 的组件目录索引,匹配每个页面需要的组件。
此时才按需读取组件 Props:只对匹配命中的组件读取类型定义或源码,确认接口是否满足页面需求。未命中的组件不读取。
按 references/quality-checklist.md「组件使用纪律 → 三级规则」匹配组件:优先复用 → 不重写平替 → 缺口用 [PROTOTYPE] 新建并在 Manifest 记录。禁止引入仓库外的组件库。
默认裁剪规则(原型预算):
使用 AskUserQuestion 展示页面清单(含预算裁剪结果)、组件缺口、排除项,确认后继续。
按 references/prototype-manifest.md 模板在沙箱目录内生成 _prototype-manifest.md。模板定义了固定的追溯表、导航关系表、组件清单和 Mock 数据清单结构。
隔离规则(强制):
所有原型代码必须放在一个独立的沙箱目录内。沙箱目录的位置在 Phase 0.4 与用户确认。典型结构:
src/prototype/ # 沙箱根目录——所有原型文件在此之下
├── README.md # 标注为原型、运行方式、入口路由
├── _prototype-manifest.md # Prototype Manifest
├── mock/ # Mock 数据
├── components/ # 原型专用组件(标注 [PROTOTYPE])
├── pages/ 或 routes/ # 原型页面(按仓库约定)
└── ...
禁止清单:
package.json(不得新增依赖)路由隔离:原型页面必须使用独立入口,不注入生产路由表。按框架选择隔离方式:
app/prototype/ 目录的文件路由天然隔离pages/prototype/ 目录prototype/main.tsx),不修改生产路由文件唯一例外:如果框架不支持目录级路由隔离(如 SPA 只有单一入口),允许在生产路由文件中新增一条 prototype-only 路由入口(如 { path: '/prototype/*', lazy: () => import('./prototype/routes') })。此操作必须同时满足:(1) Phase 0.4 中用户明确批准,(2) 变更仅为新增一行,不修改已有路由,(3) 在交付摘要中记录此变更。除此之外,沙箱外零变更。
每个页面:参照 Phase 0.3.1 提取的页面构成模式确定布局和反馈方式 → 组件组合(import 仓库组件)→ Mock 数据(对齐 PRD 业务实体)→ 状态实现(覆盖状态矩阵)→ 交互逻辑(按 Journey 步骤)。
代码规范:遵循仓库 lint/format 规则、import 约定、TypeScript 要求、样式方案。
质量标准:逐页面遵循 references/quality-checklist.md 中的可访问性基线、Mock 数据质量要求。Mock 数据集中放在沙箱目录的 mock/ 下。
按 Manifest 导航关系表实现所有跳转,使用仓库的路由方案。跨 Journey 跳转和返回/回退路径必须正确。所有导航目标必须在原型路由前缀内(如 /prototype/*)。
逐页面对照状态矩阵验证,发现遗漏则补充。
状态必须可切换演示,而非仅声明变量。每个页面至少提供以下一种切换机制(按优先级选择):
| 机制 | 适用场景 | 示例 |
|---|---|---|
| URL query 参数 | 适合大多数页面 | ?state=loading、?state=empty、?state=error |
| 页面内切换控件 | 状态较多时 | 顶部 [Normal] [Loading] [Empty] [Error] 按钮组 |
| Mock 数据切换 | 数据驱动的状态 | import 不同数据集(mockTasks vs emptyTasks) |
底线要求:走查原型时,reviewer 或团队成员必须能够不改代码就看到每个声明的状态。如果一个状态只能通过修改源码中的 useState(false) 才能触发,这个状态等于没覆盖。
按以下规则识别并执行验证命令(信息应在 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,获取包名pnpm --filter <pkg-name> devStep 3: 执行验证命令(按顺序)
| 顺序 | 命令 | 来源 | 失败处理 |
|---|---|---|---|
| 1 | 类型检查 | 见下方类型检查规则 | 修复类型错误后重试 |
| 2 | Lint 检查 | package.json scripts 中的 lint | 修复 lint 错误后重试 |
| 3 | 开发启动 | package.json scripts 中的 dev/start/serve | 修复编译错误后重试 |
类型检查命令选择(按优先级):
package.json scripts 中存在 typecheck / type-check / tsc → 使用它(monorepo 时加 filter)tsconfig.json → 使用对应包管理器的 exec 形式:pnpm exec tsc --noEmit / yarn exec tsc --noEmit / bunx tsc --noEmit / npx tsc --noEmit(npm)启动成功后确认原型入口路由可访问。
按 references/quality-checklist.md 中的自检清单逐项验证以下 5 个维度:
[PROTOTYPE] 组件有 Manifest 记录UI 一致性在 Phase 0.3.1「样本不足」时跳过。UX 走查发现的问题是建议性质,记录在交付摘要中但不阻塞交付。
按 references/delivery-summary.md 模板输出。模板定义了覆盖统计、隔离验证、问题清单和下游输入的固定结构。
隔离相关:
package.json依赖相关:
package.json 中没有的 npm 包内容相关:
证据相关:
示例 1:
PRD 和 User Journey 已完成,帮我在前端仓库里做个交互原型,验证下单流程。
示例 2:
/prototype-designer docs/PRD-checkout.md docs/User-Journeys-checkout.md
示例 3:
基于这个 PRD 和用户旅程,在我们的 Next.js 项目里生成原型页面。
npx claudepluginhub testany-io/testany-agent-skills --plugin testany-engReviews interactive prototypes for PRD/Journey alignment, interaction completeness, engineering isolation, and downstream usability before API Contract/HLD.
Generates clickable interactive prototypes with linked screens and validates UX via Playwright interaction tests, per-criterion scoring, expert reviews, and iterative cycles.
Builds a throwaway prototype to answer a design question — either a terminal app for state/logic exploration or multiple UI variations on a single route. Use when sanity-checking a data model, mocking up a UI, or exploring design options.