squirrelscan
GitHub

What squirrel can and cannot tell you about accessibility

Which accessibility problems squirrel finds automatically, what it cannot judge, what browser rendering changes, and why a clean report is not a compliance statement.

squirrel finds common, mechanical accessibility problems and gives your coding agent the exact element to fix. It does not certify anything. This page says where that line sits, so you can decide what still needs a person.

What the rules are

The accessibility rules are hand-written checks in the a11y category that read each page’s markup. They are not an axe-core run, and they do not load a page in a browser to measure it. Each rule page states the exact report message and the cases it skips.

Run only these rules with:

squirrel audit https://example.com --rule-include a11y

What squirrel checks

These are things a parser can establish from the markup.

AreaExample rules
Accessible names on controlsa11y/button-name, a11y/form-labels, a11y/select-name, a11y/input-image-alt, a11y/frame-title
ARIA validitya11y/aria-roles, a11y/aria-valid-attr, a11y/aria-required-children, a11y/aria-hidden-focus
Structurea11y/heading-order, a11y/empty-heading, a11y/landmark-regions, a11y/skip-link
Tables and listsa11y/table-headers, a11y/th-has-data-cells, a11y/list-structure
Languagea11y/html-lang-valid, a11y/valid-lang
Zoom and keyboarda11y/zoom-disabled, a11y/tabindex, a11y/accesskeys

Image alt text lives in the images category, as images/alt-text. It cites 1.1.1 Non-text Content, so the accessibility checklist counts it on that row, but --wcag-level filters accessibility rules only, so it runs at every level.

What squirrel only partly checks

Some rules look at one part of a problem and say so when they cannot see the rest.

  • Color contrast: a11y/color-contrast measures text that has an inline color, against a background it can work out from inline styles, a plain html or body rule or a same-site stylesheet. Text it cannot measure is counted as not measured, not as a pass.
  • Focus visibility: a11y/focus-visible flags outline: none with no :focus-visible fallback. When it finds nothing to judge it reports that focus styles were not analyzed.
  • Touch targets: a11y/touch-targets reads inline style attributes only. A target sized by a stylesheet or utility class is invisible to it.
  • Video captions: a11y/video-captions checks for a caption track on native video and flags third-party embeds. It cannot tell whether captions are accurate.

What browser rendering changes

Cloud browser rendering changes the markup the rules read: they see the page after JavaScript has built it, so a button added by a script is checked instead of missed. It does not add separate accessibility checks. The same rules run on the rendered HTML, which means no computed-style contrast measurement, no keyboard walk-through and no reflow or text-spacing test.

What needs a person

No parser can judge these, so squirrel does not claim to:

  • Whether alt text describes the image, and whether a decorative image really is decorative.
  • Whether link text, headings and labels make sense out of context.
  • Whether captions and transcripts match the audio.
  • Whether a keyboard user can complete a task, in a sensible order, without a trap.
  • How the page behaves with a screen reader, with 400% zoom, with increased text spacing or in forced-colors mode.
  • Whether motion, timing and error handling suit the people using the page.

Test those yourself, ideally with people who use assistive technology.

Accessibility checklist

Every Markdown report of an audit that ran has a checklist of the 55 WCAG 2.2 Level A and AA success criteria. 4.1.1 Parsing is obsolete in WCAG 2.2 and left out. Each row comes from the criteria the rules declare (shown on each rule page) and says what those rules found on this audit:

What the rules foundMeaning
Rules found an issueA rule mapped to the criterion reported a warning or failure. A lead to check, not a verdict.
Rules found no issueThe rules mapped to the criterion ran and reported nothing. They cover part of it at most, so it can still fail.
Rules did not runRules are mapped to the criterion, but none ran on this audit: excluded with --rule-exclude, filtered by --wcag-level, timed out or errored. Re-run without the exclusion to check it. A rule that ran and found nothing to check on any page did run.
No rule covers itNo squirrelscan rule is mapped to the criterion. Keyboard access, live captions and error handling are examples.

Each row also lists the rules that ran, the rules that did not run (so a rule left out of a partly checked criterion still shows), and the rules with findings. Every row has a manual check column, because every criterion still needs one.

To print only the checklist for a review pass, as Markdown or as CSV with empty manual_result and reviewer_notes columns:

squirrel report --wcag-checklist
squirrel report --wcag-checklist csv -o wcag-checklist.csv

A bare --wcag-checklist prints Markdown.

A report read with --input does not carry the passing checks, so there a rule that found nothing reads as not run, and squirrel says so on stderr.

A failed or blocked audit ran no rules, so it has no checklist: --wcag-checklist on one says so on stderr and exits 1.

Using the report well

Treat a finding as a lead worth fixing and a pass as “nothing mechanical was found”. Fix the errors first, then work through the manual list above before you describe the site as accessible to anyone. If you need a statement for legal or procurement purposes, get it from a qualified auditor.

Type to search…

↑↓ navigate↵ openesc close