Error announcements: Accessibility requirements
Form and action errors are exposed to assistive technology through dedicated assertive live regions with stable messages, deduplicated announcements, and focus preserved on the triggering control.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Route blocking validation and submit failures to a dedicated assertive error summary region, route success and nonblocking status to separate polite regions, associate field-level messages with inputs through stable IDs, and preserve focus except when a single-field inline error requires correction. Deduplicate identical announcement bursts within a short window.
Scope
- Client and server-origin validation errors on forms and destructive actions.
- Live-region markup, announcement text, deduplication, and clearing behavior.
- Focus policy distinguishing multi-error submit failures from single-field inline errors.
- Programmatic errors surfaced while focus remains in an editor or text area.
Outside this block
- Success or progress status messages (polite regions may appear in examples but success toast behavior is out of scope).
- Full WCAG conformance certification or legal compliance claims.
- Non-visual error presentation such as color alone or icon-only cues without text.
Contract
- Blocking submit failures render in the profile assertive summary region with
role="alert"or equivalent; success and nonblocking updates use separate polite regions and never share the assertive node. - Each invalid control references its error text through
aria-describedbypointing at a stable, unique error element ID. - Announcement text includes the human-readable field label and error message; generic "invalid field" text alone is insufficient.
- On multi-error submit, focus does not move away from the submit control unless the profile explicitly enables summary focus for keyboard users.
- On single-field inline validation, focus moves to the first invalid field and its error is associated before the next interaction.
- Identical error sets re-presented within the dedupe window do not produce back-to-back identical screen reader output.
- When an error clears, the associated node is removed or hidden and live-region text is cleared so stale errors are not re-read on navigation.
Implementation guidance
- Keep live regions mounted; update text content rather than destroying nodes between announcements.
- Separate assertive error summary from polite success regions to avoid priority inversion.
- For server round-trips, map stable field keys to DOM IDs so repeated submissions do not orphan associations.
- Test with NVDA, JAWS, and VoiceOver on at least one desktop and one mobile browser.
Failure handling and safeguards
- If error text arrives before associated fields mount, queue the announcement until IDs exist or fall back to summary-only text that names fields by label.
- If multiple errors exceed the profile cap, announce the cap and direct users to the summary list rather than truncating silently.
- If a programmatic error occurs during drag operations, do not steal focus; rely on assertive summary and optional visual banner.
- Never expose internal exception traces in live-region text; map to stable user-facing codes.
Verification and operations
- Track announcement counts per session, dedupe suppressions, and focus-move exceptions in staging telemetry.
- Include live-region output in automated accessibility tests using accessibility tree snapshots where supported.
- Review new error strings for brevity and absence of blame-oriented language during content review.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - Teams must align error copy, field labels, and localization with their product vocabulary.