Skip to content

JPeetz/agent-skills / skills/frontend/ui-verification

ui-verification

Verified

Use this skill when asked to verify UI in the browser, reproduce a UI finding, re-measure after a fix, or try to break a feature with browser probes.

UI Verification

Owns the browser session. Every other UI skill 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 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. Also the exploratory pass: a fresh tester driving a finished feature like a user to find the cases its contract never listed.
  • IS NOT: finding defects by reading source or deciding their tier and ship verdict (a static UI audit owns both); building or restyling UI; authoring a durable test suite (write Playwright tests); building or maintaining a whole app's persistent verify CLI, doctor command, and feature map; persistent pixel-baseline approval workflows (Chromatic, Percy); field performance (RUM or CrUX — Lighthouse and Web Vitals here are lab measurements).

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 44px, 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.

Contents

When to run

SituationWhat this skill does
An audit emitted findings and the user wants them confirmedRun only the probes those rule ids map to (see the catalogue)
No audit ran; the user points at a route or a running appDetect the feature type, run the full battery on the resolved routes
A fix just landed for a previously reproduced findingRun the clearing re-run only (step 5)
Acceptance checks pass and the user wants a feature tried like a real user, or asks to "try to break it"Read references/exploratory-test.md
The user asks for captures across themes or widthsProbe 7 (theme/locale matrix), then references/visual-review.md
The user asks to review a UI change or named screenshot statesreferences/visual-review.md for matched before/after inspection
A design system claims a type or spacing scaleRead 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 the audit skill tier them. Two skills tiering the same finding is how the tiers drift apart.

Probe catalogue

Nine probes. Each entry states what it measures, its primary rule coverage, and the evidence shape. Recipes live in Probe playbooks below — there is no separate probe directory, because this repo ships no browser test infrastructure of its own.

#ProbeMeasuresPrimary for
1axe-scanaxe-core violations per route and theme, including computed contrastcontrast, accessible names, landmarks
2target-sizeBounding box and effective hit area of every visible interactive elementinteraction-target-size
3focus-walkScripted Tab traversal, focus-ring pixel delta, dialog trap and restorationfocus-*, interaction-focus-visible, interaction-keyboard-operable
4layout-shiftAttributed layout-shift entries with the data response held openstates-layout-shift, perf-image-dimensions-and-priority
5viewport-stressHorizontal overflow and clipped text at 320px and up, and under tripled stringslayout-long-content-safety, mobile-viewport-scaling
6failure-injectionWhat renders when the data request returns 500, [], malformed, or nothingstates-no-error-state, states-no-empty-state, async-*, microcopy-*
7theme-locale-matrixThe same route captured across viewport, theme, pseudo-locale, and directiondark-i18n-untested, dark-i18n-rtl-untested
8console-networkConsole errors, page errors, failed requests, hydration mismatch warningshydration mismatch, silent runtime failures
9web-vitalsLCP with its attributed element, CLS, INP on a scripted interactionperf attribution, never a budget verdict

axe-scan, console-network, and viewport-stress run on every route regardless of feature type: they are cheap, and they are the three that find things nobody suspected.

Progress checklist

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

1. Establish the session

Resolve four things; getting any of them wrong invalidates every probe downstream.

  • Driver. Playwright when the repo can run it, the DevTools browser tools when it cannot. Four probes (layout-shift, failure-injection, theme matrix, web-vitals) 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.

Record the session before probing, e.g.:

session:
  baseUrl: http://localhost:3000
  buildMode: production
  driver: playwright 1.x
  auth: seeded test user (fixture)
  routes: ["/", "/checkout", "/settings/profile"]
  viewports: [360, 1280]
  themes: [light, dark]

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.

2. Select the probe set

Handed a list of rule ids (the normal case): take the probe each id maps to from the catalogue and run only those. Ids with no probe stay source-only findings and pass through untouched, marked as such.

Given only routes: detect the feature type (form, list, modal, dashboard, checkout), then run the battery that surface earns:

FeatureMinimum probe set
Formaxe, focus-walk, target-size, failure-injection, console
List / tableaxe, viewport-stress, layout-shift, failure-injection
Modal / dialogfocus-walk (trap + restore), axe, target-size
Dashboardaxe, layout-shift, web-vitals, theme matrix
Checkoutaxe, focus-walk, failure-injection, target-size, console

Budget the matrix before running it. Routes × viewports × 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.

3. Run the probes

Each playbook 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.
  • 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.

For UI-change and named-state captures, inspect the images yourself before reporting, following references/visual-review.md. Record visual observations separately from measured probe results.

Probe playbooks

Recipes use the Playwright page API. Under a DevTools driver, substitute the equivalent CDP call and say so in the report — Runtime.evaluate for the measurements, Network.setRequestInterception for the injections, and note that no equivalent exists for layout-shift attribution without the Performance domain.

1. axe-scan

Inject axe-core from the local dependency or a pinned CDN URL (never latest), scan each route in each theme, and store the raw violations JSON.

await page.addScriptTag({ path: require.resolve('axe-core/axe.min.js') });
const results = await page.evaluate(async () => await axe.run(document, {
  runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa', 'best-practice'] }
}));
  • Run after the theme attribute is asserted and after fonts settle, or computed contrast reads the fallback font.
  • Disable animations and wait for document.fonts.ready first.
  • False positives to guard: colour-contrast node reports on elements hidden by opacity: 0 but still in the a11y tree; region best-practice violations on intentional full-bleed pages.
  • Evidence: axe-<route>-<theme>.json plus a screenshot of each violation node cropped to its bounding box.

2. target-size

Walk every visible interactive element and record its bounding box, plus the effective hit area including pseudo-element expansion.

const boxes = await page.evaluate(() => {
  const sel = 'a[href],button,input,select,textarea,[role="button"],[role="link"],[tabindex]:not([tabindex="-1"])';
  return [...document.querySelectorAll(sel)].filter(el => {
    const r = el.getBoundingClientRect();
    const cs = getComputedStyle(el);
    return r.width > 0 && r.height > 0 && cs.visibility !== 'hidden' && cs.opacity !== '0';
  }).map(el => {
    const r = el.getBoundingClientRect();
    const before = getComputedStyle(el, '::before');
    const after = getComputedStyle(el, '::after');
    return { tag: el.tagName, text: (el.textContent || '').trim().slice(0, 40),
      w: +r.width.toFixed(1), h: +r.height.toFixed(1),
      pseudoBefore: before.content !== 'none', pseudoAfter: after.content !== 'none' };
  });
});
  • Report size in px with the viewport width, e.g. 32x32px at 360px width, touch emulation on.
  • False positives to guard: elements enlarged by an absolutely positioned pseudo-element (check the pseudo's own box before failing); inline links inside a paragraph (WCAG 2.5.8 exempts inline targets); elements whose spacing alone satisfies 2.5.8's spacing exception.
  • Evidence: targets-<route>-<viewport>.json plus a screenshot with outlined boxes when any element is under the threshold.

3. focus-walk

Script a Tab traversal, record the focused element at each step, and measure the focus-ring delta as rendered pixels.

const walk = [];
for (let i = 0; i < 40; i++) {
  await page.keyboard.press('Tab');
  walk.push(await page.evaluate(() => {
    const el = document.activeElement;
    const cs = getComputedStyle(el);
    const r = el.getBoundingClientRect();
    return { tag: el.tagName, id: el.id, name: el.getAttribute('aria-label') || el.textContent.trim().slice(0, 40),
      outline: `${cs.outlineStyle} ${cs.outlineWidth} ${cs.outlineColor}`,
      boxShadow: cs.boxShadow, rect: [r.x, r.y, r.width, r.height].map(n => +n.toFixed(1)) };
  }));
}
  • For dialogs: open it, Tab past the last focusable element, assert focus wraps inside, press Escape, assert focus returns to the opener — capture document.activeElement before opening and after closing.
  • Measure the ring with a screenshot diff of the element region focused vs unfocused; a computed outline: none with no box-shadow is a fail without needing pixels.
  • False positives to guard: :focus-visible only engages on keyboard input, so never synthesize focus with el.focus() when testing the ring; skip hidden elements in the count.
  • Evidence: focus-walk-<route>.json (ordered list) plus before/after crops of any element with no visible delta.

4. layout-shift

Hold the data response open, record attributed shift entries, and release.

await page.evaluate(() => {
  window.__shifts = [];
  new PerformanceObserver(list => {
    for (const e of list.getEntries()) if (!e.hadRecentInput) window.__shifts.push({
      value: e.value, sources: (e.sources || []).map(s => ({
        node: s.node && s.node.nodeName, prev: s.previousRect, curr: s.currentRect }))
    });
  }).observe({ type: 'layout-shift', buffered: true });
});
  • Delay the API route by 1500ms with page.route, navigate, wait for the response to render, then read window.__shifts.
  • Production build only; dev-mode hydration and on-demand compilation inject shifts that do not ship.
  • False positives to guard: shifts from a web font swap on a page whose font is already cached (run twice, use the second run); shifts caused by the probe's own injected banner.
  • Evidence: cls-<route>.json with per-entry value and source selectors, plus a filmstrip of frames around the shift when it exceeds the reporting threshold.

5. viewport-stress

Check horizontal overflow and clipped text at 320px and up, then under tripled strings.

const overflow = await page.evaluate(() => ({
  scrollW: document.documentElement.scrollWidth,
  clientW: document.documentElement.clientWidth,
  offenders: [...document.querySelectorAll('*')].filter(el => {
    const r = el.getBoundingClientRect();
    return r.right > document.documentElement.clientWidth + 1;
  }).slice(0, 20).map(el => `${el.tagName}.${el.className}`.slice(0, 80))
}));
  • Sweep widths 320, 360, 414, 768, 1024, 1280 and record only widths where scrollWidth > clientWidth.
  • For long content: set a pseudo-locale or multiply text nodes by 3 (el.textContent = el.textContent.repeat(3)) in a throwaway pass, then check for text-overflow clipping and overlapping boxes.
  • False positives to guard: intentional horizontal scrollers (carousels, code blocks) — assert overflow-x: auto on the ancestor before reporting; fixed decorative elements parked off-canvas.
  • Evidence: overflow-<route>-<width>.json plus a full-page screenshot at each failing width.

6. failure-injection

Drive the same route under four data conditions and capture what renders.

await page.route('**/api/**', route => route.fulfill({ status: 500, body: '{}' }));
// then: status 200 body '[]'; status 200 body '{"unexpected":true}'; route.abort('failed')
  • One condition per run; reset routes between runs with page.unroute.
  • Assert on rendered text and role, not just the absence of a spinner: an empty [] that renders a blank panel is states-no-empty-state, a 500 that renders nothing is states-no-error-state.
  • Check the retry path actually re-requests: count network calls after clicking retry.
  • False positives to guard: the app's global error boundary swallowing a localised failure (report it as a finding, not as a harness bug, if the boundary hides the whole page); cached service-worker responses answering after the route is intercepted (disable the SW or use a clean context).
  • Evidence: failure-<route>-<condition>.png plus the captured response status and the retry call count.

7. theme-locale-matrix

Capture one route across viewport × theme × locale × direction.

await page.evaluate(() => document.documentElement.setAttribute('lang', 'ar'));
await page.evaluate(() => document.documentElement.setAttribute('dir', 'rtl'));
  • Prefer the app's own theme toggle. When setting the attribute directly, assert it landed (document.documentElement.className / getAttribute('data-theme')) before capturing, and re-run axe in that theme.
  • Pseudo-locale: en-XA via the app's i18n config where available, else triple-length strings.
  • Budget: 2 viewports × 2 themes × 2 directions = 8 captures per route. Add a locale only where a string-length failure is suspected.
  • Evidence: matrix-<route>-<vw>-<theme>-<dir>.png named so a reviewer can sort them, plus the axe JSON per theme.

8. console-network

Collect from before the first navigation, not after.

page.on('console', m => { if (['error', 'warning'].includes(m.type())) logs.push({ type: m.type(), text: m.text() }); });
page.on('pageerror', e => logs.push({ type: 'pageerror', text: e.message }));
page.on('requestfailed', r => logs.push({ type: 'requestfailed', url: r.url(), err: r.failure()?.errorText }));
page.on('response', r => { if (r.status() >= 400) logs.push({ type: 'http', url: r.url(), status: r.status() }); });
  • Hydration mismatches surface as React/Vue warnings naming the mismatched node; capture the full text, not the first line.
  • False positives to guard: favicon and source-map 404s; HMR noise in dev mode; extensions' console chatter (use a clean context).
  • Evidence: console-<route>.json.

9. web-vitals

Measure LCP with its element, CLS, and INP on a scripted interaction.

await page.evaluate(() => {
  window.__vitals = {};
  new PerformanceObserver(l => { const e = l.getEntries().at(-1);
    window.__vitals.lcp = { value: e.startTime, el: e.element && (e.element.tagName + '.' + e.element.className) }; })
    .observe({ type: 'largest-contentful-paint', buffered: true });
});
  • Production build, cold cache, throttled CPU/network if the user asked for realistic numbers — and record the throttling in the report either way.
  • INP needs a real interaction: click the primary control, measure from input to next paint.
  • This probe attributes performance; it never issues a budget verdict. Report the number with its conditions and let the user decide.
  • Evidence: vitals-<route>.json with the metric, value, attributed element, and throttling conditions.

4. Decide each finding

Three outcomes, and the middle one is the one that earns this skill its keep.

OutcomeMeaningWhat it does to the handed-over finding
reproducedThe probe measured the defectStays a fail, now carrying observed from the measurement rather than from the source read
not-reproducedThe tested conditions did not exhibit the defectWithdraw only if the probe exercised the alleged trigger; otherwise retain the candidate with the remaining coverage gap
unknownThe 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.

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 corpus counterpart, a console error), emit it under axe:, runtime:, or explore: from an exploratory pass, and say plainly that it came from the browser and not the corpus.

5. Clearing re-run

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.

6. Report

Each finding carries a verification block; the run carries a session block. Keep the finding object's existing schema and add only this delta:

{
  "session": { "baseUrl": "...", "buildMode": "production", "driver": "playwright",
               "routes": ["/checkout"], "viewports": [360, 1280], "themes": ["light", "dark"] },
  "findings": [
    { "rule": "interaction-target-size", "status": "fail",
      "verification": { "outcome": "reproduced", "probe": "target-size",
        "observed": "28x28px at 360px width, touch emulation on",
        "evidence": ["artifacts/targets-checkout-360.json", "artifacts/targets-checkout-360.png"],
        "clearedBy": null } }
  ],
  "skipped": [ { "probe": "web-vitals", "reason": "dev build only; no production build available" } ]
}

Where this skill runs standalone, render the report without a SHIP VERDICT line: the verdict is a property of a tiered audit, and printing one from probe results alone invents a tier assignment nobody made.

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. Inspect captures before handing them off; visual observations complement measured results without turning a screenshot into proof of flow correctness.
  • 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.
  • 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.

Gotchas

The ones that cut across probes; each playbook lists 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.
  • A fresh browser context per route, or cookies and service workers leak state between probes and make the second route's result depend on the first.

Related skills

  • accessibility-compliance-audit: the source-side WCAG audit whose findings this skill reproduces at runtime.
  • design-to-code and frontend-ui-engineering: build and restyle UI; this skill measures what they shipped.
  • Playwright test authoring: durable suites belong in the repo's test directory, not here. These probes are one-off evidence, not regression tests.

Maintenance only: evals/evals.json holds the behavioural scenarios for anyone changing this skill. It never loads during a verification run.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall