Accessibility Audit

Development-only accessibility auditor for rendered @vizejs/ui parts.


Package	`@vizejs/ui/a11y-audit`
Maturity	stable
Own the source	`vize lib pull a11y-audit`
Requires	—
Aliases	a11y audit, accessibility linter, accessible name check, axe-lite
Covers	WAI-ARIA accessible name computation, axe-core name rules, Vue devtools warnings

API

`a11yAuditDiagnostic`

Diagnostic prefix shared by auditor messages.

const a11yAuditDiagnostic

`accessibleNameOf`

Approximate the accessible name from ARIA, labels, alt text, title, and content.

function accessibleNameOf(element: Element): string

`auditAccessibility`

Audit a rendered subtree for common accessibility mistakes. The audit reads the live DOM only; it never mutates it. It checks accessible names on interactive parts, dialogs, and landmarks that need one, alt on images, and ARIA id references that point at nothing.

function auditAccessibility( root: Element, options: A11yAuditOptions = {}, ): readonly A11yAuditIssue[]

`a11yAuditEnabled`

Whether development-only auditing is active. Bundlers replace process.env.NODE_ENV, so production builds fold this to false and drop the auditor entirely.

const a11yAuditEnabled: boolean

`useA11yAudit`

Warn about accessibility mistakes in a rendered subtree during development. The composable audits after mount and, with observe, after DOM changes. Each element/rule pair is reported once. In production builds it is a no-op and the audit code is eliminated.

function useA11yAudit( target: A11yAuditTarget, options: UseA11yAuditOptions = {}, ): A11yAuditController

Behavior

Normative behavior for @vizejs/ui/a11y-audit: the pure auditAccessibility(root) checker and the development-only useA11yAudit(target) composable. Every row is proven by the named test.

State x input	Observable outcome	Proven by
unnamed interactive element inside a `data-vize-ui` part	`accessible-name` issue naming the element and part; visible text, `aria-label`, `aria-labelledby`, `<label>`, and `title` all satisfy the rule; hidden elements are skipped.	`reports unnamed interactive ui parts and accepts every naming technique`
`onlyUiParts: false` / `ignore`	Elements outside ui parts are audited too; ignored rules are dropped.	`reports unnamed interactive ui parts and accepts every naming technique`
unnamed dialog, repeated unnamed landmark, unlabelled `role="region"`, `img` without `alt`, id reference to a missing element	`dialog-name`, `landmark-name`, `image-alt`, and `dangling-idref` issues in document order.	`flags unnamed dialogs, repeated or region landmarks, missing alt, and dangling idrefs`
`accessibleNameOf(element)`	Uses labelledby, then `aria-label`, labels, `alt`, `title`, placeholder, then text and image alt content; a non-element root throws `VIZE_UI_A11Y_AUDIT`.	`accessibleNameOf follows labelledby, label, alt, title, and content precedence`
`useA11yAudit` after mount in development	Audits the target, warns once per element and rule with a `[VIZE_UI_A11Y_AUDIT]` prefix, and re-audits after DOM mutations.	`useA11yAudit warns once per element and rule in development and re-audits on change`
`onIssue`, `observe: false`, `audit()`	Custom reporters replace `console.warn`; `audit()` re-runs on demand without re-reporting; use outside a scope throws.	`custom onIssue handlers receive issues and audit() runs on demand`
SSR	Rendering never audits or warns.	`server rendering never audits`
`process.env.NODE_ENV === "production"`	`a11yAuditEnabled` is `false` and `useA11yAudit` returns a disabled controller, so bundlers drop the auditor.	`production builds disable the auditor`
public types	Rules are a closed union and roots must be elements.	`src/families/accessibility/a11y-audit/a11y-audit.types.test-d.ts`
DOM/SSR/Vapor	A consumer SFC using `useA11yAudit` compiles in every renderer lane.	`scripts/check-renderers.ts`