Announce dynamic interface changes

Dynamic UI & Live Announcements

In Single-Page Applications (SPAs) and reactive interfaces, content changes without a full page reload. Sighted users notice a toast, a search count update, a skeleton spinner or a route change peripherally; screen reader users only know a non-focused part of the page changed if focus moves deliberately or an ARIA live region announces it (WCAG 4.1.3 Status Messages, 2.4.2 Page Titled, 2.4.3 Focus Order).

1. Client-Side Route Transitions (SPA Navigation)

When a user clicks a link that triggers client-side routing without a browser page reload:

1. Update document.title immediately to reflect the new view ("<Page Name> — <Product Name>", WCAG 2.4.2).
2. Reset or manage focus deliberately:
   • Either move focus to the new view's primary <h1> (with tabindex="-1" and no distracting visual focus ring unless navigated by keyboard) or to the main content container, or announce the new page title via a polite route announcer while resetting scroll and next-Tab position to the top of the page.
   • Never leave focus stranded on a destroyed navigation menu item or at the bottom of the previous page's footer.

2. ARIA Live Regions (aria-live, role="status", role="alert")

Live regions announce dynamic text changes without moving keyboard focus:

• Polite announcements (role="status" or aria-live="polite"):
  • Waits until the screen reader finishes speaking the current sentence before announcing.
  • Use for: "Changes saved", "12 results found", "Item added to cart", filter/search result counts, background job completion and non-blocking toast notifications.
• Assertive announcements (role="alert" or aria-live="assertive"):
  • Interrupts current speech immediately.
  • Use sparingly — only for critical, time-sensitive errors, session expiration warnings or immediate connection failures.
• aria-atomic="true|false":
  • Set aria-atomic="true" on short status containers (such as "Showing 1 to 10 of 42 results") so the entire phrase is read rather than just the changed number "42".

3. Making Live Regions Reliably Announce Across Browsers

A common bug is mounting a <div aria-live="polite">Saved!</div> into the DOM at the exact same moment as its text: many browser + screen-reader pairs ignore initial text inside a newly inserted live region.

• Keep the live region container mounted in the DOM ahead of time (empty), then inject or update its text content when the status event occurs.
• Clear and re-populate (or toggle between two polite buffers) if the exact same status message needs to be announced twice in a row.
• Debounce noisy updates: for live search-as-you-type or streaming output, debounce status announcements (e.g., 500–800 ms after typing stops) so the screen reader is not flooded on every keystroke.
• Never announce streaming LLM tokens character-by-character in a live region — announce when generation starts ("Generating response...") and when it completes or pauses for input.

4. Toast Notifications & Async Loading States

• Toasts with interactive actions (e.g., "Task archived — Undo"):
  • A polite status message alone does not let a keyboard user click "Undo" before the toast auto-dismisses.
  • Respect WCAG 2.2.1 (Timing Adjustable): pause auto-dismiss on :hover and :focus-within, provide a keyboard shortcut or accessible notification center for actionable toasts, or keep Undo available for a sufficient duration.
• Loading / Busy states:
  • Use aria-busy="true" on the region being updated and provide a concise polite announcement when long-running loading begins and finishes, rather than leaving an unlabeled spinner.