Replace pa11y-ci with a lightweight axe-core audit reusing Playwright #241

Context / Problem

What is the problem this feature would solve?

The documentation audit currently installs pa11y-ci 5.0.0, Pa11y 10 and a separate Puppeteer 25 browser-control stack, although @playwright/test 1.63.0 is already installed for responsive tests. The goal is to reduce the development dependency footprint and CI execution time without sampling away sitemap pages or hiding accessibility failures.

The workflow is labelled WCAG 2.1 AA, but .pa11yci.json selects WCAG2AA with the default HTML_CodeSniffer runner and no additional 2.1 rules: this is not equivalent to explicit WCAG 2.1 AA coverage. It also waits 1,500 ms per page and ignores two background-image contrast checks plus F77 duplicate-ID findings. Its advertised JSON artifact must be verified rather than assumed to exist.

Benchmark (2026-10-28)

Registry dist.unpackedSize values below describe individual published packages, not transitive installed size or browser downloads. Full-repository before/after sizes and same-machine sitemap timings will be recorded in the PR.

Sources: Playwright accessibility guide, axe-core rules and limitations, adapter documentation, pa11y-ci release, Pa11y runner/standard documentation, IBM Equal Access. Package metadata: https://registry.npmjs.org/<package>.

Solution

What is the feature you are proposing to solve the problem?

• Replace pa11y-ci with the official @axe-core/playwright integration, keeping Bun as the project runtime and package manager.
• Audit every URL in the generated VitePress sitemap using one reused browser and bounded concurrency. Use explicit WCAG 2.0/2.1/2.2 A/AA tags, no fixed sleep and no blanket suppression of contrast or ARIA findings.
• Reuse the runner's installed system Chrome in CI instead of downloading another browser. Preserve a documented local Playwright Chromium option.
• Produce real JSON results including violations and incomplete/manual-review findings, a Markdown summary, and a sticky PR report. Broken/empty sitemaps, HTTP failures, scan errors and accessibility violations must fail the audit.
• Remove the obsolete configuration/dependency and regenerate the lockfile without unrelated upgrades. Do not remove Lighthouse's separate Puppeteer-core dependency or claim all Puppeteer packages disappear.
• Update README, contributor/project documentation, AGENTS.md, repository skills and instructions. Check repository-local agents too; do not invent an unused custom agent if none exist.

What alternatives have you considered?

The table above compares maintained runners and direct engine injection. Static DOM-only tools cannot replace rendered-browser contrast/layout checks; Lighthouse remains complementary performance monitoring rather than a replacement full-sitemap audit. Different engines have different findings: this migration does not promise identical HTML_CodeSniffer rule coverage, WCAG certification, or replacement of keyboard/screen-reader/manual review.

Acceptance Criteria

• pa11y-ci, Pa11y and their exclusive transitive dependencies/configuration are removed; existing unrelated dependency versions stay stable.
• Every sitemap page is scanned with explicit WCAG 2.0/2.1/2.2 A/AA tags in a real browser, without fixed per-page waits or silently skipped URLs.
• CI reuses system Chrome without an additional browser download and reacts to runner, manifest, lockfile, shared preview action and workflow changes.
• Accessibility violations and operational failures return a nonzero exit status; incomplete results are reported for manual review.
• JSON and Markdown artifacts exist on pass/failure, and a same-repository PR gets a sticky summary without breaking fork PRs for missing write permissions.
• Regression checks demonstrate detection of a deliberate violation, invalid/empty sitemap handling and failure-report persistence.
• Before/after installed footprint, lockfile entries and full-sitemap audit durations are documented with environment/methodology and no unsupported claims about hosted CI speed.
• README, contributor docs, project docs and active agent instructions/skills agree on the new commands and coverage limitations.

Definition of Done

A focused, locally signed PR links this issue and includes the sourced comparison, measured results, relevant test/build/lint/format/knip checks and documentation build. CI is green and the PR is reviewed and merged. No CLI behavior, release version or unrelated tooling migration is included.