UI预览门控

UI 预览门控

每个改变屏幕的变更都要经历四个阶段。不要因为改变看起来很小就跳过任何阶段；预览图像是评审者批准的依据。

1. 检查当前状态
2. 预览并获得批准（工作开始前）
3. 实施
4. 验证结果与批准的预览相符（工作完成后）

例外：不改变预期屏幕的错误修复可以跳过第二阶段。如果用户仍能看到差异，请随修复一起提供前/后截图。显示与之前不同的屏幕、对话框、弹出层或消息属于屏幕变更，不属于此例外——即使它重用了现有组件。请先获得第二阶段的批准。

何时适用

• 无需询问即可应用。用户绝不应需要提及此技能的名称。
• 检查每一轮对话，而不仅仅是第一轮。一个从支持、研究、审查或错误报告开始的对话通常会在中途变成“如果屏幕这样做会怎样？”；从那一轮开始，此技能适用。
• “你怎么看？”、“有什么想法？”以及关于屏幕的“它会是什么样子？”都算作提案。
• 一旦开始，在随后的对话轮次中持续遵循，直到批准的变更被验证（第四阶段）或用户放弃该变更。
• 仅用散文或表格回答的提案是不完整的。在同一回复中附上前/后截图，或者说明为什么暂时无法生成以及何时可以生成。
• 在 UI 变更等待批准或进行中时，关于它的进度报告、选项列表和问题也必须重新附上其前/后截图或提供图片路径。绝不要仅用文字描述变更后的屏幕。

技能通常每轮根据其描述被选择，因此对话中途的轮次可能被遗漏。agent-instructions.md 位于此文件旁边，是一个简短的规则，用于添加到 AGENTS.md / CLAUDE.md 中，以便代理在每轮对话中重新检查。

1. 检查当前状态

永远不要凭记忆或猜测提出建议。

• 从正在运行的开发服务器或构建版本中捕获真实屏幕。默认视口为移动端 375px 宽；当变更也影响桌面布局时，添加桌面视图。
• 阅读渲染它的代码：标签/路由结构、组件、当前文本。
• 以 path/to/file:line 加上截图的形式记录证据。每个关于当前 UI 的声称都应指向其中之一。
• 优先使用现有组件、模式和文本。如果需要新的模式，请说明现有模式不适用的原因。

使用 scripts/capture.mjs（参见脚本）进行捕获，以便前截图、预览图和验证截图共享相同的视口、缩放比例和数据状态。

用例清单（在第一次预览前，主动执行）

审批者永远不必问“点击它之后呢？”或“如果有数据怎么办？”。在发送任何预览之前，根据代码和实际应用列出变更涉及的每一种情况：

• 变更屏幕的状态： 空 / 有数据 / 多项（截断、“查看全部”） / 加载中 / 错误 / 被计划、角色或权限锁定 / 其他配置（单商店 vs 多商店、功能标志）。
• 从新控件或变更控件可到达的每个屏幕： 表单、选择器、对话框、验证错误、取消/返回、确认、成功、失败。
• 操作之后： 操作完成后源屏幕的样子（新项出现、计数器变化），以及如何撤销或编辑它。
• 显示相同数据的其他位置： 列表、详情屏幕、历史记录、报告、导出、其他平台（桌面端、Web、LINE、客户方）。每个均标记为：已变更 / 未变更但显示新数据 / 不受影响。

在第一次预览时以表格形式发送清单：用例、用户所见的界面、重用的现有组件、图片状态（已附上 / 需要测试数据——如何准备 / 超出范围——原因）。预览可以分批到达，但第一条消息始终显示整个清单，批准一个图片绝不意味着未展示的用例已获批。对于未定决策，请提出合理的默认值，而不仅仅列出问题。

2. 预览并获得批准

在编写实现代码之前，向审批者展示一张并排图片和简短摘要，然后等待明确的“确定”。

图片规则：

• 左侧为“之前”，右侧为“之后”，组合在一张图片中。
• 将每个变更区域框起来：左图为红色，右图为绿色。
• 成对框选：每个变更在两侧的对应位置都应有框。对于新增项，用细线标记前图间隙中的插入点（"pad": 0，小 h）；对于移除项，在后图的间隙处标记。绝不为了代指缺失的元素而框选不相关的邻居（例如下面的行）。
• 框坐标取自 capture.mjs --selector 输出（或在需要交互的状态下（例如输入后打开的对话框），使用 Playwright 在 e2e 测试中测量的元素矩形），而非目测。在发送前查看合成后的图片，确认每个框都准确落在目标上。
• 两侧的视口、滚动位置和示例数据必须相同。
• 如果屏幕根据状态（数据存在/缺失、错误、空、按角色或配置）分支，则为变更涉及的每个状态显示一对前/后图。你未展示的状态视为未批准。每个状态制作一张图片；切勿将多对图放入一张图片中。
• 仅通过暂存（临时修改代码以打开）才能到达的真实屏幕必须在 spec 中包含 "staged"，以便图片显示此说明。
• 发送前检查：compose.mjs 会拒绝违反这些规则的 spec，并打印检查清单。打开图片，逐项回答，并将答案放入消息中（参见模板）。如果某一项失败，修复后重新合成；绝不要用文字解释失败的项目。
• 遵循下面的图片策略。

图片策略

用户或项目决定是否允许使用原型图。在请求或项目说明（AGENTS.md、CLAUDE.md、贡献文档）中查找选择。如果未说明，则使用 real-only。永远不要自行切换到 mockup-allowed，因为截图很困难；应主动询问。

• real-only（默认）：两侧都是运行中真实应用的全屏截图。在原型分支或功能标志后构建后侧并捕获。绝不要使用裁剪或粘贴的片段、从代码或手动重新绘制的原型图（包括生成的图像）、将一行截断的截图，或与真实应用显示不同的虚拟数据。
• mockup-allowed：仅当用户或项目明确允许时，后侧才可以为原型图。前侧始终是真实截图。为每个原型图面板在排版 spec 中标记 "mockup": true，以便图片显示它，并在审批请求中说明。原型图绝不计入第四阶段的证据：验证始终使用已实现屏幕的真实截图。

更严格的项目规则始终优先于较宽松的用户偏好；如果两者冲突，请指出并遵循项目规则。

摘要（使用 references/templates.md）：

• 位置：变更出现在哪个屏幕/标签以及屏幕上的什么位置
• 新功能：按用户类型（例如管理员、客户）说明变得可能的新功能
• 未变更内容：以及受影响的平台/界面

批准仅限于所展示的内容。任何超出范围的内容都需要新的预览。

3. 实施

按照批准的预览进行构建。如果实施过程迫使出现可见的偏差（布局、文本、行为、新平台影响），请停止并返回第二阶段，使用更新后的预览，而不是交付差异。

这包括为响应代码审查而进行的小型文本编辑和修复：如果修复改变了用户所见的内容（超出已批准的图片），请停止并先获得新的预览批准。事后仅用文字报告不算数。

4. 对照批准的预览进行验证

不要仅凭代码差异报告完成。

1. 使用与预览相同的捕获设置和状态重新捕获已实现的屏幕。
2. 合成验证图片：批准的预览 | 实际结果。为每个承诺的变更画框；用琥珀色框出与批准的预览之间的每个差异，即使是微小的偏移。仅用文字描述差异不视为已验证。
3. 逐项检查：
   • 每个承诺的变更都存在且与预览匹配；
   • 所有列为“未变更”的内容未变更；
   • 框选区域之外的任何内容未移动、换行或溢出；
   • 变更的交互功能在实际操作中正常，而不仅仅是渲染。通过 e2e 测试仅确认行为；它们不能替代对每个应看起来未变更的状态的图片检查。
4. 决定：
   • 匹配：使用验证图片和检查清单结果进行报告。
   • 在批准的意图内存在微小不匹配：修复、重新捕获、重新检查。
   • 改变已批准内容的不匹配：报告并重新获取批准。

将任何无法验证的内容（平台、设备、真实数据）单独列出，而不是视为完成。

脚本

两个脚本都需要 Node 18+ 和 Playwright（npm i -D playwright && npx playwright install chromium）。设置 PLAYWRIGHT_MODULE 为模块路径以重用现有安装。

捕获屏幕并获取元素的框坐标：

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

它会以 CSS 像素为单位打印选择器的矩形，准备好粘贴为 boxes。

从 JSON spec 合成面板：

node scripts/compose.mjs spec.json

Spec 格式、色调以及验证布局请参考 references/compose-spec.md。