ui-verification

UI Verification

负责管理浏览器会话。本仓库中的其他 UI 技能会分析源码并推断用户将看到什么；本技能则会加载页面并进行测量。

• **是：**启动应用、通过浏览器操作应用，并运行可在运行时判定规则的探测：计算后的盒模型、注入故障、观察布局偏移、脚本化的 Tab 遍历、按主题进行 axe 扫描。输出按规则 ID 归类且附有可复现证据的发现，并在修复后再次运行以确认问题已解决。
• **不是：**通过阅读源码查找缺陷或判定其等级和发布结论（这两项均由 ui-design 的 Audit 模式负责）；构建或重设 UI 样式（ui-design Build）；编写持久化测试套件（编写 Playwright 测试）；构建或维护整个应用的持久化验证 CLI、doctor 命令和功能映射（app-verification，按名称调用）；持久化的像素基线审批工作流（Chromatic、Percy）；线上性能监测（RUM 或 CrUX；Lighthouse 是实验室工具）。

分工正是关键所在。静态审计会报告代码可能产生的效果；但它无法发现一个 40px 控件的点击区域已通过伪元素扩展到 44px，也无法发现一个重试按钮实际上没有绑定任何操作。本技能会复现或排除这些问题，因此每项发现都附有测量结果，而非仅有置信度。

目录

• 运行时机
• 探测目录
• 进度清单
• 1. 建立会话
• 2. 选择探测集
• 3. 运行探测
• 4. 判定每项发现
• 5. 修复后再次运行
• 6. 报告
• 诚信原则
• 注意事项
• 相关技能

运行时机

情况	本技能的操作
ui-design 审计产生了发现，且用户希望确认	仅运行 references/rule-coverage.md 中与这些规则 ID 对应的探测
未运行审计；用户指出某个路由或正在运行的应用	检测功能，并在解析出的路由上运行完整测试组
某项已复现发现刚完成修复	仅运行修复后再次运行（第 5 步）
用户要求跨主题或宽度截图	运行 probes/theme-locale-matrix.md，然后进行下文的视觉审查
用户要求审查 UI 变更或指定的截图状态	阅读 references/visual-review.md，了解如何检查匹配的前后状态及可疑重复项
design-system.md 声明了一套比例值，且有人需要核验	在真实页面上读取计算样式中的声明值；若构建过程覆盖了某个主题值，该值就不会应用到浏览器中

本技能不负责分配等级或给出发布结论。将已复现的发现及其证据交回，由 ui-design 通过 references/ship-readiness.md 判定等级；两个技能若对同一项发现分别判定等级，等级就会逐渐不一致。

探测目录

每个文件对应一项探测：说明它测量什么、驱动程序调用什么、需要防范哪些误报，以及返回的证据是什么形式。

探测	测量内容	主要用于
probes/axe-scan.md	每个路由和主题下的 axe-core 违规项，包括计算后的对比度	对比度、可访问名称、地标
probes/target-size.md	每个可见交互元素的边界框和有效点击区域	interaction-target-size
probes/focus-walk.md	脚本化 Tab 遍历、焦点环像素差异、对话框焦点陷阱与恢复	focus-*、interaction-focus-visible、interaction-keyboard-operable
probes/layout-shift.md	保持数据响应未完成时记录的归因 layout-shift 条目	states-layout-shift、perf-image-dimensions-and-priority
probes/viewport-stress.md	在 320px 及以上宽度、以及字符串扩展为 3 倍时的水平溢出和文本裁切	layout-long-content-safety、mobile-viewport-scaling
probes/failure-injection.md	数据请求返回 500、[]、格式错误或无响应时的渲染结果	states-no-error-state、states-no-empty-state、async-*、microcopy-*
probes/theme-locale-matrix.md	同一路由在不同视口、主题、伪本地化和文字方向下的截图	dark-i18n-untested、dark-i18n-rtl-untested
probes/console-network.md	控制台错误、页面错误、请求失败、hydration 不匹配警告	hydration 不匹配、静默运行时故障
probes/web-vitals.md	带归因元素的 LCP、CLS，以及脚本化交互中的 INP	性能归因，不用于判定是否达到预算

进度清单

Verification progress:
- [ ] Step 1: Establish the session (references/session-setup.md): driver, build mode, base URL, auth, resolved routes
- [ ] Step 2: Select the probe set from handed-over rule ids (references/rule-coverage.md) or from the routes
- [ ] Step 3: Run each probe; record evidence artifacts before interpreting any of them
- [ ] Step 4: Decide each finding reproduced / not-reproduced / unknown; repeat timing-sensitive or inconsistent results when needed
- [ ] Step 5: For each fix applied, re-run the identical probe and record clearedBy
- [ ] Step 6: Emit the verification block per finding (references/evidence-output.md), then render
- [ ] Step 7: List probes skipped and why. A probe that could not run is never a pass

1. 建立会话

阅读 references/session-setup.md。其中会确定四项内容；任何一项出错，都会使后续所有探测失效：

• 驱动程序。 仓库能运行 Playwright 时使用 Playwright，否则使用 Chrome DevTools 浏览器工具。有四项探测需要请求拦截和网络控制，因此不支持这些功能的驱动程序无法执行它们。
• 构建模式。 性能和布局偏移探测针对生产构建运行；开发模式下的数据测量的是打包器。开发模式下也可以正常运行故障注入和焦点探测。
• 身份验证和种子数据。 如果路由需要登录，但没有预置会话，则结果为 unknown，绝不会判定为通过。
• 路由。 将差异映射到 URL。无法访问路由的组件会改用仓库的 Storybook；如果没有 Storybook，则结果为 unknown。

如果应用无法启动，请在此处停止。没有会话的验证运行不会产生任何发现；这是需要报告的结果，并不代表系统状况良好。

2. 选择探测集

拿到规则 ID 列表时（通常来自 ui-design 审计）：打开 references/rule-coverage.md，选择每个 ID 对应的探测，只运行这些探测。没有对应探测的 ID 保留为仅基于源码的发现，原样传递并标记为此类发现。

**只提供路由时：**按照 ui-design 功能手册中的方式检测功能（表单、列表、模态框、仪表板、结账），然后运行相应界面所需的测试集。无论如何，每个路由都要运行 probes/axe-scan.md、probes/console-network.md 和 probes/viewport-stress.md：这些探测成本低，而且能发现三类无人预料到的问题。

运行前先规划好测试矩阵的规模。路由数、视口数和主题数相乘后，规模会迅速增大；耗时 20 分钟的运行，下次就可能被跳过。两个视口（360 和 1280）以及两个主题足以覆盖主要情况；只有在某项探测已经发现边界问题时，才增加宽度。

3. 运行探测

每个探测文件都附有自己的操作步骤。以下三条规则适用于所有探测：

• 先采集证据，再进行解读。 先将屏幕截图、JSON 测量结果和控制台日志写入磁盘。如果某项发现的证据从未写入磁盘，报告读者就无法核实，这会让它回到静态审计结束时的状态。
• 一次探测、一条路由、一个视口、一种主题。 切勿在一次运行中合并两种条件：当结果出乎意料时，你需要知道是哪个维度导致的。
• 重复不确定的测量。 在受控条件下重试对时序敏感或结果不一致的测量。对于已捕获触发条件的确定性故障，无需重复运行。结果若反复变化，在弄清其条件之前仍属无法下定论。

对于 UI 变更和具名状态的捕获，请按照 references/visual-review.md 自行检查图像。将视觉观察与测量所得的探测结果分开记录。

4. 判定每项发现

有三种结果，其中间一种正是这项技能的价值所在。

结果	含义	对交接发现的影响
reproduced	探测测出了该缺陷	保留为 fail，但现在依据测量结果而非源代码读取结果，标记为 observed
not-reproduced	在测试条件下未出现该缺陷	仅当探测覆盖了所述触发条件时才撤回；否则保留候选项，并注明剩余的覆盖缺口
unknown	探测无法运行或无法判定	发现仍以 unknown 状态保留，并注明探测给出的原因。绝不能转为通过

not-reproduced 结果是一项真正的交付成果，而非白费功夫。它能剔除大量规则库以 file:line 的精确度断言的误报，也会纳入 ui-design 已要求的驳回部分。

如果探测发现了任何静态规则都未预测到的问题，就将其作为一项新发现，关联到该探测主要针对的规则 id。如果没有规则覆盖该问题（例如没有对应 ui-design 规则的 axe 违规，或控制台错误），就将其归入 axe:<violation-id> 或 runtime:<signature>，并明确说明它来自浏览器，而非规则库。

5. 清除后的重新运行

仅阅读差异无法验证修复。请重新运行完全相同的探测：相同的路由、视口、主题、种子和注入故障。在该发现上将其记录为 clearedBy，保留修复前的产物，绝不要用修复后的产物覆盖它。

有三种值得明确说明的结果：

• 探测现在通过了：该发现已 applied 并清除。
• 探测仍未通过：修复无效。将其报告为已应用但未验证，并说明原因；不要只报告修复，却对重新运行的结果只字不提。
• 探测通过了，但同一路由上的另一项探测现在未通过：修复造成了回归，这是一个新发现，不是旧发现的脚注。

6. 报告

references/evidence-output.md 规定了格式：追加到每项发现中的 verification 块、顶层 session 块以及产物路径。它只定义 ui-design 的 references/output-adapters.md 架构中的增量部分；发现对象、三个计数和判定仍由该架构统一规定。

如果此技能单独运行，请渲染相同的终端适配器，但省略 SHIP VERDICT：判定是分层审计的属性，仅凭探测结果就打印判定，相当于凭空捏造了无人给出的层级归属。

诚实原则

• 跳过的探测不等于通过的探测。 对于每个未运行的探测，都要说明原因（没有路由、需要身份验证、驱动程序不支持拦截、应用无法构建）。报告若悄悄省略这些探测，就会让人误以为覆盖范围比实际更广。
• 截图是证据，不是结论。 探测根据测量结果作出判断。交付前，Agent 会检查捕获的内容；视觉观察可以补充测量结果，但不能把截图变成流程正确性的证明。
• 不要把范围扩大到重新设计。 此技能只报告实际测量的内容。如果某个发现需要新的字体比例，就应像审计一样，明确指出下一步要运行的模式。
• 被检查的对象是应用，不是测试框架。 如果失败是由探测本身导致的（选择器始终未解析、路由拦截吞掉了错误的请求），那就是测试框架的 bug。修复探测并重新运行；绝不要将其报告为应用缺陷。
• 数值必须带上单位和条件。 44x44px at 360px width with touch emulation on 是一项测量。太小 则是此技能旨在取代的推断。

注意事项

以下问题会影响多种探测。每个探测文件也会列出各自的误报情况。

• 对使用 class="dark" 或 data-theme 属性设置主题的应用（大多数 Tailwind 应用都如此），page.emulateMedia({ colorScheme: 'dark' }) 不起作用。探测会报告暗色模式顺利通过，但应用实际上仍处于浅色模式。应操作应用自身的切换开关，并在截图前确认属性已生效。
• 在 next dev 上运行性能或布局偏移探测，测到的是按需编译的耗时。首次导航到某个路由时，打包器可能会耗费数秒，这部分时间会计入 LCP，并远超任何真实开销。
• 如果动画始终无法结束，截图探测会一直等待直至超时。截图时应设置 prefers-reduced-motion: reduce；然后在关闭该设置的单独一轮中运行对动画敏感的检查，因为减少动态效果的代码路径也可能出错。

相关技能

• ui-design：读取源代码，产出此技能会复现的发现，并负责分级、发布结论和发现的格式规范。
• typography-audit：需要渲染尺寸或行高数值的字体发现，可以交由此技能进行测量。
• ax-audit：面向 Agent 的界面。其运行时检查使用相同的会话和探测。
• ui-animation：动画制作。此技能可以捕获时序，但曲线评判属于该技能的职责。
• app-verification：一套持久的、针对每个应用的测试框架（verify CLI、doctor 命令、功能映射、工作树隔离），由代码仓库保留并供每个 Agent 重复使用；此技能的探测属于该框架 verify 命令可调用的检查，适用于其覆盖的 UI 路径。针对固定 UI 规则进行一次性浏览器探测时，使用此技能；要让代码仓库具备持久能力，能够在每次会话中运行检查并证明自身符合要求时，请使用 app-verification（按名称调用）。

仅用于维护：evals/evals.json 保存行为场景和路由提示词，供修改此技能的人员使用。验证运行期间不会加载它。