git:20260909.3bef5cf to git:20260910.219f832

26 added, 26 removed. Audit A to A.

---

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

- ## 快速开始

+ ## Quick start

- 1. 根据用户材料确认原型类型与业务事实；信息不足时先询问，不猜测。

- 2. 生成或大改 UI 时运行 `node <skill-root>/scripts/resolve-pack.mjs --select=<preset、pattern 或 component id>`，只读取输出的最小文件闭包。

- 3. 按 [共享生成契约 §7](references/generation-contract.md#7-交付文件) 生成完整 `<prototype-name>/` 交付目录；业务状态统一交给 `PrototypeViewers`，正式 Client Runtime 使用 Runtime 原样副本。

- 4. 完成后运行仓库根目录的 `npm test`；仅按任务需要启动作者服务或场景截图。

+ 1. Confirm the prototype type and business facts from the user's materials; ask first when information is insufficient, do not guess.

+ 2. When generating or heavily changing UI, run `node <skill-root>/scripts/resolve-pack.mjs --select=<preset, pattern, or component id>` and read only the minimal file closure it outputs.

+ 3. Generate the complete `<prototype-name>/` delivery directory per [shared generation contract §7](references/generation-contract.md#7-交付文件); route all business state through `PrototypeViewers`, and use the Runtime copy as-is for the formal Client Runtime.

+ 4. When done, run `npm test` at the repository root; start the authoring server or scenario screenshots only when the task needs them.

- ## 先判断任务

+ ## Route the task first

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

+ Read only the entry that matches the current task; do not read all references at once:

- | 用户目标 | 必读入口 | 主要产物或工具 |

+ | User goal | Required entry | Main output or tool |

|---|---|---|

- | 生成、重建或大改 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) | 逐项勾选 |

+ | Generate, rebuild, or heavily change UI | [UI generation](references/ui-generation.md) | HTML prototype and on-demand UI components |

+ | Understand Viewer, note cards, SVG connectors, or interaction lightning | [Product annotations](references/product-annotations.md) | snapshot + Client Runtime |

+ | Start the authoring environment, direct edit, edit notes, or jump to source | [Local authoring](references/local-authoring.md) | `runtime/server/index.mjs` + Author Tools |

+ | Add review pins to a page, export For AI | [Review mark](references/review-mark.md) | `runtime/author/tools/mark/` |

+ | Batch screenshots by page state | [Scenario screenshots](references/screenshots.md) | `runtime/cli/screenshot.mjs` |

+ | Prepare final files | [Delivery & iteration](references/delivery.md) | Final delivery files |

+ | Final check before delivery | [Delivery checklist](references/delivery-checklist.md) | Per-item checkboxes |

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

+ When generating or heavily changing UI, read the [shared generation contract](references/generation-contract.md) first; for other tasks read the matching entry above without reading the full contract.

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

+ For visual tasks, pick a foundation and providers via the [UI pack catalog](ui/catalog.md), then locate the minimal dependency closure with `node <skill-root>/scripts/resolve-pack.mjs --select=<id>`; all UI packs follow the [UI pack contract](ui/contract.md).

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

+ `scripts/` holds the agent's deterministic tools. `runtime/` is split by execution boundary: `client/` formal browser runtime, `author/` browser authoring tools, `server/` local Node authoring service, `cli/` standalone command-line tools.

- ## 核心边界

+ ## Core boundaries

- - 所有原型必须按顺序使用 `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 与正式标注数据，不生成业务状态。

- - 系统名、菜单、字段、状态和业务数据必须来自用户材料；信息不明确时先询问，禁止猜测。

+ - Every prototype must use the distributed copies of `runtime/client/core/display-mode.js`, `runtime/client/core/state.js`, `runtime/client/notes/model.js`, `runtime/client/notes/viewer.js` in order; `state.js` provides the single `PrototypeViewers` state source, `model.js` handles only note scenario metadata and pure `when` matching, and Notes Viewer handles only DOM/connector rendering. Do not fold these responsibilities back into the Viewer.

+ - Formal notes are written back to `prototype/notes.snapshot.js` only through `runtime/server/index.mjs` + Notes Editor; do not inline a notes editor in `prototype.html` and do not store formal notes in localStorage.

+ - Mark is a temporary review tool in the Author Tools panel alongside Direct Edit; its data goes to page-path-scoped localStorage, is never written to the snapshot, and is not injected into the source HTML.

+ - Direct Edit previews in the authoring session only and writes back to the source HTML safely through the server.

+ - The authoring service only handles local editing and in-prototype source lookup; it never enters the source HTML or the final deliverable.

+ - Screenshots consume only the URL scene and formal annotation data; they do not generate business state.

+ - System names, menus, fields, states, and business data must come from the user's materials; ask when information is unclear, never guess.