AddThisFeature

Live Region Manager

Announce the things that change on their own, once each, at the right urgency.

involved Components & Primitives

What it adds

A single managed channel through which asynchronous status — saves, errors, filter results, background jobs — reaches screen reader users.

What your agent is told to do

5
  1. 1

    Find every place the app changes the screen without a user action immediately preceding it: autosave, polling, validation on blur, filter result counts, upload progress, toast notifications, and background job completion.

  2. 2

    Route all of those through one manager with two channels — polite for status the user can absorb when they pause, assertive for errors and anything that interrupts what they were about to do — and default everything to polite.

  3. 3

    Keep the live regions themselves mounted and empty in the shell from first paint, and change only their text content. A region inserted at the moment of the announcement is frequently missed entirely.

  4. 4

    Collapse repeated and superseded messages: an identical message within a short window is dropped, and a progress or count message replaces the previous one rather than queueing behind it.

  5. 5

    Do not announce anything the user has just caused directly and can already perceive — a button label changing under their own click, or a field they just typed into. Duplicating that turns the channel into noise and trains people to ignore the announcements that matter; visually hidden text used by these messages should come from Screen Reader Only Utility rather than being styled here.

Edge cases it handles

7
  • Polite and assertive must stay in separate regions, because mixing them means an error waits behind a queue of routine status, and routine status interrupts the user mid-sentence.
  • The same message posted twice in quick succession is read twice; deduplicate on message text within a short window, and expose an explicit override for the rare case where a repeat genuinely carries information.
  • Superseded content must be replaced predictably — a filter count or an upload percentage should overwrite the region rather than append, or the user hears every intermediate value in order and the current one last.
  • Announcing every minor event makes the channel useless. Set a threshold for what qualifies as status worth interrupting for, and let ordinary rendering carry the rest.
  • Rapid successive changes need throttling with a trailing announcement so the final state is spoken, not merely the first of a burst.
  • A route change should reset the regions, otherwise a stale message from the previous screen is read against the new one.
  • Emptying and refilling a region in the same frame is often coalesced and never announced; separate the clear and the set.

Definition of done

8
  • All asynchronous status in the app is announced through one manager rather than per-component regions.
  • Polite and assertive messages occupy separate persistent regions present from first paint.
  • Identical messages within the deduplication window are announced once.
  • Progress and count messages replace their predecessor instead of queueing.
  • Announcements do not duplicate feedback the user's own action already conveys.
  • Regions are cleared on route change and no stale message carries across screens.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.