Skip to content

Skill S12 · Vitrine — Responsive Auditor

/responsive-audit

Measures a site at phone, tablet and desktop widths with Playwright, makes a contact sheet, fixes, re-runs.

Whenever something might look wrong on a phone, and before every launch.

Measure first, then look, then fix. Numbers catch overflow you can't see; your eyes catch layouts that are technically fine and still wrong.

This skill finds defects: what's broken. To decide what's better (composition, spacing, hierarchy) across rounds of changes, use /screenshot-iteration; to design each width on purpose, use /responsive-art-direction.

1. Set up

  • The app must be running locally (for example npm run dev). Find its URL and the pages to check: every route, or the pages the user named.
  • Playwright must be available: npm i -D playwright && npx playwright install chromium if it isn't.
  • Work in a scratch directory, not in the project.

2. Run the measurement

Save this as audit.mjs in the scratch directory and run it:

node audit.mjs <base-url> <out-dir> <path> [path…]

For example node audit.mjs http://localhost:3000 ./audit / /pricing /about.

// Responsive audit: measures each page at three widths, saves a screenshot per page and width,
// writes report.json, and builds sheet.html (a contact sheet) to review by eye.
import { chromium } from "playwright";
import fs from "node:fs";
import path from "node:path";

const [base, out, ...paths] = process.argv.slice(2);
if (!base || !out || !paths.length) {
  console.error("usage: node audit.mjs <base-url> <out-dir> <path> [path…]");
  process.exit(1);
}
const WIDTHS = [
  { name: "phone", width: 375, height: 812, mobile: true },
  { name: "tablet", width: 768, height: 1024, mobile: true },
  { name: "desktop", width: 1280, height: 800, mobile: false },
];
fs.mkdirSync(out, { recursive: true });
const browser = await chromium.launch();
const report = [];

for (const p of paths) {
  for (const w of WIDTHS) {
    const ctx = await browser.newContext({ viewport: { width: w.width, height: w.height }, isMobile: w.mobile, hasTouch: w.mobile });
    const page = await ctx.newPage();
    const errors = [];
    page.on("console", (m) => m.type() === "error" && errors.push(m.text().slice(0, 200)));
    page.on("pageerror", (e) => errors.push(String(e).slice(0, 200)));
    await page.goto(new URL(p, base).href, { waitUntil: "load", timeout: 60000 });
    await page.waitForTimeout(1200);
    const m = await page.evaluate(() => {
      const W = innerWidth;
      const visible = (el) => {
        const s = getComputedStyle(el);
        return s.visibility !== "hidden" && s.display !== "none" && Number(s.opacity) > 0.05;
      };
      // Covered by something else (an overlay, a sticky bar)? Then it isn't what the user sees.
      const onTop = (el) => {
        const r = el.getBoundingClientRect();
        const x = r.left + r.width / 2;
        const y = r.top + r.height / 2;
        if (x < 0 || y < 0 || x > innerWidth || y > innerHeight) return true;
        const hit = document.elementFromPoint(x, y);
        return !hit || hit === el || el.contains(hit) || hit.contains(el);
      };
      // An element past the right edge only matters if no ancestor clips it.
      const clipped = (el) => {
        for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
          const s = getComputedStyle(a);
          if (s.overflowX !== "visible" || s.clipPath !== "none") {
            const r = a.getBoundingClientRect();
            if (r.right <= W + 2 && r.left >= -2) return true;
          }
        }
        return false;
      };
      const label = (el) => `${el.tagName.toLowerCase()}${el.id ? "#" + el.id : ""}${typeof el.className === "string" && el.className ? "." + el.className.split(" ")[0] : ""}`;
      const overflow = [];
      for (const el of document.body.querySelectorAll("*")) {
        const r = el.getBoundingClientRect();
        if (!r.width || !r.height) continue;
        if ((r.right > W + 2 || r.left < -2) && visible(el) && !clipped(el)) {
          overflow.push(`${label(el)} spans ${Math.round(r.left)}→${Math.round(r.right)}px`);
          if (overflow.length >= 5) break;
        }
      }
      const small = [];
      for (const el of document.querySelectorAll("a[href],button,input:not([type=hidden]),select,textarea,[role=button],[role=tab],[role=checkbox],[role=radio],[role=switch],[role=slider],[role=option]")) {
        const r = el.getBoundingClientRect();
        // Screen-reader-only elements (1px boxes) aren't targets anyone taps.
        if (r.width <= 2 || r.height <= 2 || !visible(el) || !onTop(el)) continue;
        if (r.width < 24 || r.height < 24) small.push(`${(el.getAttribute("aria-label") || el.textContent || label(el)).trim().slice(0, 30)} (${Math.round(r.width)}×${Math.round(r.height)})`);
      }
      const tiny = [];
      for (const el of document.body.querySelectorAll("*")) {
        if (![...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim())) continue;
        const box = el.getBoundingClientRect();
        if (box.width <= 2 || !visible(el) || !onTop(el)) continue;
        const size = parseFloat(getComputedStyle(el).fontSize);
        if (size < 10.5) tiny.push(`"${el.textContent.trim().slice(0, 24)}" at ${size}px`);
      }
      return { scrollWidth: document.documentElement.scrollWidth, width: W, overflow, small, tiny };
    });
    const file = `${p.replace(/[^a-z0-9]+/gi, "_") || "home"}-${w.name}.png`;
    await page.screenshot({ path: path.join(out, file) });
    report.push({ path: p, viewport: w.name, file, errors, ...m, horizontalScroll: m.scrollWidth > m.width + 1 });
    await ctx.close();
  }
}
await browser.close();

fs.writeFileSync(path.join(out, "report.json"), JSON.stringify(report, null, 2));
const cells = report.map((r) => `<figure><img src="${r.file}"><figcaption>${r.path} · ${r.viewport}${r.horizontalScroll || r.overflow.length ? " · OVERFLOW" : ""}</figcaption></figure>`).join("");
fs.writeFileSync(path.join(out, "sheet.html"), `<!doctype html><meta charset="utf-8"><style>body{margin:0;padding:16px;background:#111;color:#ddd;font:12px system-ui;display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));gap:12px}figure{margin:0}img{width:100%;border:1px solid #333}</style>${cells}`);

for (const r of report) {
  const issues = [];
  if (r.horizontalScroll || r.overflow.length) issues.push(`overflow: ${r.overflow.join("; ") || `page is ${r.scrollWidth}px wide`}`);
  if (r.small.length) issues.push(`${r.small.length} small targets: ${r.small.slice(0, 4).join(", ")}`);
  if (r.tiny.length) issues.push(`${r.tiny.length} tiny text: ${r.tiny.slice(0, 3).join(", ")}`);
  if (r.errors.length) issues.push(`console: ${r.errors[0]}`);
  console.log(`${r.path} [${r.viewport}] ${issues.length ? issues.join(" | ") : "ok"}`);
}
console.log(`\nReport: ${path.join(out, "report.json")}  Contact sheet: ${path.join(out, "sheet.html")}`);

3. Look

Open sheet.html in a browser, or screenshot it with Playwright if you can't open files, and review every cell. The script can't see these, so look for them:

  • A desktop layout squeezed into a phone: side-by-side columns, a sidebar taking most of the width.
  • Text overlapping other text, or controls covering content (arrows over cards, sticky bars over headings).
  • Content cut off at the bottom of a fixed-height box with no way to scroll to it.
  • Huge empty areas, or everything crammed into the top third.
  • Tablet: the awkward middle, where desktop grids are too narrow and phone stacks are too wide.

4. Judge what the numbers mean

  • Overflow (the page scrolls sideways, or an element pokes out) is always a bug. Fix it at its cause: a fixed width, a nowrap, a long word or URL, a grid without minmax(0, 1fr), a transform or scale that grows past its box. Don't hide it with overflow-x: hidden on the body.
  • Small targets under 24×24px fail WCAG 2.5.8 unless there's spacing around them or an equivalent larger control. On touch, grow the hit area (padding, or an ::after with negative inset) rather than the visual.
  • Tiny text under 10.5px: fine for deliberate uppercase mono labels with wide tracking; not fine for anything a person has to read.
  • Console errors: fix them all; hydration and key warnings often come from layout code.

5. Fix, then re-run

  • Prefer the component's own container width (container queries, %, min()) over new viewport breakpoints, so the component works wherever it's placed.
  • If a preview or demo renders components inline inside a narrower box, remember @media still sees the window. Test in a real viewport, or render the demo in an iframe.
  • Re-run the script after the fixes. Finish only when overflow and console errors are at zero and every cell of the contact sheet looks deliberate.

6. Report

List what failed, what you changed per page, and anything you left alone on purpose (and why).

Don't use when

  • You're deciding how a layout should recompose at each width. That's /responsive-art-direction.
  • You're comparing design rounds for quality. That's /screenshot-iteration. This skill measures defects.

Acceptance criteria

  • No page shows horizontal overflow at any measured width.
  • Touch targets meet the minimum size, and text stays readable.
  • No console errors at any width.
  • The contact sheet has been reviewed by eye, not only the numbers.

Common failure modes

  • Fixing overflow with overflow-x: hidden on the body, which hides the problem and breaks sticky elements.
  • Measuring only the homepage.
  • Trusting the numbers alone, so a layout that's technically fine and visually wrong passes.
  • Element screenshots under a sticky header, taken as real overlap.

Final self-review

  • Did I measure every page, or just the one I was working on?
  • Did I find the cause of each overflow, or just hide it?
  • Did I look at the contact sheet?