A11yScope

A Chrome extension that checks the current page against the automatable subset of WCAG 2.2 Level AA, and explains each finding in terms a developer can act on.

Built to stay honest about its own limits: automated tooling catches roughly a third of real accessibility barriers, and the UI says so rather than implying a clean scan means compliance.

Two ways to run the same engine:

Both run locally. Nothing is uploaded, no account, no telemetry.

Design constraints

These are not incidental — they shape every decision in the codebase.

• No backend. Everything runs in the page and the side panel. There is no server to pay for, and no scan data leaves the browser.
• No build step. Plain ES modules and classic scripts, loaded directly by Chrome. npm is used only for the test runner.
• activeTab, not host permissions. The extension can read a page only after the user explicitly scans it. This keeps the install-time permission warning minimal, which matters for both review and conversion.
• No runtime dependencies. Nothing in SHIP comes from node_modules.

Layout

manifest.json               MV3 manifest
src/lib/color.js            contrast maths, alpha compositing
src/lib/dom.js              visibility, accessible names, selectors
src/rules/                  the checks, grouped by theme
src/content/engine.js       runs every rule, returns a serialisable report
src/content/highlight.js    injected highlighter (serialised into the page)
src/background/             service worker: tab access and injection
src/panel/                  side panel UI, report export
tools/make_icons.py         draws the PNG icons
tools/package.mjs           builds the Web Store zip from an allow-list
test/                       fixtures and the Chromium-backed test runner

Rules

31 checks across four groups. Each reports either a violation (the failure is unambiguous) or a review item (a real question a human has to answer — never a guess dressed up as a result).

Where a value cannot be determined — text over a background image, a ::placeholder colour, a control hidden off-screen until focused — the rule reports it for review instead of inventing a number. A scanner that cries wolf on correct markup is worse than no scanner.

Some rules only ever ask for review, because the standard itself leaves room for judgement. link-generic-text is the clearest case: WCAG 2.4.4 is Link Purpose In Context, so a "read more" whose meaning comes from the surrounding card conforms. Demanding that link text stand alone is 2.4.9, which is Level AAA.

Calibration

Precision is checked against real sites, not just the fixtures. gov.uk is the control: it is a well-known example of careful accessibility work, so anything we report there is a false positive until proven otherwise.

node tools/scan.mjs https://www.gov.uk        # expect 0 violations
node tools/scan.mjs https://stripe.com --review

Three real defects were found this way, each of which would have produced failures across most of the web:

1. The 2.5.8 spacing exception was missing. Undersized targets are exempt when a 24px circle centred on them reaches no other target. Without it, gov.uk reported 72 violations; with it, zero.
2. Text hidden by text-indent: -5000px + overflow: hidden was measured for contrast. That is the standard way to give an icon button a screen reader label. The text is never painted, so its contrast is meaningless. The engine now measures the text node with a Range and checks it survives every clipping ancestor.
3. Accessible names ignored aria-label on descendants. An icon link built as <a><svg role="img" aria-label="Nvidia"></svg></a> is correctly named, but a walker that only collects text nodes sees nothing. This alone accounted for 30 bogus "link has no discernible text" findings on stripe.com.

Each fix has a regression case in test/clean.html.

Known limitations

• Top frame only. Content inside <iframe> is not scanned.
• One moment in time. Text revealed by animation, carousel slides that are off-stage, and hover or focus states are measured in whatever state the page is in when you scan. Text painted in exactly its background colour is reported for review rather than failed, because that is nearly always an animation waiting to run.
• mix-blend-mode and gradient text. Contrast over a gradient is reported for review; text composited with a blend mode may still produce a ratio that does not match what is on screen.
• No conformance claim. Automated rules cover roughly a third of WCAG. Whether alt text is accurate, whether a keyboard user can finish a task, whether the page makes sense read aloud — none of that is testable here.

Development

npm install          # puppeteer, for the tests only
npm test             # rule engine against both fixtures
node test/extension.mjs   # loads the real extension into Chromium
npm run icons        # regenerate PNGs from tools/make_icons.py
npm run package      # build dist/a11yscope-<version>.zip

Loading it locally

1. Open chrome://extensions
2. Turn on Developer mode
3. Load unpacked → select this directory
4. Open any page, click the A11yScope toolbar icon, then Scan this page

Tests

test/fixture.html is a deliberately broken page; every rule in MUST_FIRE has to find something in it. test/clean.html is correct markup and must produce zero violations — that second assertion is the one that keeps the tool trustworthy, and it has already caught one false positive during development.