Contrast & Target Audit

About Contrast & Target Audit

A single JavaScript file that measures the page in front of it and hands back JSON: text below the WCAG AA contrast threshold, interactive targets under 24px, links that go nowhere, and horizontal overflow with the elements causing it.

No dependencies. No build step. No browser download. Nothing to configure before the first run.

The reason it exists

Most contrast checkers read background-color off the element holding the text — or off the nearest ancestor that has one — and compare it to color. On a flat design that is right. On a layered one it is wrong, and it is wrong quietly. You get a number, the number looks plausible, and it describes a colour that is not on the screen.

Take a translucent panel:

.panel   { background: rgba(0, 0, 0, 0.04); }
.panel p { color: #a8a8a8; }

The paragraph’s own background is transparent. Its parent is 4% black — over what? The answer is: over everything above it, all the way to the canvas the browser paints.

This tool walks from the element up to <html>, collects every non-transparent background-color on the way, and composites them back down onto the canvas in paint order with source-over alpha blending. On the example above that gives #f5f5f5, and #a8a8a8 on #f5f5f5 is 2.18:1 — a failure a declared-background checker cannot see, because it never computes #f5f5f5 at all.

Every finding carries the composited foreground and background it used. Paste both into any contrast calculator and you get the same ratio back. That is the point: a finding you can check is a finding you can argue with.

Where it stops instead of guessing

A gradient or an image cannot be reduced to one colour, and pretending otherwise produces confident nonsense — a white label on a blue gradient pill reported as 1.04:1 against a transparent parent, then “fixed” into near-black on blue.

So when a pair fails and something between it and the first opaque layer paints a background-image, the finding goes into a separate unmeasured array naming the element that painted it. It tells you where to look. It does not tell you the answer, because it does not have one. An empty unmeasured array means every failing pair was measured on real colours.

The four checks

Contrast. Every element with its own text node, color against the composited background, WCAG 2.x relative luminance. Large text (24px, or 18.66px at weight 700+) is held to 3:1 at AA; everything else to 4.5:1. --level AAA raises both. A translucent color is composited over its background first, so rgba(255,255,255,.46) is measured as what it renders as, not as white.

Target size. a button input select textarea summary under 24px, the WCAG 2.2 SC 2.5.8 minimum. Three deliberate exclusions, each of which exists because the in-house version got it wrong first:

• An inline <a> inside a sentence is exempt, and the spec says so.
• A checkbox or radio inside a <label> is measured as the label, because clicking the label activates the input. Without this, a 44px filter row full of 20px checkboxes fails on every run, forever. measuredVia records which rect was used.
• aria-hidden, [hidden] and [disabled] controls are skipped — a 1×1 honeypot is not a target anyone has to hit. This does not carry over to the contrast check: an aria-hidden glyph is still visible, and still has to be readable.

Dead links. href that is empty, #, a javascript: no-op, or a fragment whose target id is not in the document. Each one comes back with its reason.

Horizontal overflow. When scrollWidth beats clientWidth, every element whose right edge lands past the viewport is listed with that edge and its width. The first entry is usually the culprit; the rest are its parents.

Three ways to run it

Paste it into a console and call contrastTargetAudit(). This is the route for a page behind a login, or a state you can only reach by opening a drawer and clicking twice. Nothing else here can measure that.

Build a bookmarklet with node tools/build-bookmarklet.mjs. One click runs the audit, logs the object, copies the JSON to the clipboard and shows a summary line.

Run the Node runner across several URLs and widths at once:

node runner.mjs https://example.com/ https://example.com/pricing 
  --width 375 --width 768 --width 1440 
  --out report.json --pretty --fail-on-findings

The runner drives an installed Chromium — Chrome, Edge, Brave, Chromium — over the Chrome DevTools Protocol, using Node 22’s built-in global WebSocket and fetch. There is no Puppeteer here and no Playwright, so there is no browser download at install time and no dependency tree to audit. --fail-on-findings gives you an exit code for CI.

There is one option worth reading about before you use it. --init runs a script on every new document before the page’s own scripts. If your theme is picked at runtime, set it there. Setting it after load means measuring mid-transition, and a button with a 260ms background transition will hand you a ratio for a colour pair that exists for a quarter of a second and never again. That is not hypothetical — see below.

Where it comes from

This is the generalised form of tools/audit.js from the bineret.com theme, where it was the instrument for a front-end rebuild rather than a thing shipped to users. The rebuild is written up at https://bineret.com/work/rebuilding-bineret-com/.

What that means concretely, from the rebuild log:

• The final audit covered /, /packages/, /contact/, /products/, /blog/ and /404 across light and dark at 375, 768, 1280 and 1440, and came back with 0 contrast failures, 0 dead links and 0 horizontal overflow.
• Three accessibility bugs that predated the rebuild were found by this script, not by looking: footer links with 19–21px targets, a full-width “Apply filters” button that inherited no padding inside the mobile drawer and collapsed to a 17px bar, and a form honeypot that reported as an undersized target on every run.
• Two regressions were caught the same way, in a later round: a directory heading link at 63×21px, and a desktop <summary> at 171×20px — a summary is focusable and clickable at every width, not only where it is styled to look like a control.
• It also produced a false positive, repeatedly: the shop’s filter checkboxes, 20×20 inside 44px labels. That is why label-aware measurement is in this version.
• And once, it produced a number that was real but meaningless. A dark-mode run reported three CTA buttons at 2.29:1. The theme was being switched after load, and the audit measured mid-transition — the light fill with the dark ink already applied. Set before load, the same pair measures 6.13:1. That is where --init comes from.

The site-specific parts are gone. The hardcoded admin-bar skip is now the ignore option, the two hardcoded canvas colours are now pageBackground, and the attribute name it reads for colour mode is now themeAttribute. Nothing in it knows anything about WordPress, or about any particular class name.

What it does not check

It is a spot check, not a WCAG audit, and the README says so at length. It does not look at alt text, accessible names or roles, heading order, landmarks, keyboard operability, focus order or focus visibility, non-text contrast (SC 1.4.11), motion, or the HTTP status of any link. It does not model mix-blend-mode, filter, or opacity on an ancestor — the compositing is source-over alpha only, so a parent at opacity: 0.5 changes the screen in a way the maths here does not follow. It cannot see text painted onto a canvas or a video. And it only sees what is in the DOM when you run it, so a closed modal or a second tab panel is invisible until you open it.

For conformance you want axe-core or IBM Equal Access, plus a person for the manual criteria. What you get here is four classes of problem found fast, with contrast numbers that are correct on layered designs where the usual tools are not, in a form you can diff between two runs.

Included

audit.js (the whole tool), runner.mjs (the CDP runner), tools/build-bookmarklet.mjs, two fixtures, and a test that drives a real browser against both: broken.html carries exactly one failing contrast pair, one 20px button, one href="#" and one 2000px div — all four must be found — and clean.html is the same page corrected, where every count must be zero.

MIT licensed. Node 22+ for the runner only; the console and bookmarklet routes need nothing but a browser.