ui-prototype

Files (5)

• SKILL.md
• feature-notes.css · assets/
• feature-notes.js · assets/
• content-format.md · references/
• feature-notes.md · references/

SKILL.md (first lines)

# UI Prototype

本技能（Skill）负责界面原型（UI Prototype）的生成、保存、归入任务和清理。原型以现有完整页面表达讨论中的变化，可以先于任务和规范变更存在；它不是正式设计稿、生产原型、像素级验收标准，也不替代正式规范或验证证据。

## 按意图进入

- **生成或修改**：当前对话中存在用户对本次原型的明确确认才执行。同一任务已有授权或拒绝继续有效；未确认时返回 `not-requested`，不创建占位材料、不阻塞原任务。是否需要原型由任务分流处理，本技能不重复询问。已有正式任务时，生成后立即归入任务供评审，不等待实施决定。
- **决定实施**：直接执行下方归入步骤，不重新询问是否制作原型。
- **放弃或清理**：只处理适用的临时成果，不生成新原型。

按实际范围读取已有任务、项目与服务约束、提案、设计和规范；不存在的材料不作为探索前置条件。不新增任务字段、数据库状态、独立描述文件或命令。原型与正式规范、设计冲突时先明确并收敛差异，确认的行为写回相应正式材料，不以 HTML 静默覆盖规范。

## 成果保存与接续

本节统一负责保存、归入和清理；其他技能（Skill）只交接，不复制流程。

**讨论与评审阶段**：保存位置取决于是否已有正式任务，与是否决定实施无关。

- 已有任务及关联规范变更（OpenSpec Change）：直接保存到其真实工作副本内，复用已有目录及任务发现入口；不能只提供临时预览链接。
- 已有任务但没有关联变更：保存到该任务所属主工作空间（Canonical Workspace）的 `.buildr/local/task-prototypes/<task-id>/`，使用任务记录中已核对的编码。该目录只保全本机原型成果，不新增任务状态，也不要求创建变更；不要写到隔离工作树（Worktree）的同名目录。
- 尚无任务：默认放在操作系统临时目录内本次讨论独占的子目录，报告实际可打开路径及临时性质，不承诺保留期限，不为预览创建任务或规范变更。后续建立正式任务时，立即归入任务，不等待实施决定。候选组件（Component）和构建入口仍在已核对的隔离位置维护；实际已有源码位置时保留其稳定隔离标识、工作树（Worktree）路径和分支（Branch），在同一目标进入正式开发时交给 `task-triage` 接续，不另起一套实施位置。

用户明确指定其他位置时遵从，同时明确任务内是否可发现；不能把一个普通文件链接描述为任务阅读入口。

**归入与接续**：生成后已有任务，或后续建立任务时执行。归入只表示可以评审，不表示用户已确认采用、批准实施或验收通过；决定实施时核对并复用已有副本，在正式前端编辑前补齐缺失接续。

1. 核对实际文件、当前评审版或用户确认版本、全部相关页面和资源、必要构建来源、任务身份及已有关联变更；同时交接已有源码的稳定隔离标识、工作树（Worktree）实际根、分支（Branch）和未提交成果。由 `task-triage` 决定接续同一位置，工作树提供者核验归属；材料保存或归档不重新选择源码位置。先保全已有版本，不以重新生成的画面冒充原版。
2. 按上述位置保存；有关联规范变更（OpenSpec Change）时复用其真实工作副本，补交付已归档任务使用对应归档目录。原先仅保存在任务本机目录而后续建立变更时，先核对并复制到变更，再验证任务阅读；不得在同一任务维持两份独立更新的原型。
3. 核对副本内容、自包含资源和发现标记，更新已有设计及成果引用，按下方“浏览器验证”检查任务展示。新副本完整可读且引用更新后，才清理本次已被替代且无需保留的副本；保留旧预览入口时说明用途。在本次交付说明中记录实际位置，不改写历史确认与验收。

没有关联变更不阻止任务内阅读，也不授权强造变更；是否需要规范变更仍由实际产品语义决定。本机目录不会随代码提交交付，需要移交或长期保留时同时保全构建来源和实际 HTML，并说明保留范围。

临时文件丢失时如实说明并核对可恢复来源；无法恢复则说明影响，重建不冒充原确认版。仅对无法确定的关键选择请求决定，继续不依赖缺失内容的工作。

**放弃与清理**：用户明确放弃且未要求保留，或明确授权清理后，核对实际路径、归属、使用情况和保全需要，仅删除本次独占且无需保留的临时预览。沉默或时间经过不等于放弃，系统可能清理也不等于已删除。共享、未知归属、其他任务或已归入正式任务的文件不在此范围；工作树（Worktree）和分支交给原提供者安全清理。

## 制作原型

1. **调查现有真实界面**：读取适用 `AGENTS.md` 和运行说明，检查真实页面入口、导航、组件、主题、文案与交互，按需在浏览器中查看。明确保留与变化的内容及关键状态；必要事实不可访问时说明影响，停止受影响部分，不凭空声称复用现有产品。
2. **限定范围**：覆盖关键页面及必要状态；局部修改也放回现有导航、相邻模块和信息层级，交付完整页面。单页本地状态可可靠表达时只做一页，否则必须生成多个原型页面。使用模拟数据和本地交互，不读取凭证、不接真实后端或执行真实写入。
3. **复用源码**：正式与演示入口导入同一份相关组件（Component）及主题，包括原有顶部栏、导航和主要操作；仅隔离必要的数据、导航与副作用，不另写相似界面冒充复用。无法安全隔离时停止该部分。使用项目既有构建生成自包含 HTML，记录来源提交、文件及未提交内容摘要；源码变化后重建受影响成果。
4. **提供功能说明**：制作前读取[功能说明组件](references/feature-notes.md)与[内容格式与阅读联动](references/content-format.md)，只解释当前画面与本次变化有关的功能、操作后果和边界，随状态保持一致。项目已有统一原型阅读器时，复用其页面目录、状态选择和说明交互，不另造一套说明外壳；没有现成阅读器时才按示例组装。说明组件（Component）的脚本和样式随构建内联，不能只复用卡片后自写不一致的展示工具。区域支持悬停或聚焦高亮、离开清除和点击定位，不画连线、不重置模拟数据。标题、关键状态、刷新与功能说明入口放在同一顶部操作行，窄屏允许自然换行。说明默认收回且不固定，从“功能说明”入口悬停或点击以浮窗（Popover）打开，空间充足时可手动固定并排。任务内由宿主呈现，原型不重复叠加说明面板。保留旧文件兼容。

每个文件必须含 `<!doctype html>`、`<html>`、`<head>`、可读 `<title>`、`<body>` 及精确标记 `<!-- buildr:ui-prototype -->`。必要 CSS、JavaScript 内联，媒体和字体使用内联或 `data:` / `blob:` 资源；不依赖远程资源、机器绝对路径、开发服务器、真实会话、父页面权限或浏览器持久存储。

延续真实页面的视觉与交互习惯，表达必要的加载、空白、错误和禁用等状态，不虚构平台能力。截图不能替代 HTML；调查笔记、构建记录和测试日志不放进产品画面或功能卡片。

## 浏览器验证

使用当前可用浏览器逐一打开每个 HTML 文件，实际用鼠标检查完整页面、核心交互、关键状态及对应说明，对照真实页面与已确认原型核对导航、字号、信息密度和关键路径。检查常用桌面尺寸；涉及窄屏时增加对应尺寸，不把整页缩成难以阅读或点击的缩略图。

尚无任务时验证独立预览；已有任务时，不论是否关联变更，都须在 Buildr Web 实际任务的“方案设计”和“单独查看”中验证入口、全部页面、交互与功能说明。直接打开文件不能证明任务发现正常；仅候选环境通过时，明确尚未集成生效。修正问题后重验受影响部分。

没有浏览器能力或无法覆盖核心状态时报告未验证范围，不以加载成功、键盘操作、静态截图或源码检查替代实际鼠标交互验证。

## 交付与后续实施

报告实际状态（`generated | adopted | cleaned | blocked | not-requested`）、适用任务与变更、全部文件路径及保留或清理情况、页面和状态、来源观察、浏览器与尺寸、逐页验证结果、任务展示结果及未验证范围。归入供评审仍为 `generated`，只有用户确认采用才报告 `adopted`；不新增持久状态，不把文件可见冒充实施授权或正式验收。有设计师参与时提供全部文件作为设计输入。

后续 Agent 在正式前端编辑前必须读取全部相关原型，按其信息架构、布局和交互开发；只有用户明确要求忽略原型时才可以不采用，不为此新增豁免记录或阻塞状态。

From BuildrAI/Buildr, MIT.

More from BuildrAI/Buildr