ai-audit-design

ai-audit-design

A stylesheet is a claim. A painted pixel is the evidence. Everything here measures the second, because the defects that survive review are exactly the ones no declaration predicts: contrast against a gradient with grain over it, a row whose two cards start reading 68px apart, a label printing over another label at 320px, a card grid that groups the wrong things.

Serve the built output and point the audit at it. A dev server with hot reload measures a page nobody visits.

node scripts/audit.mjs --base http://127.0.0.1:4399 \
  --routes / /about /projects --widths 320 390 820 1440

--checks selects passes (geometry contrast collision proximity type interior a11y); --aa relaxes the contrast target from AAA to AA; --json out.json writes findings and text anchors. Run it before touching anything.

What each pass is asking

geometry — does the page fit, can a thumb hit it, does a heading follow the one above it. Sub-pixel borders on a pill radius, images shipping more resolution than their box can use, missing dimensions.

contrast — the ink is read from the element's own color; only the ground is sampled, because that is the part no token knows. Text over a photograph is where this earns its keep.

collision — glyph rects, not element boxes. Boxes overlap constantly and mean nothing.

proximity — for a set of like siblings, the gap between them against the largest gap inside one. Below 1.0 the space is grouping the wrong things and something else — usually a border — is arguing against it. Also inventories every stroke that is not a container edge.

type — one role, one answer. Two roles at the same size, face, weight and case whose leading differs by a hundredth is a typed value, not a decision.

interior — do containers in one row start reading on the same line, and does a component's inset scale with the type it holds.

a11y — structural and semantic checks: valid semantic markup, ARIA attribute validity and required attributes, heading / landmark / skip-link / lang / title structure, zoom disabled, deprecated elements, list-integrity (ul/ol/li, dt/dd/dl), focusable-aria-hidden mismatch, duplicate ids and accesskeys, form label coverage, and caption requirements. The a11y pass runs once per unique route across all widths; it is not width-dependent.