Back to Details

ui-verification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UI Verification

UI验证

Owns the browser session. Every other UI skill in this repo reasons about source and infers what the user will see; this one loads the page and measures it.
  • IS: booting the app, driving it with a browser, and running the probes that decide a rule at runtime: computed boxes, injected failures, observed layout shift, a scripted Tab walk, an axe scan per theme. Output is findings keyed to rule ids with reproducible evidence, plus the clearing re-run after a fix.
  • IS NOT: finding defects by reading source or deciding their tier and ship verdict (
    ui-design
    Audit mode owns both); building or restyling UI (
    ui-design
    Build); authoring a durable test suite (write Playwright tests); pixel-diff regression against a baseline (Chromatic, Percy); field performance (RUM or CrUX; Lighthouse is a lab tool).
The division of labour is the point. A static audit reports what the code will probably do; it cannot see a 40px control whose hit area a pseudo-element already expands to 44, or a retry button wired to nothing. This skill reproduces or kills each of those, so a finding arrives with a measurement instead of a confidence.
掌控浏览器会话。此仓库中的其他UI技能均基于源代码进行分析并推断用户所见内容；而本技能会加载页面并进行实际测量。
  • 负责： 启动应用、通过浏览器驱动应用运行、执行可在运行时判定规则的探针：计算盒子模型、注入故障、观测布局偏移、脚本化Tab遍历、按主题执行axe扫描。输出结果为关联规则ID的可复现问题证据，以及修复后的验证重跑结果。
  • 不负责： 通过读取源代码发现缺陷或判定缺陷等级与发布结论（
    ui-design
    审计模式负责这两项）；构建或重新设计UI（
    ui-design
    构建功能）；编写持久化测试套件（编写Playwright测试）；与基线进行像素差异回归测试（Chromatic、Percy）；现场性能数据（RUM或CrUX；Lighthouse是实验室工具）。
明确分工是关键。静态审计报告代码可能产生的行为；但它无法发现某个40px控件的点击区域已被伪元素扩展至44px，或者重试按钮未绑定任何功能。本技能可复现或排除这些问题，让问题结果附带实际测量数据而非置信度。

Contents

目录

When to run

运行时机

SituationWhat this skill does
A 
ui-design
audit emitted findings and the user wants them confirmed		Run only the probes those rule ids map to, in 
references/rule-coverage.md
No audit ran; the user points at a route or a running appDetect features, run the full battery on the resolved routes
A fix just landed for a previously reproduced findingRun the clearing re-run only (step 5)
The user asks for captures across themes or widths
probes/theme-locale-matrix.md
alone
A 
design-system.md
claims a scale and someone needs it checked		Read the claimed values off computed styles on a real page; a theme value the build overrides never reaches the browser
Nothing here assigns a tier or a ship verdict. Hand reproduced findings back with their evidence and let 
ui-design
's 
references/ship-readiness.md
tier them; two skills tiering the same finding is how the tiers drift apart.
场景本技能的操作
ui-design
审计已生成问题结果，用户需要确认这些结果		仅运行
references/rule-coverage.md
中与这些规则ID对应的探针
未执行审计；用户指定了某个路由或正在运行的应用检测功能，对解析后的路由运行全套探针
针对之前复现的问题的修复已完成仅运行验证重跑（步骤5）
用户需要跨主题或不同宽度的捕获结果仅运行
probes/theme-locale-matrix.md
design-system.md
声明了某种尺寸规范，需要进行检查		从真实页面的计算样式中读取声明的值；构建过程中被覆盖的主题值永远不会到达浏览器
本技能不负责分配缺陷等级或发布结论。将附带证据的复现问题结果返回，由
ui-design
的
references/ship-readiness.md
来判定等级；若两个技能同时判定同一问题的等级，会导致等级标准出现偏差。

Probe catalogue

探针目录

Each file is one probe: what it measures, the driver calls, the false positives it must guard, and the shape of the evidence it returns.
ProbeMeasuresPrimary for
probes/axe-scan.mdaxe-core violations per route and theme, including computed contrastcontrast, accessible names, landmarks, document language
probes/target-size.mdBounding box and effective hit area of every visible interactive element
interaction-target-size
probes/focus-walk.mdScripted Tab traversal, focus-ring pixel delta, dialog trap and restoration
focus-*
, 
interaction-focus-visible
, 
interaction-keyboard-operable
probes/layout-shift.mdAttributed 
layout-shift
entries with the data response held open
states-layout-shift
, 
perf-image-dimensions-and-priority
probes/viewport-stress.mdHorizontal overflow and clipped text at 320px and up, and under tripled strings
layout-long-content-safety
, 
mobile-viewport-scaling
probes/failure-injection.mdWhat renders when the data request returns 500, 
[]
, malformed, or nothing
states-no-error-state
, 
states-no-empty-state
, 
async-*
, 
microcopy-*
probes/theme-locale-matrix.mdThe same route captured across viewport, theme, pseudo-locale, and direction
dark-i18n-untested
, 
dark-i18n-rtl-untested
probes/console-network.mdConsole errors, page errors, failed requests, hydration mismatch warningshydration mismatch, silent runtime failures
probes/web-vitals.mdLCP with its attributed element, CLS, INP on a scripted interactionperf attribution, never a budget verdict
每个文件对应一个探针：包含测量内容、驱动调用、需要防范的误报情况，以及返回证据的格式。
探针测量内容主要针对规则
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.md320px及以上宽度下的水平溢出和文本截断情况，以及三倍长度字符串下的表现
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性能归因，不做预算判定

Progress checklist

进度检查清单

text
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
text
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. Establish the session

1. 建立会话

Read references/session-setup.md. It resolves four things, and getting any of them wrong invalidates every probe downstream:
  • Driver. Playwright when the repo can run it, the Chrome DevTools browser tools when it cannot. Four probes need request interception and network control, so they do not exist under a driver without them.
  • Build mode. Perf and layout-shift probes run against a production build; dev-mode numbers measure the bundler. Failure injection and focus probes run fine in dev.
  • Auth and seeded data. A route behind a login with no seeded session returns 
    unknown
    , never a pass.
  • Routes. Map the diff to URLs. A component with no reachable route falls back to the repo's Storybook, and to 
    unknown
    if there is none.
Stop here if the app will not boot. A verification run with no session produces no findings, which is a reportable outcome and not a clean bill of health.
阅读references/session-setup.md。它会解决四个问题，任何一个出错都会使后续所有探针的结果失效：
  • 驱动程序：仓库支持时使用Playwright，不支持时使用Chrome DevTools浏览器工具。有四个探针需要请求拦截和网络控制，因此不支持这些功能的驱动无法运行它们。
  • 构建模式：性能和布局偏移探针针对生产构建运行；开发模式下的数值测量的是打包工具的性能。故障注入和焦点探针在开发模式下可正常运行。
  • 认证和预置数据：需要登录但无预置会话的路由会返回
    unknown
    ，永远不会判定为通过。
  • 路由：将差异映射到URL。无法访问的组件会回退到仓库的Storybook，若没有Storybook则返回
    unknown
    。
如果应用无法启动，请在此停止。未建立会话的验证运行不会生成任何问题结果，这是可报告的结果，而非无问题的证明。

2. Select the probe set

2. 选择探针集

Handed a list of rule ids (the normal case, from a 
ui-design
audit): open 
references/rule-coverage.md
, take the probe each id maps to, and run only those. Ids with no probe stay source-only findings and pass through untouched, marked as such.
Given only routes: detect features the way 
ui-design
's feature playbooks do (form, list, modal, dashboard, checkout), then run the battery that surface earns. 
probes/axe-scan.md
, 
probes/console-network.md
, and 
probes/viewport-stress.md
run on every route regardless: they are cheap, and they are the three that find things nobody suspected.
Budget the matrix before running it. Routes multiplied by viewports multiplied by themes grows fast, and a run that takes twenty minutes gets skipped next time. Two viewports (360 and 1280) and two themes cover the ground; add widths only where a probe already found an edge.
收到规则ID列表（常规情况，来自
ui-design
审计）：打开
references/rule-coverage.md
，选择每个ID对应的探针，仅运行这些探针。无对应探针的ID仍为仅基于源代码的问题结果，保持原样并标记。
仅提供路由：按照
ui-design
的功能手册检测功能（表单、列表、模态框、仪表盘、结账页），然后运行该功能对应的全套探针。
probes/axe-scan.md
、
probes/console-network.md
和
probes/viewport-stress.md
会在所有路由上运行：它们成本低，且能发现无人预料的问题。
运行前估算矩阵规模。路由数乘以视口数乘以主题数会快速增长，耗时20分钟的运行下次会被跳过。两个视口（360px和1280px）和两个主题即可覆盖主要场景；仅在探针已发现边缘情况时增加宽度。

3. Run the probes

3. 运行探针

Each probe file carries its own recipe. Three rules hold across all of them:
  • Capture evidence before interpreting it. Write the screenshot, the JSON measurement, and the console log to disk first. A finding whose evidence was never written is unverifiable by the person reading the report, which puts it back where the static audit left it.
  • One probe, one route, one viewport, one theme. Never fold two conditions into one run: when the result surprises you, you need to know which axis produced it.
  • Repeat uncertain measurements. Retry timing-sensitive or inconsistent results under controlled conditions. A deterministic failure with a captured trigger needs no duplicate run. A result that flips remains inconclusive until its conditions are understood.
每个探针文件都有自己的操作步骤。所有探针需遵循三条规则：
  • 先捕获证据再解读：先将截图、JSON测量数据和控制台日志写入磁盘。未写入证据的问题结果无法被阅读报告的人验证，这会使其回到静态审计的状态。
  • 一次探针、一个路由、一个视口、一个主题：切勿将两种条件合并到一次运行中：当结果出乎意料时，你需要知道是哪个维度导致的。
  • 重复不确定的测量：在受控条件下重试对时间敏感或结果不一致的测量。具有可捕获触发条件的确定性故障无需重复运行。结果反复变化的情况在明确其条件前仍为不确定。

4. Decide each finding

4. 判定每个问题结果

Three outcomes, and the middle one is the one that earns this skill its keep.
OutcomeMeaningWhat it does to the handed-over finding
reproduced
The probe measured the defectStays a 
fail
, now carrying 
observed
from the measurement rather than from the source read
not-reproduced
The tested conditions did not exhibit the defectWithdraw only if the probe exercised the alleged trigger; otherwise retain the candidate with the remaining coverage gap
unknown
The probe could not run or could not decideFinding survives as 
unknown
with the probe's reason. Never converts to a pass
A 
not-reproduced
result is a real deliverable, not a wasted run. It is what removes the false positives a large rule corpus asserts with 
file:line
confidence, and it feeds the rejection section 
ui-design
already requires.
Where a probe finds something no static rule predicted, emit it as a new finding against the rule id the probe is primary for. Where no rule covers it (an axe violation with no ui-design counterpart, a console error), emit it under 
axe:<violation-id>
or 
runtime:<signature>
and say plainly that it came from the browser and not the corpus.
三种结果，其中中间的结果是本技能的核心价值所在。
结果含义对传入问题结果的处理
reproduced
探针测量到了缺陷保持
fail
状态，现在附带的是测量得到的
observed
值，而非源代码分析得出的值
not-reproduced
测试条件下未出现该缺陷仅当探针已验证了所谓的触发条件时才撤回该结果；否则保留候选结果并标记剩余的覆盖缺口
unknown
探针无法运行或无法判定结果保持
unknown
状态并附带探针的原因说明。永远不会转换为通过
not-reproduced
结果是真实的交付成果，而非无效运行。它能消除大型规则库以
file:line
置信度断言的误报，并为
ui-design
要求的拒绝部分提供数据。
若探针发现了静态规则未预测到的问题，将其作为新的问题结果关联到该探针主要针对的规则ID。若没有规则覆盖该问题（无对应ui-design规则的axe违规、控制台错误），则以
axe:<violation-id>
或
runtime:<signature>
为标识输出，并明确说明它来自浏览器而非规则库。

5. Clearing re-run

5. 验证重跑

A fix is not verified by reading the diff. Re-run the identical probe: same route, same viewport, same theme, same seed, same injected failure. Record it as 
clearedBy
on the finding, keep the before-artifact, and never overwrite it with the after.
Three outcomes worth naming:
  • The probe now passes: the finding is 
    applied
    and cleared.
  • The probe still fails: the fix did not work. Report it as applied-unverified and say so; do not report the fix and stay silent about the re-run.
  • The probe passes but a different probe on the same route now fails: the fix caused a regression, which is a new finding, not a footnote on the old one.
不能通过阅读代码差异来验证修复效果。重新运行完全相同的探针：相同路由、相同视口、相同主题、相同预置数据、相同注入故障。在问题结果上记录
clearedBy
，保留修复前的证据，切勿用修复后的证据覆盖它。
三种值得注意的结果：
  • 探针现在通过：问题结果标记为
    applied
    并已清除。
  • 探针仍失败：修复未生效。将其报告为已应用但未验证，并明确说明；切勿仅报告修复而对重跑结果保持沉默。
  • 探针通过，但同一路由上的另一个探针现在失败：修复导致了回归，这是一个新的问题结果，而非旧结果的脚注。

6. Report

6. 生成报告

references/evidence-output.md owns the shape: a 
verification
block appended to each finding, a top-level 
session
block, and artifact paths. It defines only the delta on 
ui-design
's 
references/output-adapters.md
schema, which stays the single owner of the finding object, the three counts, and the verdict.
Where this skill runs standalone, render the same terminal adapter with 
SHIP VERDICT
omitted: the verdict is a property of a tiered audit, and printing one from probe results alone invents a tier assignment nobody made.
references/evidence-output.md定义了报告格式：每个问题结果后附加
verification
块、顶层
session
块，以及证据文件路径。它仅定义了对
ui-design
的
references/output-adapters.md
schema的增量部分，后者仍是问题结果对象、三个计数和结论的唯一所有者。
当本技能独立运行时，使用相同的终端适配器但省略
SHIP VERDICT
：结论是分级审计的属性，仅根据探针结果生成结论相当于自行分配了无人认可的等级。

Honesty rules

诚信规则

  • A skipped probe is not a passed probe. Report every probe that did not run, with the reason (no route, auth required, driver lacks interception, app would not build). A report that silently omits them reads as coverage it does not have.
  • A screenshot is evidence, not a verdict. Probes decide on measurements. Captures exist so a human can check the measurement, and for the two questions no measurement settles: whether the dark theme looks right, and whether the pseudo-locale broke the layout or merely the prose.
  • Do not widen into a redesign. This skill reports what it measured. A finding that needs a new type scale names the mode to run next, exactly as an audit does.
  • The app is the subject, not the harness. A failure caused by the probe itself (a selector that never resolved, a route interception that swallowed the wrong request) is a harness bug. Fix the probe and re-run; never report it as a defect in the app.
  • Numbers carry their units and their conditions. 
    44x44px at 360px width with touch emulation on
    is a measurement. 
    too small
    is the inference this skill exists to replace.
  • 跳过的探针不等于通过的探针：报告所有未运行的探针及其原因（无路由、需要认证、驱动不支持拦截、应用无法构建）。若报告中静默省略这些探针，会被误认为具备相应的覆盖范围。
  • 截图是证据，而非结论：探针基于测量结果做出判定。捕获内容的作用是让人工检查测量结果，以及解决两个测量无法回答的问题：深色主题是否显示正常，伪区域设置是破坏了布局还是仅影响了文本。
  • 不要扩展为重新设计：本技能仅报告测量结果。需要新尺寸规范的问题结果应指明下一步运行的模式，就像审计一样。
  • 应用是检测对象，而非工具本身：由探针自身导致的失败（选择器从未解析、路由拦截错误吞噬了请求）属于工具bug。修复探针后重新运行；切勿将其报告为应用缺陷。
  • 数值需附带单位和条件：
    44x44px，360px宽度，开启触摸模拟
    是测量结果。
    太小
    是本技能要替代的推断。

Gotchas

注意事项

The ones that cut across probes. Each probe file carries its own false positives.
  • page.emulateMedia({ colorScheme: 'dark' })
    does nothing for an app that themes with a 
    class="dark"
    or 
    data-theme
    attribute, which is most Tailwind apps. The probe reports a clean dark pass while never having left light mode. Drive the app's own toggle, and assert the attribute landed before capturing.
  • Running perf or layout-shift probes against 
    next dev
    measures on-demand compilation. The first navigation to a route can spend seconds in the bundler, which lands in LCP and dwarfs anything real.
  • Animations that never settle keep a screenshot probe waiting until timeout. Set 
    prefers-reduced-motion: reduce
    for captures, then run motion-sensitive checks in a separate pass with it off, because reduced motion is also a code path that can be broken.
这些是跨探针的常见问题。每个探针文件都有自己的误报情况。
  • page.emulateMedia({ colorScheme: 'dark' })
    对使用
    class="dark"
    或
    data-theme
    属性设置主题的应用无效，大多数Tailwind应用都是如此。探针会报告深色模式通过，但实际上从未离开浅色模式。应驱动应用自身的切换按钮，并在捕获前确认属性已设置。
  • 针对
    next dev
    运行性能或布局偏移探针测量的是按需编译性能。首次导航到路由可能需要数秒的打包时间，这会被计入LCP并掩盖真实性能。
  • 永不停止的动画会导致截图探针等待至超时。捕获时设置
    prefers-reduced-motion: reduce
    ，然后在单独的运行中关闭该设置以检查对动画敏感的内容，因为减少动画也是可能出现故障的代码路径。

Related skills

相关技能

  • ui-design
    : reads source, produces the findings this skill reproduces, and owns tiering, the ship verdict, and the finding schema.
  • typography-audit
    : type findings that need a rendered measure or leading value can be handed here for the measurement.
  • ax-audit
    : agentic surfaces. Its runtime questions use the same session and probes.
  • ui-animation
    : motion craft. This skill can capture the timing, but judging the curve is that skill's.
Maintenance only: 
evals/evals.json
holds the behavioural scenarios and routing prompts for anyone changing this skill. It never loads during a verification run.
  • ui-design
    ：读取源代码，生成本技能需复现的问题结果，并负责分级、发布结论和问题结果schema。
  • typography-audit
    ：需要渲染测量值或行高值的排版问题结果可提交至本技能进行测量。
  • ax-audit
    ：智能界面。其运行时问题使用相同的会话和探针。
  • ui-animation
    ：动画设计。本技能可捕获时间，但判断动画曲线属于该技能的职责。
仅维护用途：
evals/evals.json
包含行为场景和路由提示，供修改本技能的人员使用。它不会在验证运行期间加载。