prototype-ui

根据规格制作 UI 原型

此技能基于规格项目（技能 specs-ui），制作一个可点击的原型：界面相同、视觉识别相同，主要流程也能正常运行。用户可以进行导航、填写表单、查看列表变化，以及体验状态流转。所有内容都在浏览器中模拟。它适用于用户测试（引导式场景、可控的初始数据和观察）和演示。它不是应用程序：规格仍是权威依据。

界面文案、场景和交流内容均使用法语。代码（脚本、属性、变量、操作、标识符）使用英语；代码注释可以使用法语。

<skill> 指此技能的文件夹：脚本从项目根目录运行，命令为 node <skill>/scripts/…。项目根目录包含 specs/（specs/ui 用于存放规格，specs/prototype 用于存放原型）。采用旧版布局（根目录下有 specs-ui/、prototype-ui/）的项目，应先使用 specs-ui 技能中的 migrate-layout.mjs 整理目录结构。

节省 token（请先阅读）

一个原型页面大小为 35 到 70 Ko（10 000 到 20 000 个 token），而 shells.html 超过 150 Ko。为了“看看”而读取整个文件，是造成浪费的首要原因。规则如下：

1. specs/prototype/PROTOTYPE.md 是记忆文件：恢复工作时首先阅读，并尽可能只依赖它。每个阶段结束时都要更新，控制在 150 行以内。specs/ui/CONTEXTE.md 只在明确范围时阅读（阶段 1）；之后，data.js 记录主线中的事实。
2. 先总结，再阅读：outline.mjs specs/prototype e3 e4 会总结页面的每个状态并标出行号（比 HTML 短约 12 倍）；outline.mjs specs/prototype --shells 对外壳也会做同样的处理。随后只阅读有用的行（offset / limit）。绝不读取 site/，绝不完整读取 shells.html。
3. 保存接线说明，放在 specs/prototype/fiches/eN.md（模板为 templates/fiche.md）。说明只需编写一次，然后在每次迭代时更新。撰写者只需收到说明文件的路径，而不是一长段消息。
4. 撰写者应简明高效：他们阅读简短指引 references/redacteur.md，不完整阅读 alpine.md。他们分段阅读页面，针对性修改而不重新通读，最后只运行一次 build 和 check，不编写任何测试脚本，也不查看截图。
5. 先检查，再查看：先看 check.mjs 的文本，然后看场景图（--scenarios，每个阶段一张图片）；只有存疑时才看页面图。先看桌面版；只有移动端覆盖范围完整的屏幕才看移动端图。
6. 只接线选定的用户流程。 未接线的页面不产生任何成本：它会显示原型图，并可通过 ?state= 查看每个状态。
7. 只发布有改动的内容：基础代码（proto.js）和数据（data.js）与页面分离，因此修正面板或数据时只需发送一个文件。发布前集中处理修改。

角色	模型	任务
设计	主模型	明确范围、数据模型、预设、actions.js、共享接线（shells.html、nav）、说明、场景、审阅页面图、PROTOTYPE.md、发布
撰写	sonnet	根据说明为用户流程中的页面接线
机械执行	haiku	运行脚本并报告；修正被指出的链接或图标

页面接线需要理解原型图，并在不破坏它的前提下使其可交互：这属于撰写工作（Sonnet）。两名撰写者绝不处理相同页面，且只有主模型可以修改 data.js、actions.js、prototype.json 和 shells.html。

任务	阅读内容
编写说明、为共享部分接线	PROTOTYPE.md、outline.mjs 的输出、references/alpine.md（相关章节）
为页面接线（撰写者）	对应说明、references/redacteur.md
场景、测试会话、演示	references/scenarios.md

阶段 0 · 前提条件

需要有一个最新的 specs-ui 项目（包含 sources/site.json、至少一个批次和 CONTEXTE.md）。否则，应先使用 skill specs-ui 提出规格。如果 specs/prototype/PROTOTYPE.md 已存在，则表示这是恢复工作：阅读记忆文件，然后进入适用阶段。

阶段 1 · 明确范围

阅读 specs/ui/CONTEXTE.md（用户流程、角色、主线事实、清单）。使用 AskUserQuestion，并从规格中选项：

• 需要接线的用户流程，通常为 2 到 4 个：首次使用、主要任务、重要错误情况；
• 用途：用户测试、演示，或两者兼有；
• 起始情境：首次使用、已填充的账户、错误情况。

待确认的问题也要写入 PROTOTYPE.md 的“待确认”部分，绝不能只留在对话中。

步骤 2 · 准备原型

node <skill>/scripts/scaffold.mjs --specs specs/ui --out specs/prototype
(cd specs/prototype && npm install)          # une fois : Tailwind compilé, Alpine et Lucide servis localement
node <skill>/scripts/build.mjs specs/prototype
node <skill>/scripts/drift.mjs specs/prototype --mark   # point de départ du suivi des specs

脚手架会写入：

• src/pages/eN.html：每个屏幕状态的桌面版和移动版，不含规格稿中的外壳；每个状态都通过 ?state=<id> 显示，页面尚未接线时，根元素会标记为 data-proto-static；
• src/shells.html：规格稿中的外壳和共享区块；
• src/data.js、src/actions.js、src/prototype.json（其中提供了 nav 表供参考：请复核，见 references/alpine.md §10）、PROTOTYPE.md、package.json。

如果不运行 npm install，构建会回退到 CDN（浏览器版 Tailwind），因此每个屏幕都会有轻微延迟。之后重新运行脚手架不会改动已接线的页面或 shells.html：它们在规格稿中的版本会放入 src/_from-specs/。

步骤 3 · 数据与操作

主模型会在接线前编写这些内容：它们是各页面共用的契约。

• src/data.js → window.PROTO_DATA：用户流程中的业务对象，包含主线中的准确值和稳定标识符（s-1042）。只包含用户流程会显示或修改的内容。
• window.PROTO_PRESETS：场景的起始情况，以及步骤保证的状态（它们会补充数据，不会覆盖数据）。
• src/actions.js → window.PROTO_ACTIONS：每个操作对应一个动作（this.data、this.notify()、this.later(ms, fn)），会自动保存；如果页面需要跳转到新建对象，动作会返回该对象。

将这些内容记录在 PROTOTYPE.md 中。

步骤 4 · 接线

1. 共享部分由主模型负责：复核 nav，然后在 shells.html 中接线需要跟随数据变化的部分（侧边栏、页眉）；只读取相关模板的行（outline.mjs --shells）。
2. 每个页面一份页面说明，放在 fiches/eN.md 中，使用 outline.mjs 准备：状态与条件、数据、操作、参数、静态内容、允许使用的文本。
3. 编写者（sonnet，负责互不重叠的页面）会收到：各自的页面说明、references/redacteur.md、PROTOTYPE.md。

规则：

• 保留设计稿，只添加行为；
• 接线桌面版和移动版；
• 不得添加规格稿之外的内容，但用户流程必然要求的派生状态除外：这些状态要与相邻设计稿组合，并按照 alpine.md §2 的要求记录在 PROTOTYPE.md 中；
• 标记在原型中创建的对象（fresh）。

收到反馈后，整合各项记录：所需操作、新文本和偏差都要写入 PROTOTYPE.md 和页面说明。

步骤 5 · 场景

在 prototype.json → scenarios 中填写：id、title、persona、goal、start、preset，以及用于演示典型场景流程的 steps。步骤格式为 { "text", "page", "preset" }：点击“下一步”或“上一步”会打开相应屏幕并加载其数据。格式、面板、观察事项、测试会话和演示：见 references/scenarios.md。

步骤 6 · 构建、检查与复核

node <skill>/scripts/build.mjs specs/prototype
node <skill>/scripts/check.mjs specs/prototype --scenarios   # --sheet pour les planches de pages

check.mjs 会报告阻塞项：

• 缺失链接、未知的预设或步骤；
• 遗留的规格稿外壳；
• JS 或 Alpine 错误、未知图标、未组装的区块；
• 桌面版和移动版的水平溢出。

每个场景的每个步骤都会在其屏幕上检查，并重建相应状态（?scenario=<id>&scenario-step=<n>）。使用 --pages e2,e13 可限制检查范围（--pages scenarios 则只检查步骤）。复核场景总览：屏幕是否正确、状态是否正确、故事是否连贯。

步骤 7 · 发布

node <skill>/scripts/prepare-publish.mjs specs/prototype <scratchpad>/prototype-publish

使用 Artifact 工具发布：

• file_path：主页面；
• files：提供的列表，仅包含已修改的文件（对于新 artifact：首次发布，或属于其他账户的 artifact，使用 --all）；
• url：artifact 的 URL，用于更新。

然后运行 prepare-publish.mjs specs/prototype --confirm，并将 URL 记录到 PROTOTYPE.md 和 prototype.json → artifact 中。每位访客的数据彼此独立，并保存在其浏览器中。prepare-publish.mjs specs/prototype --check 会在不做任何准备的情况下，检查 artifact 是否落后于本地站点。

在 git 仓库中，提交 src/、fiches/、PROTOTYPE.md、构建好的站点、site/.published.json 和 src/specs-sync.json；node_modules/、.check/ 和 .build-tmp/ 不要纳入仓库。

跟踪 specs

drift.mjs specs/prototype 会指出自上次同步以来哪些屏幕的 specs 发生了变化（指纹记录在 src/specs-sync.json 中），以及共用的标识和错别字。接线后若 specs 有变更：重新运行 scaffold.mjs，将 specs 版本放入 src/_from-specs/。使用 outline.mjs specs/prototype eN --specs 对比，而不是直接阅读两个页面；将变更同步到已接线的页面和对应说明文件中，然后删除 src/_from-specs/ 并运行 drift.mjs specs/prototype --mark eN。--pages e7,e8 --force 只会重新生成尚未接线的页面（然后对这些屏幕运行 --mark）。

开发期间的维护

应用构建期间，原型仍用于用户测试和演示；它不跟随代码，而是跟随 specs。

• 已接线的页面：每当 specs 的变更影响这些页面时（drift.mjs），按上述方式同步变更；条件允许时，与 specs 的变更一起提交。
• 未接线的页面：重新生成（scaffold.mjs --pages eN --force），然后运行 --mark。
• 已过时的流程：当已交付的应用覆盖某个流程时（specs 中的状态为「已交付」），用户测试应在应用中进行。在 PROTOTYPE.md 中将该流程标记为「冻结」，而不是继续维护它。
• 重新构建、检查、重新发布已修改的文件，并与 specs 一起提交。