Skip to content

feat(docs): publish each component's accessibility checklist, mapped to WCAG 2.2 - #97

Merged
alexgrozav merged 1 commit into
mainfrom
accessibility-checklists-uxf-802
Nov 19, 2026
Merged

alexgrozav merged 1 commit into
mainfrom
accessibility-checklists-uxf-802

Conversation

@alexgrozav

Copy link
Copy Markdown
Contributor

What changed

Each of the 17 components now has an accessibility checklist of its own, like /docs/accessibility/button-checklist, titled "Accessible Button Checklist (WCAG)". People search for checklists like "accessible combobox checklist", and until now the rules they want sat inside each component's four layer pages. Rules don't change, and neither does any layer (UX, DX or AX) of a component page.

A checklist holds every rule whose Basis names WCAG, WAI-ARIA or the APG, on all four layers, which is 268 of the 639 rules. Each row shows the rule, its level, its requirement, the WCAG 2.2 success criteria its Basis cites, with their short names, levels and Understanding links, and the Basis as written. Each rule links back to its table on its layer's page, since rows have no anchors of their own. Rules whose Basis is only HTML or Open Components stay on the component pages, since the Basis can't tell the accessibility ones among them from the rest.

The pages are generated, so they can't drift from the tables:

  • server/lib/checklists.ts builds each page from its component's Checklist tables. server/lib/wcag.ts holds the WCAG 2.2 criteria, with only each one's number, short name, level and Understanding slug. A Basis that cites a criterion WCAG 2.2 doesn't have, gives the wrong level or leaves the level out fails pnpm test, naming the file.
  • server/lib/checklists.test.ts compares each page in content/docs/4.accessibility/ with what the generator builds (toMatchFileSnapshot), and fails on a changed row, a missing page or a stray file. With CI set, it never writes a page, so CI fails on any difference. pnpm test server/lib/checklists.test.ts -u writes them again after a rule changes.
  • It also checks that every link lands on a heading that exists, that each page's MCP copy is the same bytes as its /raw/ copy, that the pages add no rules to the MCP server, and that the rows are exactly the rules the contracts say have such a Basis.

Each page has one title, at most 42 characters, and no seo.title, since a seo.title would head the /raw/ copy but not the MCP server's, and pnpm check-mcp compares them. "WCAG 2.2" is in each description and intro.

The folder has no index.md, which would make the pages parts of a split page. The sitemap, llms.txt, /raw/ and the MCP server pick the pages up with no other change. AGENTS.md, .github/CONTRIBUTING.md ("The docs") and a changelog entry describe them.

Checklist

  • The title follows Conventional Commits, as in feat(docs): add the focus guideline.
  • pnpm check-types passes. (So do pnpm check-reference, pnpm test, pnpm build, pnpm check-seo, pnpm build:mcp and pnpm check-mcp.)
  • Docs changes: the pages read well on pnpm dev. (Checked on the built site, in screenshots of the Combobox's checklist at 390px and 1440px.)
  • Homepage changes: pnpm build, then pnpm lighthouse, still scores 100 in every category. (No homepage changes.)

…to WCAG 2.2

Each component gets a page at /docs/accessibility/<component>-checklist with every rule whose Basis names WCAG, WAI-ARIA or the APG, the WCAG 2.2 criteria behind it and a link back to its table. server/lib/checklists.ts builds the pages from the Checklist tables, and checklists.test.ts fails when they drift.

Co-authored-by: multica-agent <github@multica.ai>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://accessibility-checklists-uxf-802.opencomponents.dev, https://accessibility-checklists-uxf-802-opencomponents.blue-water-0397.workers.dev (commit 347927a)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://fc52c0fb.opencomponents.dev, https://fc52c0fb-opencomponents.blue-water-0397.workers.dev 347927a 2026-11-19T07:26:04.400Z Visit the dashboard ↗

@alexgrozav
alexgrozav marked this pull request as ready for review November 19, 2026 07:31
@alexgrozav
alexgrozav merged commit 341cbe1 into main Nov 19, 2026
5 checks passed
@alexgrozav
alexgrozav deleted the accessibility-checklists-uxf-802 branch November 19, 2026 07:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant