Accessibility Audit

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

Minimal setup

Use a Vue 3.5+ project. Install the package, then import the functions and types documented in the API below from this entry.

vp install @vizejs/ui

Public entry: @vizejs/ui/a11y-audit. See Vite+ integration for project setup.

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Development-only audit that warns about ui parts without accessible names. -->
<script setup lang="ts">
import { useTemplateRef } from "vue";

import { useA11yAudit } from "@vizejs/ui/a11y-audit";

const root = useTemplateRef<HTMLDivElement>("root");
const audit = useA11yAudit(root);
</script>

<template>
  <div ref="root">
    <button type="button" data-vize-ui="button" aria-label="Close panel">×</button>
    <output>{{ audit.issues.value.length }} accessibility issues</output>
  </div>
</template>

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.