suaveplan/openspec/changes/enterprise-testing-a11y/design.md

Architecture

attachAxe is a thin, deterministic wrapper around @axe-core/playwright's AxeBuilder. The factory takes a Page and per-attach defaults, returns an AxeHandle whose two methods (assertNoViolations, getViolations) build a fresh AxeBuilder on each call so callers can scope per-assertion (e.g. exclude a known-noisy third-party widget for one check without leaking the override).

Adapter choice

@axe-core/playwright is the canonical Playwright adapter and ships the axe-core engine as a CDN-free script that is evaluate()-injected into the page. It matches the rest of the testing-e2e stack (Playwright primitives, no Node-only deps). Alternatives (axe-playwright, hand-rolled page.addScriptTag) were rejected: the former is community-maintained with weaker semver discipline, the latter duplicates work and forces us to track axe-core releases manually.

Defaults

• Rule set: WCAG 2.1 AA (['wcag2a','wcag2aa','wcag21a','wcag21aa']). 2.2 tags are MAY-include via runOnly override, not default, until baseline runs prove no churn.
• Impact gate: serious + critical fail by default. strict: true widens to all four (minor, moderate, serious, critical).
• Scope: entire page unless include/exclude provided.

Reporter

Violations are written to playwright-report/a11y/<spec-name>.json keyed by rule id, with impact, nodes[].target, nodes[].html, helpUrl. The path is fixed so the release-readiness aggregator (owned by enterprise-testbed-verification) can glob a single directory.

Error model

A11yError extends TestingE2eError carrying { code, cause?, context: { violations, ruleSet, url } }. Codes:

• TESTING_E2E.A11Y.VIOLATIONS_FOUND — assertion failed.
• TESTING_E2E.A11Y.AXE_LOAD_FAILED — axe-core script injection failed (CSP, navigation race).
• TESTING_E2E.A11Y.INVALID_RULESET — caller passed an unknown WCAG tag.

Baseline-update workflow

There is no baseline file. Either the page passes the rule set or it fails — drift is impossible by construction. To temporarily ignore a rule, disableRules: ['rule-id'] with a code-comment justification and an issue link is the only mechanism.

Cross-links

• Release-readiness gate: ../enterprise-testbed-verification/proposal.md.
• Audit driver: /mnt/s/web/genesis/docs/superpowers/specs/2026-04-25-test-suite-audit.md §2 row 1 and §7 row "Inspect browser console".
• Project rules: /mnt/s/web/genesis/CLAUDE.md "Web App & Page Verification".