Skip to content

[Feature]: Promote a11y to Stable — settle the 1.14 surface and document audit scope #142

Description

@JosunLP

Pre-flight checklist

  • I searched existing issues and did not find a duplicate request.
  • I explained the problem or use case, not just the desired API.

Problem or use case
a11y is Beta and a genuine differentiator (first-party focus management, live regions, and audits where competitors rely on third-party libraries), but its surface just expanded in 1.14.0 (createLiveRegion, focusVisible, inert, scrollLock, autoFocus, preference signals) and its audits are runtime-only with no documented scope. Teams adopting it for compliance need to know exactly what the audits check and that the API won't shift.

Proposed solution
Freeze the a11y API for one cycle and publish a precise audit scope: which WCAG criteria the runtime audits cover, what they cannot detect, and how results are surfaced. Add test coverage for focus trapping, live-region announcements, inert/scrollLock behavior, and the preference signals. Exit criteria: frozen surface, documented audit coverage with known limitations, tested focus/live-region behavior.

Possible API or UX shape

import { audit, createLiveRegion, focusTrap } from "@bquery/bquery/a11y";

const report = audit(root); // documented: which WCAG checks are/aren't covered
// report.issues -> [{ rule, element, wcag, severity }]

Alternatives considered
Promoting without documenting audit scope — risks teams over-trusting runtime audits for compliance they don't actually cover. Continuing to expand the surface before freezing — fine for Beta, but must pause for Stable.

Relevant area
a11y

Additional context
Wire audit results into the devtools panel (#146) so a11y issues are inspectable alongside component state. First-party a11y is a real selling point versus React/Vue/Svelte; documenting its limits is what makes it trustworthy.

Metadata

Metadata

Assignees

No one assigned

    Labels

    a11yChanges to the a11y module

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions