toolkit

Scenario · Something looks broken

Someone complained the site isn't accessible

A complaint, a demand letter, or a patient saying they could not book on the site.

A complaint that the site isn't accessible carries legal weight, and the tempting response — run a checker, fix what it flags, and call it closed — is the one guaranteed to be wrong. An automated scan only catches a fraction of real barriers, and its silence is not proof that someone using a screen reader or a keyboard can actually use the site. This runs those automated checks anyway, but treats them as a starting point: the specific complaint gets reproduced first, the booking path gets tested by keyboard alone, and the final report says exactly what was tested and what wasn't — instead of quietly claiming the site now passes.

What to ask for

Accessibility (a11y)Accessibility scan for a live page — runs axe-core (Deque) across device presets and scores the page against WCAG, returning an absolute PASS / REVIEW / FAIL verdict plus a self-contained HTML report grouped by impact.Layout / front-end QAFront-end / layout QA for a live page — measures the rendered DOM across device presets and flags objective layout defects: horizontal overflow, tap targets too small, text below the legible floor, skipped heading levels, DOM bloat, interactive elements whose contrast passes at rest but fails on hover or focus, a mobile nav toggle that reveals nothing, and viewport meta defects (missing or blocking zoom).ScreenshotsCapture multi-device screenshots of any URL from the command line — one PNG per device preset (iPhone → Desktop 4K), headless, on a Playwright core.On-page SEOOn-page SEO scan — reads a page's delivered HTML and checks the head, meta and heading signals search engines use: title presence and length, meta description, rel=canonical, meta robots (noindex), Open Graph tags, viewport, html lang, and exactly one H1, plus a structured-data summary.Link & image checkerOn-page link & image checker — extracts every link and image a page declares, fetches each to its status code, and reports the dead ones (4xx/5xx broken links and broken images) plus the link-quality issues search engines and screen readers care about: non-descriptive anchor text, image-only links with no accessible text, malformed links, insecure external links, new-tab links missing rel=noopener, and excessive link counts.

See it work

A real run of Accessibility (a11y):

Accessibility (a11y) · accessibility-a11y — https://toolkit-tests.pages.dev/a11y/missing-alt.html
  running axe-core (wcag2a, wcag2aa, wcag21a, wcag21aa) across desktop,iphone-17 …

FAIL — https://toolkit-tests.pages.dev/a11y/missing-alt.html
  1 critical  0 serious  0 moderate  0 minor  0 to review  20 passed
   critical image-alt (1 el, desktop/iphone-17)

  report: ./out/accessibility-a11y-accessibility-a11y.html
  json:   ./out/axe.json
  text:   ./out/accessibility-a11y-accessibility-a11y.txt

The captured report, exactly as a run hands it to a client —open the full report ↗

For a medical practice this arrives with legal weight, and the temptation is to run a checker, fix what it says, and declare the matter closed. That is the one response guaranteed to be wrong, because the checker’s silence is not evidence.

  1. Take the specific complaint seriously and separately. If someone said they could not complete a booking, that exact path is the priority and it is worth reproducing before any general audit. A named barrier is worth more than a hundred generic findings.
  2. [manual] Route the legal side immediately. A demand letter is not a support ticket. Whoever handles the practice’s legal matters needs it now, and the technical work runs in parallel rather than instead.
  3. Run the accessibility check on the pages that matter. Home, the booking or contact path, and the top service pages. It finds contrast failures, missing labels and names, focus problems and the structural faults that block assistive technology.
  4. Check the structure and the layout. Heading order and a single H1 from the on-page grade — heading structure is how a screen-reader user navigates a page, and a page with no H1 or six of them is genuinely hard to use. The layout check catches content that overlaps or collapses, and links with no accessible name.
  5. Look at it at real sizes. Capture across devices and at increased zoom. Text that reflows off screen at 200% is a failure a desktop check does not see.
  6. [manual] Test the booking path by keyboard alone. Tab to every field, complete it, submit it, without touching the mouse. This takes two minutes, it is not automatable, and it finds the barriers that matter most — a form that cannot be completed by keyboard cannot be completed by a screen-reader user.
  7. [manual] Fix in order of who is blocked, then re-verify. Something preventing a booking outranks a contrast ratio on a footer link. Re-run the checks and repeat step 6 after the fixes.
  8. Report what was tested and what was not. Automated coverage, the manual keyboard pass, and the fact that no assistive-technology user has tested it unless one has. That honesty is the useful record.

Never report a clean scan as compliant

Automated tooling covers a fraction of the applicable criteria. Saying “the site passes accessibility checks” in response to a complaint is both untrue and, in a legal context, worse than saying nothing. Step 8 exists so the report says what was actually done.

What this does not cover

Legal advice, and most of what actually matters. Automated accessibility checks find a minority of real barriers — typically the machine-detectable ones like contrast and missing labels — and cannot tell you whether the site is usable by someone relying on a screen reader, which is a question answered by a person using one. A clean automated pass is not a defence and must never be reported as compliance.

← All scenarios