accessible-ai-output

Accessible AI Output

The Law

AI OUTPUT IS NOT ACCESSIBLE BY DEFAULT.
Streaming text injected into the DOM is invisible to screen readers without ARIA live regions.
"We'll do accessibility later" ships content that is unusable by assistive technology now.
ARIA live regions + reading order + cognitive load review IS accessible AI output.

When to Use

Trigger before:

• Shipping any UI that streams or dynamically renders AI output
• Adding a chat interface, AI response panel, or inline suggestion
• Any component that updates its content in response to a model call
• Rendering structured AI outputs (tables, lists, code blocks generated by a model)

When NOT to Use

• Static content that does not change after initial render
• Server-side rendered pages where the full AI output is in the initial HTML

The Three Accessibility Concerns for AI Output

1 — ARIA Live Regions

Dynamically inserted content is invisible to screen readers unless an aria-live region is declared.

<!-- Streaming output — use polite: screen reader finishes current before announcing -->
<div
  role="log"
  aria-live="polite"
  aria-label="AI response"
  aria-atomic="false"
>
  <!-- Streamed tokens inserted here -->
</div>

<!-- Error messages — use assertive: interrupts current reading -->
<div role="alert" aria-live="assertive">
  Something went wrong. Try again.
</div>

<!-- Status indicators (generating, done) — polite -->
<div aria-live="polite" aria-label="Generation status">
  Generating…
</div>

Rules:

• aria-live="polite" for response content — does not interrupt what the user is reading
• aria-live="assertive" for errors only — interrupts; use sparingly
• aria-atomic="false" on streaming containers — announces each new chunk, not the entire accumulated text
• role="log" for conversational output (chat); role="status" for status messages

2 — Reading Order

Screen readers follow DOM order. Visual layout does not change DOM order.

Common failures in AI UIs:

• User message visually left, AI response visually right — but DOM has AI response before user message
• Floating action buttons (Copy, Retry) placed before the response content in DOM
• Streaming status indicator inserted at the top of the DOM but visually shown below the input

Fix: Match DOM order to reading order. Test by tabbing through the page with no CSS.

<!-- Correct DOM order -->
<div class="message user">User message text</div>
<div class="message ai" aria-live="polite">AI response text</div>
<div class="message-actions">
  <button>Copy</button>
  <button>Retry</button>
</div>

3 — Cognitive Load

AI outputs are often long, unpredictably structured, and dense. Cognitive load review asks:

• Is there a skip link to jump past a long AI response?
• Are code blocks in AI output announced as "code" (use <code> or role="code")?
• Are tables in AI output accessible (<thead>, <th scope>, caption)?
• Are citations / footnotes in AI output reachable by keyboard?
• If the response is truncated, is the truncation announced ("Response cut off — 3 more paragraphs")?

The Process

Step 1 — Add ARIA Live Regions

For every streaming or dynamic AI output container, add the correct aria-live attribute before the feature ships.

Step 2 — Audit Reading Order

Tab through the feature with CSS disabled (or use browser DevTools to view DOM order). Every interactive element and content block should be reachable in a logical order.

Step 3 — Run the Cognitive Load Checklist

- [ ] Long responses have a "skip to actions" link
- [ ] Code blocks use <code> or role="code" with language label
- [ ] Tables use <thead>, <th scope="col/row">, and a caption
- [ ] Citations / sources reachable by keyboard
- [ ] Truncation announced to screen reader
- [ ] Streaming cursor / animation has prefers-reduced-motion alternative

Step 4 — Test With a Screen Reader

Run the feature with VoiceOver (macOS) or NVDA (Windows). Verify:

• Streaming text is announced as it arrives (not all at once on completion)
• Error states interrupt reading appropriately
• Actions (Copy, Retry) are reachable and correctly labelled
• Empty state communicates the feature's purpose

Rationalization Red Flags

These thoughts mean accessibility was skipped — stop:

• "We'll do accessibility in a follow-up" — ARIA live regions take 20 minutes to add before shipping; retrofitting them after takes a week of debugging
• "Most users won't need this" — 15–20% of users have some form of disability; "most users" excludes them
• "The model output is readable, so it's accessible" — readable visually is not the same as readable by assistive technology; they are entirely different rendering paths
• "We have a screen reader pass planned for Q4" — dynamic content accessibility cannot be bolted on; it must be in the DOM structure from the start

Completion Statement Format

When accessible-ai-output is satisfied, state it like this:

Accessibility review complete.
Feature: <name>

ARIA live regions:
  Response container: role="log" aria-live="polite" aria-atomic="false" ✓
  Error container: role="alert" aria-live="assertive" ✓
  Status indicator: aria-live="polite" ✓

Reading order: DOM order matches visual reading order ✓
  Verified by: tab navigation test / DOM order audit

Cognitive load checklist:
  Code blocks: <code> with language label ✓
  Tables: thead + th scope + caption ✓
  Truncation: announced to screen reader ✓
  Reduced motion: streaming animation alternative ✓

Screen reader test: VoiceOver / NVDA — streaming announced correctly ✓
Accessibility review stored: design/reviews/<feature>/<date>-accessibility.md ✓

Why This Matters

Streaming text injected into the DOM without aria-live is completely silent to screen readers. The user hears nothing while the model generates. For a feature where generation is the primary interaction, this makes the feature entirely unusable — not degraded, absent. ARIA live regions are a 20-minute addition that converts a feature from inaccessible to usable.