Skip to content
Wholisphere Docs

Scanning & Monitoring

A Wholisphere scan evaluates a page set against WCAG 2.2 and produces structured findings that roll up into a VPAT. This section covers how scans run; for the report they produce, see Compliance.

What a scan evaluates

The engine evaluates all 86 WCAG 2.2 success criteria with evidence, and every one of the 55 Level A + AA criteria has automated hard-fail detection — verified, not aspirational: three regression suites (static evaluators, full-Chromium e2e, live-model vision) run in CI against a 196-page per-criterion fixture testbed with deliberate pass and fail examples. Detection methods, which the VPAT records per criterion — we never round mixed methods up to “100% automated”:

  • Static (37 criteria) — hard-fail from markup analysis alone, no browser.
  • Browser-deterministic — Playwright probes with no LLM: keyboard interaction, focus visibility, measured flash frequency, reflow, contrast, target size, plus a cross-check against the browser’s native accessibility tree (never a third-party engine like axe-core — all detection is in-house).
  • Vision/text-LLM-assisted — criteria a rule-based scanner can’t judge (images-of-text, use-of-color, heading descriptiveness), verified against the rendered full-page screenshot; each counted only where live model runs were stable.
  • Human-attested — the 16 review-only criteria, all Level AAA, arrive as confidence-scored machine verdicts routed to one-click reviewer sign-off in the VPAT.

Scoping a scan

  • Page discovery is sitemap- or URL-list-driven (--sitemap / --urls). The scanner does not spider arbitrary links.
  • Criterion selection — --criteria, --skip-criteria, and --levels (both runners) trim a scan to what your site can actually fail; deselected criteria also switch off the browser captures they need, so trimmed scans are genuinely faster and cheaper. --levels A,AA is the AA certification run.
  • PDF documents — pass --include-pdfs and linked PDFs are graded against structural checks citing W3C PDF techniques (tagging, language, title, figure alt text, headings, tables, form labels, link text, bookmarks); document findings flow into the same review queue and VPAT as pages. An opt-in rendered-page phase — active when a vision LLM is configured or you pass --pdf-vision — rasterizes suspect pages in-memory (never persisted, capped at 10 pages/document) and adds three checks split by mechanism: deterministic rendered-text contrast measured from pixels (1.4.3, no model), a vision judge for image-of-text pages (1.4.5 / 1.1.1), and a best-effort reading-order signal (1.3.2). It adds one dependency, @napi-rs/canvas (a rasterizer, not an accessibility engine); where it can’t load, the structural verdicts stand. Honest limits: alt-text usefulness is still not graded, contrast over photos/gradients is reported indeterminate, and reading order is a signal, not proof.
  • Multi-step flows — pass --flow <startUrl> (browser runner) and the crawler walks a checkout/signup-style flow with sentinel data to decide SC 3.3.7 (redundant entry) and SC 3.3.4 (review before commit). Opt-in with a hard safety contract: same-origin, max 6 steps, and it never activates place-order/pay-style controls — point it at staging or a test-mode checkout.
  • Bring your own model — the LLM tiers accept your own key; with no model configured, the scan still hard-fails 57 criteria from the static + browser paths and reports the rest honestly as needing a model or a reviewer.

The three-tier deep scan

Run on demand (minutes and cents per page), the deep scan turns “cannot verify” into a measured verdict:

  1. Interaction probes (Playwright, no LLM) — keyboard-trap detection, focus order and visibility, 320px reflow, text spacing, motion.
  2. Audio judge — fetches caption tracks and measures cue coverage; a Whisper adapter handles transcripts, so the 1.2.x media criteria become measured.
  3. Vision & text judges — stability-verified vision and text-LLM judges rule on criteria a rule-based scanner can’t see (images-of-text, use-of-color, heading descriptiveness) against the rendered full-page screenshot. Measured, never assumed (no vision key → “unverified”, never a false pass). These verdicts feed the VPAT like any other finding — nothing is derived or inferred beyond what the scan observed.

Two ways to run a scan

  • You run it — the GitHub Action or the @wholisphere.ai/scanner-runner package, in CI or locally. Best for teams that want scans gated to deploys.
  • We run it — hosted scanning: paste a URL and our runner fleet does the rest, no CLI required. Best for agencies and non-technical clients.

Then keep it green with scheduled monitoring and hand clients a live status portal.