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 a11yWhat squirrel checks
These are things a parser can establish from the markup.
| Area | Example rules |
|---|---|
| Accessible names on controls | a11y/button-name, a11y/form-labels, a11y/select-name, a11y/input-image-alt, a11y/frame-title |
| ARIA validity | a11y/aria-roles, a11y/aria-valid-attr, a11y/aria-required-children, a11y/aria-hidden-focus |
| Structure | a11y/heading-order, a11y/empty-heading, a11y/landmark-regions, a11y/skip-link |
| Tables and lists | a11y/table-headers, a11y/th-has-data-cells, a11y/list-structure |
| Language | a11y/html-lang-valid, a11y/valid-lang |
| Zoom and keyboard | a11y/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-contrastmeasures text that has an inline color, against a background it can work out from inline styles, a plainhtmlorbodyrule or a same-site stylesheet. Text it cannot measure is counted as not measured, not as a pass. - Focus visibility:
a11y/focus-visibleflagsoutline: nonewith no:focus-visiblefallback. When it finds nothing to judge it reports that focus styles were not analyzed. - Touch targets:
a11y/touch-targetsreads inlinestyleattributes only. A target sized by a stylesheet or utility class is invisible to it. - Video captions:
a11y/video-captionschecks 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 found | Meaning |
|---|---|
| Rules found an issue | A rule mapped to the criterion reported a warning or failure. A lead to check, not a verdict. |
| Rules found no issue | The rules mapped to the criterion ran and reported nothing. They cover part of it at most, so it can still fail. |
| Rules did not run | Rules 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 it | No 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.csvA 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.