---
name: html-prototype-build
description: Build, annotate, review, screenshot, and deliver native HTML UI prototypes with AI agents using reusable UI packs, DOM-bound product annotations, in-browser Direct Edit, browser review pins, a local authoring server, an element-to-source Inspector, and multi-state screenshots. Use when the user mentions /html-prototype-build or asks to reconstruct UI in HTML, create product annotations, edit prototype styles, review or mark DOM elements, capture prototype states, or package prototype deliverables. Works with Claude Code, Codex, Cursor, and other Agent Skills clients; do not use for generic source-code navigation, ordinary documentation, or production frontend development.
---

# HTML Prototype Build

## 快速开始

1. 根据用户材料确认原型类型与业务事实；信息不足时先询问，不猜测。
2. 生成或大改 UI 时运行 `node <skill-root>/scripts/resolve-pack.mjs --select=<preset、pattern 或 component id>`，只读取输出的最小文件闭包。
3. 按 [共享生成契约 §7](references/generation-contract.md#7-交付文件) 生成 `prototype.html + prototype/`；业务状态统一交给 `PrototypeViewers`，正式 Client Runtime 使用 Runtime 原样副本。
4. 完成后运行仓库根目录的 `npm test`；仅按任务需要启动作者服务或场景截图。

## 先判断任务

只读取当前任务对应的入口，不要一次性读取全部 references：

| 用户目标 | 必读入口 | 主要产物或工具 |
|---|---|---|
| 生成、重建或大改 UI | [UI 生成](references/ui-generation.md) | HTML 原型与按需 UI 组件 |
| 理解 Viewer、说明卡片、SVG 连线或交互闪电 | [产品说明标注](references/product-annotations.md) | snapshot + Client Runtime |
| 启动作者环境、直接编辑、编辑说明或跳转源码 | [本地作者服务](references/local-authoring.md) | `runtime/server/index.mjs` + Author Tools |
| 给页面添加评审 pin、导出 For AI | [评审打点](references/review-mark.md) | `runtime/author/tools/mark/` |
| 按页面状态批量截图 | [分组截图](references/screenshots.md) | `runtime/cli/screenshot.mjs` |
| 整理最终文件 | [交付与迭代](references/delivery.md) | 正式交付稿 |
| 交付前最终核对 | [交付复检清单](references/delivery-checklist.md) | 逐项勾选 |

生成或大改 UI 时，先读 [共享生成契约](references/generation-contract.md)；其余任务按上表入口读取，不必全量读契约。

视觉任务先经 [UI 包目录](ui/catalog.md) 选 foundation 与 provider，再用 `node <skill-root>/scripts/resolve-pack.mjs --select=<id>` 定位最小依赖闭包；UI 包共同遵守 [UI 包契约](ui/contract.md)。

`scripts/` 保存 Agent 的确定性工具。`runtime/` 按执行边界分为：`client/` 正式浏览器运行时、`author/` 浏览器作者工具、`server/` 本地 Node 作者服务、`cli/` 独立命令行工具。

## 核心边界

- 所有原型必须按顺序使用 `runtime/client/core/display-mode.js`、`runtime/client/core/state.js`、`runtime/client/notes/model.js`、`runtime/client/notes/viewer.js` 的分发副本；`state.js` 提供唯一 `PrototypeViewers` 状态源，`model.js` 只负责说明场景元数据与 `when` 纯匹配，Notes Viewer 只负责 DOM/连线渲染，禁止把这些职责重新塞回 Viewer。
- 正式说明只经 `runtime/server/index.mjs` + Notes Editor 写回 `prototype/notes.snapshot.js`；禁止在 `prototype.html` 内联标注编辑器，也禁止把正式说明写入 localStorage。
- Mark 是 Author Tools 面板中与 Direct Edit 并列的临时评审工具，数据按页面 pathname 进入 localStorage，不写入 snapshot，也不注入源 HTML。
- Direct Edit 只在作者服务环境中预览并通过服务端安全写回源 HTML。
- 作者服务只做本地编辑与原型内源码定位，不进入源 HTML 或正式交付物。
- 截图只消费 URL scene 与正式标注数据，不生成业务状态。
- 系统名、菜单、字段、状态和业务数据必须来自用户材料；信息不明确时先询问，禁止猜测。