Skip to content

Add WCAG accessibility conformance test suite#42502

Open
mdo wants to merge 4 commits into
v6-devfrom
mdo/wcag-a11y-tests
Open

Add WCAG accessibility conformance test suite#42502
mdo wants to merge 4 commits into
v6-devfrom
mdo/wcag-a11y-tests

Conversation

@mdo

@mdo mdo commented Jun 11, 2026

Copy link
Copy Markdown
Member

Summary

Adds a unified, generated accessibility checker so per-component WCAG coverage is derived and verified in CI rather than hand-maintained per page. This grew out of the OTP accessibility work (twbs/discussions#42486): WCAG criteria are stable, but the mapping of which criteria apply to a component—and our coverage of each—should be a single source of truth that can be linted, not prose scattered across docs.

What's included

  • site/src/data/wcag.ts — shared catalog of WCAG success criteria (title, level, version, "Understanding" URL), a criterion → axe-core rule mapping (wcagAxeRules), and coverage-status metadata. Exposes typed criterion ids so configs are validated at build time.
  • build/a11y.config.mjs — the single source of truth selecting which criteria each component is tested against, each with a built-in / partial / author coverage status and optional note. Currently covers forms/otp-input and components/menu.
  • build/test-a11y.mjs — renders each configured component's documented <Example> snippets in headless Chromium (with the compiled CSS + JS bundle) and runs axe-core, scoped to the axe rules mapped to each declared criterion. Reports the criterion id, title, level, our coverage status, and a verdict: PASS / FAIL (machine-checkable, component-owned), MANUAL (component-owned, not axe-checkable), or AUTHOR (consuming app's responsibility).
  • package.json — new js-test-a11y script (node --experimental-strip-types build/test-a11y.mjs) and the axe-core dev dependency.
  • Symbols.astro — adds a universal-access icon to the docs sprite for surfacing a11y status.

Notes

  • This adds the harness and the initial component mappings; it doesn't change any component behavior.
  • The forms/otp-input and components/menu entries pair with the separate OTP and menu PRs.

mdo added 2 commits June 10, 2026 20:36
Introduce a unified, generated accessibility checker so per-component WCAG
coverage is derived and verified rather than hand-maintained:

- site/src/data/wcag.ts: shared catalog of WCAG criteria (title, level,
  version, "Understanding" URL) plus a criterion -> axe-core rule mapping and
  coverage-status metadata.
- build/a11y.config.mjs: single source of truth selecting which criteria each
  component is tested against, with a built-in/partial/author coverage status.
- build/test-a11y.mjs: renders each component's documented <Example> snippets
  in headless Chromium (compiled CSS + JS) and runs axe-core scoped to the
  rules mapped to each declared criterion, reporting PASS/FAIL/MANUAL/AUTHOR.
- Add the "js-test-a11y" npm script and the axe-core dev dependency.
- Add a universal-access icon to the docs icon sprite.
@mdo

mdo commented Jun 11, 2026

Copy link
Copy Markdown
Member Author

@patrickhlauke This might be of interest to you! One thing I eventually want to look into is something like this, but for now outputting to the terminal feels helpful. Still need to iterate on this to see how best to identify guidelines to adhere to though.

CleanShot_2026-06-10_at_09 24 582x

@patrickhlauke

Copy link
Copy Markdown
Member

a priori, this looks interesting, but probably need to see the fully implemented feature across all components - and then likely need a good QA pass to make sure all relevant aspects are covered for each component

@patrickhlauke

Copy link
Copy Markdown
Member

related: as i've not kept track of BS for a while ... what stage is v6 at? is it at a point where a full-on manual accessibility review/test is warranted?

@patrickhlauke

Copy link
Copy Markdown
Member

not prose scattered across docs

there will likely still need to be some notes/considerations that should be flagged as part of the prose, to explain more in-depth aspects that don't necessarily map cleanly to just a "do this or you fail this SC"

@mdo

mdo commented Jun 11, 2026

Copy link
Copy Markdown
Member Author
CleanShot 2026-06-11 at 09 44 22@2x

Here's how checks look in the terminal right now. Pushed a little update for some more coverage. Plenty more to do here and TBD if we get it in for v6.0 proper or a follow-up. Basically we're at the hardening stage of things—lots of docs cleanup to do, some refinement here and there, need a new homepage. Otherwise I think some a11y reviews would be great at any point. See https://v6-dev--twbs-bootstrap.netlify.app.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Inbox

Development

Successfully merging this pull request may close these issues.

2 participants