empirical-responsive-audit

Audits web UIs for mobile layout defects by rendering viewport matrices with a Playwright probe.

3|1|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/ever-just/agentskills --skill empirical-responsive-audit-ever-just
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: empirical-responsive-audit
Source: https://github.com/ever-just/agentskills/tree/main/skills/empirical-responsive-audit
Command: npx skills add https://github.com/ever-just/agentskills --skill empirical-responsive-audit-ever-just

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires playwright-core.

What problem does it solve? Static code review misses real responsive layout defects and invents false ones. This Skill audits a web UI empirically by rendering every servable surface across a phone/tablet/desktop viewport matrix in both orientations and light/dark themes, letting the browser reveal actual horizontal overflow, undersized tap targets, and iOS input-zoom traps. ## Core Features & Use Cases - Empirical viewport-matrix rendering: Renders each surface across phones (320–414px, both orientations), tablets, and desktops in light and dark modes using a preinstalled Chromium via playwright-core. - Mechanical defect detection: The injected DOM probe flags horizontal overflow with offending elements, sub-44px tap targets (WCAG 2.5.5), sub-16px inputs, and viewport-meta zoom suppression, then exits non-zero so it works as a CI pre-merge gate. - Root-cause workflow: Combines the render with targeted ripgrep anti-pattern scans to pin each defect to a file:line, and produces a severity-tagged (S1/S2/S3) findings report with exact fixes. - Use Case: When users report that a frontend "isn't optimized for mobile" or text spills outside its container, run the probe against the app, get a JSON defect log plus screenshots per viewport, fix the S1 issues, and commit the probe as a permanent regression gate. ## Quick Start Ask the agent to run the responsive probe against your app's URL and report every horizontal overflow, small tap target, and sub-16px input it finds across the full device matrix.

Frequently Asked Questions about empirical-responsive-audit

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit a website for mobile responsiveness issues?▼

Render every page across a matrix of phone, tablet, and desktop viewports in both orientations and color schemes using a Playwright-based probe. The probe mechanically detects horizontal overflow, sub-44px tap targets, and sub-16px inputs, then outputs a JSON defect log with screenshots.

How to detect horizontal overflow on mobile with Playwright?▼

Inject a DOM probe that compares documentElement.scrollWidth against window.innerWidth with 1px slack, and collect every element whose right edge exceeds the viewport. The probe sorts offenders worst-first with tag, class, id, and text so you can locate the root cause quickly.

Can I use this probe as a CI pre-merge gate?▼

Yes, the probe exits with a non-zero code whenever any viewport has horizontal overflow, so wiring it into CI blocks layout regressions automatically. Commit the script and invoke it on key surfaces as an npm script or pipeline step.

Does the probe require running playwright install?▼

No, it resolves a preinstalled Chromium via executablePath, discovering versioned builds under PLAYWRIGHT_BROWSERS_PATH and falling back to headless_shell or system Chrome paths. Running playwright install is explicitly discouraged because it re-downloads browsers.

Why does my input cause iOS to zoom when focused?▼

iOS auto-zooms any focused input whose computed font-size is below 16px, and the page cannot scroll back afterward. Fix it by setting inputs to at least 16px rather than disabling pinch-zoom, which violates WCAG 1.4.4.

When should I not use an empirical rendering audit?▼

Avoid it for pure visual-taste questions like whether a design looks premium or on-brand, and for broad UX, copy, or information-architecture reviews. It only asserts properties a rendered DOM can prove, not backend or data correctness.