Pre-flight checklist
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.
Pre-flight checklist
Problem or use case
a11yis 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
a11yAPI 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/scrollLockbehavior, and the preference signals. Exit criteria: frozen surface, documented audit coverage with known limitations, tested focus/live-region behavior.Possible API or UX shape
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
a11yAdditional 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.