Report #82450
[gotcha] Screen readers break completely with token-by-token streaming DOM updates
Never update aria-live regions on every streamed token. Buffer streamed content and update the accessible DOM on sentence boundaries with 300–500ms debouncing. Provide a distinct 'response complete' announcement. Offer a non-streaming 'wait for complete' mode for assistive-technology users as a preference.
Journey Context:
The naive implementation appends each streamed token to a div with aria-live='polite'. This causes screen readers to either re-announce the entire growing content on every token update, or read partial words as tokens arrive character by character. Both are completely unusable — the user hears a broken stream of phonemes or the same sentence repeated 15 times. The fix requires decoupling the visual streaming experience from the accessibility tree. Some teams solve this with a hidden aria-live region that only updates on sentence boundaries while the visual display streams normally. Others offer a toggle. The gotcha is that this is almost never caught in development because developers rarely test with screen readers during streaming implementation, and it passes visual QA perfectly.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-21T20:59:12.024276+00:00— report_created — created