Empirical Responsive Audit

Empirical Responsive Audit

Overview

Auditing responsiveness by reading the code misses real defects and invents fake ones. This skill audits empirically — by rendering the UI across a device viewport matrix and letting the browser tell you the truth: does the page scroll sideways, are tap targets reachable, will an input trigger iOS zoom. It combines three lenses (render → grep → rubric), weights the render highest, and ships a re-runnable probe so the audit becomes a permanent regression gate, not a one-off report.

The cardinal rule: the render corrects the grep. A static scan will produce false positives ("no viewport meta export → desktop-width layout!"); rendering reveals the framework injected a sane default and there is zero overflow. When Lens A and Lens B disagree, Lens A wins — trust what the browser actually painted over what the source seemed to imply.

When to use

• "The frontend isn't optimized for mobile." / "It looks broken on my phone."
• "Text spills outside its container / overflows the card / gets cut off."
• "The stacking / spacing is awkward on small screens."
• Any responsive-layout, tap-target, or mobile-accessibility audit.
• As a checked-in pre-merge gate: after layout fixes, wire the probe into CI so horizontal overflow can never regress silently.

When NOT to use this skill

• Pure visual-design taste ("does this look premium / on-brand / beautiful?") → use frontend-design or ui-ux-audit.
• A broad UX/IA/accessibility-content review (copy, empty states, flows) → ui-ux-audit is the human checklist; this skill is the mechanical layout gate.
• Backend/data correctness. This skill only asserts things a rendered DOM can prove.

The three lenses (empirical-first)

Run all three, but resolve conflicts in favor of the render.

Lens A — empirical rendering (the probe)

Prereq: npm i -D playwright-core plus a preinstalled Chromium — the probe resolves the browser via executablePath and never runs playwright install.

Ship and run templates/responsive-probe.mjs. It resolves the preinstalled Chromium (never playwright install), loops the viewport matrix with deviceScaleFactor: 2 + isMobile, loads each surface (networkidle, falling back to domcontentloaded on timeout), injects a DOM probe, screenshots full-page, prints a JSON defect log, and exits non-zero if any viewport overflows.

# one surface, default full matrix (phones both orientations + tablets + desktop, light + dark)
node templates/responsive-probe.mjs https://app.example.com/dashboard dashboard ./probe-out

# fast inner-loop: phones only
PROBE_MATRIX=phones node templates/responsive-probe.mjs http://localhost:3000/ home

# CI gate — the exit code IS the gate
node templates/responsive-probe.mjs "$URL" pr-check || { echo "layout regressed"; exit 1; }

The injected probe mechanically flags, per viewport:

• Horizontal overflow — document.documentElement.scrollWidth > innerWidth (1px slack for sub-pixel rounding), plus every element whose right edge exceeds the viewport, sorted worst-first with tag/class/id/text so you can find the offender instantly.
• Sub-44px tap targets — every a/button/input/select/textarea/[role=button]/[onclick] smaller than 44×44 CSS px (WCAG 2.5.5).
• Sub-16px inputs — every text input whose computed font-size < 16px (the iOS focus-zoom trap).
• Viewport meta — presence, exact content, and a zoomDisabled flag if it contains user-scalable=no / maximum-scale=1 (WCAG 1.4.4 violation).

Viewport matrix (the default full set): phones 320 / 360 / 375 / 390 / 414 in both orientations, tablets 768 / 834, desktop 1024 / 1280 / 1440, each rendered in light and dark. Read the JSON per-viewport, and eyeball the screenshots for defects the DOM can't quantify (broken stacking, clipped art, contrast).

Lens B — static anti-pattern grep

Once the render shows where it breaks, grep for why. These are the patterns that cause the Lens-A defects — use them to pin the root-cause file:line, not to raise findings on their own:

rg -n 'w-\[[0-9]+px\]|width:\s*[0-9]+px'        # fixed px widths — need max-w-full / min-w-0
rg -n 'grid-cols-[2-9]|flex-row' -g '*.tsx' | rg -v 'sm:|md:|lg:'   # no responsive prefix
rg -n '100vw|w-screen'                           # 100vw ignores the scrollbar → overflow
rg -n 'h-screen|min-h-screen'                    # should be dvh on mobile (URL bar)
rg -n '<table'                                   # each must sit in an overflow-x-auto wrapper
rg -n 'user-scalable|maximum-scale'              # must NOT disable pinch-zoom
rg -n 'overflow-x-hidden|overflow-hidden'        # root clipping: prefer clip so sticky survives

Also hunt unbreakable strings — long domains, URLs, wallet addresses, API tokens rendered inline without min-w-0 / truncate / break-all / break-words. A single 60-char token is a classic mobile overflow the grep for w-[...] won't catch — the render will.

Lens C — brand / rubric

Score palette, type scale, spacing rhythm, and hierarchy against the project's design kit. The mobile acceptance criteria (what counts as pass/fail) live in ux-decision-rubrics — defer to it rather than re-deriving thresholds here.

Mobile-correctness rules to assert

Assert these on every audited surface. Each has a why so you can generalize to cases not listed.

Defect taxonomy (severity)

Tag every finding S1/S2/S3 so the fix backlog is prioritized.

Serving strategy

You can only audit what you can render. Get as many surfaces served as possible before falling back to component-level static review.

• Public routes — render directly with the probe.
• Auth-gated routes — render via a seeded / mocked session (test user, injected cookie, storage state) where the app allows it. If you truly can't get in, audit those screens at the component level (Lens B) and screenshot every shell/skeleton that does render (login, loading, error, empty states).
• Widgets / embeds — open them in a narrow iframe on a stub host page so the probe measures them at real embed widths.

Output

Two deliverables:

1) Findings report — one row per defect, most-severe first:

Each finding = severity × viewport(s) × root-cause file:line × exact fix. Attach the offending screenshot. Lead with the empirical evidence (overflowPx, offender tag/class) — that's what makes a finding undeniable.

2) The checked-in probe — commit responsive-probe.mjs (and an npm script / CI step invoking it on the key surfaces). Its non-zero exit on overflow is the regression gate. Copy this acceptance checklist into your report and tick it:

[ ] Probe run across the FULL matrix (phones both orientations + tablets + desktop, light+dark)
[ ] Zero horizontal overflow in every viewport (probe exit 0)
[ ] No sub-16px inputs; no sub-44px tap targets on touch surfaces
[ ] Viewport meta present; pinch-zoom NOT disabled
[ ] Auth-gated + widget surfaces served (or component-audited with a stated reason)
[ ] Probe committed + wired into CI as a pre-merge gate

Pitfalls

• Auditing the code instead of the render. The grep says "broken," the browser says "fine" (framework injected a default viewport/width). Trust the render. Static findings are leads to confirm, not verdicts.
• Running playwright install. Don't — it re-downloads a browser (slow, often blocked). Use the preinstalled Chromium via executablePath, with the headless_shell fallback path the probe already discovers.
• networkidle hangs on pages with long-poll/websocket/analytics. The probe already falls back to domcontentloaded on timeout — keep that fallback; don't wait forever.
• Forgetting mobile emulation. Set deviceScaleFactor + isMobile (+ hasTouch) on the context, or touch media queries and DPR-dependent layout never fire and you audit a lie.
• Flagging a self-contained scroller as page overflow. A wide table/code block that scrolls inside its own overflow-x: auto wrapper satisfies vertical-only page scroll — that's acceptable, not a defect. Only documentElement.scrollWidth > innerWidth is the failure.
• "Fixing" iOS input-zoom by disabling zoom. user-scalable=no is a WCAG 1.4.4 violation and treats the symptom. The fix is 16px inputs.
• One viewport ≠ audited. Overflow that hides at 390px screams at 320px, and dark mode surfaces contrast/overflow bugs light mode hides. Run the whole matrix, both themes.

Combining with other skills

• parallel-agent-refactor — fan out the S1/S2 fixes in parallel, then re-run the probe as the gate to prove every fix landed and nothing regressed.
• dark-mode-token-migration — re-run the probe in both themes after a token migration to catch contrast/overflow regressions the build can't see.
• shadcn-tailwind-v4-primitives — the primitive layer where the mobile-correctness rules (dvh, 44px targets, safe-area, 16px inputs) should be baked in once, so the audit stops finding them.
• ux-decision-rubrics — the acceptance criteria / thresholds this audit scores against.
• ui-ux-audit — the broader human UX checklist; this skill is its mechanical, empirical layout half.
• frontend-design — for the visual-taste redesign once the layout defects are fixed.
• production-agent-audit / finding-forensic-remediation — the general "evidence-bound findings → prioritized backlog" discipline this report follows.