# Accessibility

Accessibility is a page behavior to verify, not a quality inherited by including a stylesheet. Aim for WCAG 2.2 AA and document the actual checks and gaps. The official [WCAG 2.2 standard](https://www.w3.org/TR/WCAG22/) is the normative reference; local law or procurement requirements may differ.

## Structure and operation

Use a descriptive document title, correct `lang`, one main landmark, named navigation and a visible-on-focus skip link. Preserve a logical heading outline with one page `h1`. Set link destinations and button types explicitly. Never use a clickable `div` when a native button suffices.

All controls must work by keyboard and touch. Focus remains visible, logical and unobscured by fixed navigation. Hover cannot be the sole way to reveal a caption, menu, instruction or action. A tooltip needs an accessible, dismissible interaction; a `title` attribute alone is insufficient for essential help.

Modal dialogs require a name, initial focus, contained focus where appropriate, Escape dismissal where appropriate, background handling and focus return. The modern SDS navigation toggle is a simple disclosure; it is not a modal implementation. Use a tested accessible primitive or implement the full contract before calling it a dialog.

## Perception

Verify text contrast on actual backgrounds: 4.5:1 for ordinary text and 3:1 for qualifying large text. Check non-text contrast where a boundary or state is necessary to identify a control. The light decorative `--sds-line` does not by itself establish a sufficiently contrasting form boundary. Do not communicate error, success, selection or availability through color alone.

Check zoom, text enlargement, text spacing and a 320px viewport without lost content or page-wide horizontal scrolling. Allow labeled data tables to scroll inside their own region. Respect the user's forced colors; do not suppress focus or rely exclusively on custom background images.

## Forms and updates

Use persistent labels. Explain unusual constraints before submission. Associate errors and help with inputs, preserve values after errors and provide a useful recovery action. Announce asynchronous outcomes in an appropriately scoped live region; do not repeatedly announce decorative changes. Move focus only when the task needs it, with a predictable destination.

Validation and submission are different events. A success animation or cue must follow confirmed completion, not merely syntactically valid input. Render server errors in text with enough context to retry safely.

## Alternatives

Meaningful images need contextual alt; decorative duplicates use empty alt. Complex charts need a readable explanation and access to exact data. Decorative Lottie is hidden from assistive technology; meaningful animation needs an equivalent explanation. Avoid persistent movement or provide pause/stop control. Honor `prefers-reduced-motion` and explicit still mode.

Audio is supplementary, off by default and controllable. Every audio event must have an equivalent visible state. Silence must leave the task complete. Media containing spoken information needs appropriate captions or transcripts.

## Verify

Use automated checks to find obvious failures, then manually test keyboard, focus, touch, reduced motion, zoom and a screen reader. Record browser, device and assistive technology versions and the paths tested. Passing an automated scan is partial evidence, not certification. See [quality gates](quality.md) for the release checklist.
