Layout Audit
layout-audit.mjs beside this file drives a page at several widths and measures the DOM. It reports
only what a person would call a layout defect; accessibility is a separate question it does not ask.
node ~/.claude/skills/layout-audit/layout-audit.mjs --base=http://localhost:3000 --routes=/,/pricing
Flags: --routes (comma separated, default /), --widths (default 1440x900,390x844), --auth=user:pass
for Basic Auth, --shots=<dir> to also write a screenshot per route and width, --json to diff runs.
Playwright is taken from the globally installed @playwright/cli, so no project gains a dependency.
Checks
| Check | What it means |
|---|---|
viewport-overflow | An element reaches past the viewport edge - the page scrolls sideways |
clipped-text | A box cuts its own text with no ellipsis and no title, so the text is unreachable |
collapsed-text | An element holds text but has no height - it reads as a blank gap |
overlapping-text | Two text boxes are drawn on the same pixels |
tiny-text | Type below what a phone can be read at |
Working with the result
- Run it against a build, not a dev server mid-edit. Hot reload leaves half-applied styles.
- Group the findings by element before fixing anything. A shared header repeated over ten routes is one defect, not ten, and the count in the report is not the amount of work.
- Truncation with an ellipsis and a title is a pattern, not a defect - the tool already excludes it. If a finding says a box clips text, the text is genuinely unreachable.
- A repeated finding on one class of element is a design decision. Type size across a whole surface, or a colour, belongs to whoever owns the design; report the numbers and let them choose rather than changing the palette in passing.
- A screenshot still catches what no rule states. Take
--shotsand look at the pages the rules called clean, especially the phone width. - A clean run says nothing about a person's phone. Playwright's WebKit with an iPhone profile is not Safari on an iPhone. When a reported phone defect does not reproduce, say so rather than report that it works, then ask for the device or remove the suspected mechanism outright.
- Prove a rule fires before trusting a zero. Plant the defect on a scratch page, run the checks against it, and watch the rule report it. A page-level clip in particular makes naive width comparisons pass on every page.