Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(AST-086): status announcements have one owner and use the shared channel (#7792)

Cindy Zhang31e06f44a72c
diff --git a/docs/specs/AST-086-status-announcements/spec.md b/docs/specs/AST-086-status-announcements/spec.md
new file mode 100644
index 0000000000..a8a5cfa318
--- /dev/null
+++ b/docs/specs/AST-086-status-announcements/spec.md
@@ -0,0 +1,198 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-086
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-15
+phase: accepted
+owners: [cixzhang]
+affects_architecture: [architecture:react-component-runtime]
+affects_families: [family:input-fields]
+affects_contributing: []
+affects_consumer_docs:
+ [
+ useAnnounce,
+ Toast,
+ ChatSystemMessage,
+ ChatTypingIndicator,
+ Comments,
+ FieldStatus,
+ Banner,
+ ]
+---
+
+# Status announcement delivery system spec
+
+## Intent
+
+A screen-reader user hears each status change once, when it happens, at the
+right urgency. A message is never lost because its live region appeared
+together with its text, and never heard twice because two parts of the page
+both claim it.
+
+Builders get one rule for every component that reports status: name the one
+owner of the message, and deliver transient messages through the shared
+announcement channel.
+
+## Non-goals
+
+- Which events a component reports. Component and family records decide what
+ is a status message; this record decides how it is delivered.
+- Exact wording. Text comes from `architecture:internationalization`.
+- Focus movement. A status message never moves focus; focus rules stay with
+ `architecture:interaction-modality` and component records.
+- Modal alerts that take focus, such as AlertDialog. They are not status
+ messages.
+- Spoken output on a specific screen reader. `spec:AST-009` owns that evidence.
+- Where the channel is hosted while a native modal makes the rest of the page
+ inert. `spec:AST-003` (FR15, FR18, FR20) owns hosting.
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Requirements
+
+- **FR1 — One owner per message.** Every status message Astryx announces has
+ exactly one announcement owner. No other element that shows the same words
+ carries a live role (`status`, `alert`, `log`) or `aria-live`.
+- **FR2 — Transient messages use the shared channel.** When the element that
+ shows a message mounts, unmounts, or is replaced together with its text, the
+ owner announces through the shared announcement channel, except as FR4 and
+ FR10 provide. The new element
+ MUST NOT carry a live role or `aria-live`.
+- **FR3 — Live roles only on persistent containers.** A component MAY own a
+ live role only on an element that stays mounted while its content changes.
+ It MUST NOT mount that element already holding the text to announce.
+- **FR4 — A live container owns content added inside it.** Content added inside
+ a mounted live container is delivered by that container, at its urgency. An
+ element added with that content MUST NOT carry its own live role or announce
+ the same content through the channel. A persistent component region that FR3
+ allows, such as Button's loading region or an input's invalid-entry region,
+ keeps its own role and delivers its own content at its own urgency.
+- **FR5 — Urgency.** Outside a live container, errors and time-critical
+ failures use the assertive channel. All other status messages use the polite
+ channel. Inside a mounted live container, FR4 applies.
+- **FR6 — Once per occasion.** An occasion is one state transition or one user
+ action. The owner announces once per occasion. Rerender, StrictMode replay,
+ and an update to the same value do not repeat it. A new occasion with the
+ same words announces again.
+- **FR7 — Shown words stay readable.** Delivering through the channel does not
+ hide the visible message from assistive technology. The visible element stays
+ available for browse mode and `aria-describedby`. The announced words match
+ the shown words.
+- **FR8 — Indicators inside an owner are silent.** A visual indicator composed
+ inside a component that owns the task, such as a Spinner in a busy control,
+ announces nothing and carries no live role. The owning component announces its busy state once per busy start (FR6), through the channel or through a persistent region that FR3 allows.
+ A standalone indicator is its own owner and follows FR2.
+- **FR9 — One shared channel per document.** The channel is one polite and one
+ assertive region per document. They are created empty, stay mounted for the
+ document's lifetime, and clear their text shortly after each announcement so
+ stale text does not linger. `useAnnounce` is the public way to reach it.
+- **FR10 — Modal-hosted owners keep their own channel.** While the shared
+ channel is not admitted to modal hosting, a globally hosted owner that
+ `spec:AST-003` rehosts above native modals (FR16, FR18) announces through its
+ own persistent polite and assertive containers, which move with it. FR3, FR5,
+ and FR6 apply to those containers.
+
+### Platform support
+
+- Supported feature/engine floor: the package's supported browsers.
+- Unsupported behavior: without a document (server render), announcing is a
+ no-op and renders nothing.
+- While a native modal dialog is open, the shared channel on the page body is
+ not exposed to assistive technology until `spec:AST-003` admits it to modal
+ hosting. Owners rehosted above the modal use their own containers (FR10).
+ Until then, a busy owner rendered inside a native modal announces its busy
+ state through a persistent region inside that modal (FR3, FR8). Other
+ delivery inside native modals is outside this record.
+- Browser evidence: DOM and accessibility-tree checks prove routing (FR1–FR5,
+ FR7–FR10). Spoken timing, order, and repetition (FR6 on real AT) require
+ `spec:AST-009` FR4 evidence.
+
+## Current-state impact
+
+- `component:FieldStatus` AR1 and `component:Banner` FR8 defer to FR4 inside a
+ mounted live container; elsewhere they already match FR2, FR5, and FR7.
+- `architecture:react-component-runtime` INV5 gains the authority it requires
+ for the document-owned channel (FR9). INV2 and INV3 already require FR6.
+- Toast: the viewport announces each toast through the body-level channel, and
+ each visible card also carries `role="status"`/`role="alert"` with
+ `aria-live`. Under FR1 and FR10 the viewport's own persistent live containers,
+ which `spec:AST-003` rehosts above native modals, is the one owner, and the
+ card drops its live role. A toast shown over a Dialog stays announced.
+- Switch: busy is announced through the channel, and the thumb Spinner also
+ mounts with `role="status"`. Under FR8 the thumb Spinner is silent. Under FR6
+ StrictMode replay does not repeat the busy announcement.
+- Spinner (standalone): mounts with `role="status"` and its name. Under FR2 it
+ announces its label through the channel when it appears. The role and name it
+ exposes without a live role are outside this record.
+- `family:input-fields` members and other busy controls (TextInput, TextArea,
+ Selector, MultiSelector, ComplexSelector, Typeahead, Tokenizer, the date and
+ time inputs, FileInput, CheckboxInput, CommandPaletteInput,
+ DropdownMenuSubMenu, Thumbnail, and the lab EmojiPicker, Schedule, and
+ Comments history loaders): each composes a Spinner with
+ `role="status"` inside the busy control. Under FR8 that Spinner is silent and
+ each control announces its own busy state through the channel. Switch
+ already does. CommandPalette opens as a native modal, so it announces each busy
+ start, including its load on opening or clearing the query, through a
+ persistent region inside its dialog (FR3).
+- ChatMessageList: its top loading Spinner is a `role="status"` child of the
+ log. Under FR4 and FR8 it is silent, and ChatMessageList announces its loading
+ through the channel.
+- EmptyState, the ChatComposer status bar, and the chat trigger menu's loading
+ row: each mounts a live role together with its text. Under FR2 the message
+ goes through the channel and the element carries no live role.
+- Button: its persistent loading region fits FR3, except when a Button first
+ renders loading and the region mounts holding its text. Inside a live
+ container it keeps its role and urgency (FR4).
+- DateInput, DateTimeInput, TimeInput, and NumberInput: their persistent
+ assertive invalid-entry regions fit FR3 and, inside a live container, keep
+ their role and urgency (FR4).
+- ChatSystemMessage: forces `role="status"` inside the `role="log"` list. Under
+ FR4 the log delivers it; dividers and dates are ordinary log content.
+- ChatTypingIndicator (lab): mounts with `role="status"` and text. It follows
+ FR4 inside a live log, otherwise FR2.
+- Comments (lab): its error banners and progress label mount live roles
+ together with their text. Inside a live log they follow FR4; otherwise FR2.
+- `spec:AST-037` FR9 (Timer adds no unsolicited live region) already conforms.
+- Consumer tests that query these elements by `status` or `alert` role change.
+ Release notes name each affected component.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| FR1, FR4 | Shared test: one live owner per announced message | Toast shown; busy Switch; system notice, FieldStatus error, and failure Banner inside a chat log; busy Button and invalid DateInput inside a chat log (pass) | A live role on a second element, or a channel announcement of content added inside a live container, fails |
+| FR2, FR3 | Shared test: no live element mounts holding its text | Conditional status, toast card, standalone Spinner | Mounting `role="status"` with text fails |
+| FR5 | Channel routing tests | Error, warning, success, loading | Routing an error to polite, or a success to assertive, fails |
+| FR6 | StrictMode and rerender tests on the channel spy | Busy start, repeated rerender, same-value update, new occasion | Two announcements for one occasion, or none for a new one, fails |
+| FR7 | Accessibility-tree check of the visible message | FieldStatus attached/detached, toast card | Hiding the visible text or a word mismatch fails |
+| FR8 | Shared test: no live role inside a busy owner; channel spy on the owner | Busy TextInput, Selector, Switch thumb, ChatMessageList loader, busy CommandPalette (region inside its dialog) | A composed indicator with a live role or its own announcement, or a busy owner that announces nothing, fails |
+| FR9 | `useAnnounce` tests | First use, many components, region removed, server render | A second region pair, or stale text after the clear delay, fails |
+| FR10 | Accessibility-tree check with a Dialog open | Info and error toast shown over an open Dialog | A toast that reaches only the body-level channel, or no exposed live container, fails |
+| FR6 (AT) | `spec:AST-009` real-AT receipt | Toast, busy Switch, chat notice | Missing, repeated, or out-of-order speech fails |
+
+## Decision log
+
+### DEC-1 — One owner per message, delivered through the shared channel
+
+**Reference:** `spec:AST-086/DEC-1`
+**Decider:** cixzhang, 2026-10-15
+
+Several components show status while also claiming it in a second place, or
+mount a live region already holding its text. Screen-reader users then hear a
+message twice or not at all. One owner and one shared, always-mounted channel
+removes both failures with a single rule, and matches the delivery
+`component:FieldStatus` already uses.
+Owners that `spec:AST-003` rehosts above native modals keep their own containers
+until the shared channel can be hosted there (FR10).
+
+Rejected: delivering transient messages through each component's own live
+region — the page gains many competing regions and two-owner duplicates recur.
+
+## Open questions
+
+None.
diff --git a/packages/core/src/Banner/Banner.spec.md b/packages/core/src/Banner/Banner.spec.md
index 573f0acb25..f007291bb8 100644
--- a/packages/core/src/Banner/Banner.spec.md
+++ b/packages/core/src/Banner/Banner.spec.md
@@ -42,29 +42,29 @@ separately targetable surface. The status and content targets remain unchanged.
- Released default preserved: `no` — Banner no longer derives a live-region role from visual status
- Compatibility class: breaking accessibility-semantic correction; visual output, DOM structure, props, theming targets, and interaction behavior are unchanged
- Controlled/uncontrolled behavior: unchanged
-- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption
+- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption. Inside a mounted live container, `spec:AST-086` FR4 applies instead.
Consumer migration instructions belong in consumer docs and release notes.
### DEP-0007 — Deprecate live-region roles derived from `status`
-| Field | Value |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id | `DEP-0007` |
-| cleanup | `CLN-0015` |
-| package | `@astryxdesign/core` |
-| surface | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role` |
-| old contract | Visual `status` selects the live-region role of the Banner root |
-| replacement | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root |
-| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner` |
-| warning | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29) |
-| migration | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"` |
-| codemod | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes |
-| downstream | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors |
-| transition | no prior transition |
-| state | `proposed` |
-| open decision | Banner FR and DEC entries that make `status` visual-only |
-| target plan | `CLN-0015` in the next minor release |
+| Field | Value |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0007` |
+| cleanup | `CLN-0015` |
+| package | `@astryxdesign/core` |
+| surface | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role` |
+| old contract | Visual `status` selects the live-region role of the Banner root |
+| replacement | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |
+| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner` |
+| warning | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29) |
+| migration | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"`. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |
+| codemod | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes |
+| downstream | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |
+| transition | no prior transition |
+| state | `proposed` |
+| open decision | Banner FR and DEC entries that make `status` visual-only |
+| target plan | `CLN-0015` in the next minor release |
### CLN-0015 — Banner renders no live-region role by default
@@ -105,16 +105,16 @@ prop vocabulary or extensibility rule changes.
The requirements below describe the current implementation and its additive
frame target contract.
-| ID | Invariant | Basis | Contract state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
-| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |
-| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |
-| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |
-| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |
-| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |
-| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element. | Owner decision; current source and tests | Current behavior |
-| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged. | Current target inventory; compatibility policy | Current behavior |
-| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role. Async outcomes MUST announce from the transition handler through `useAnnounce`; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior |
+| ID | Invariant | Basis | Contract state |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
+| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |
+| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |
+| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |
+| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |
+| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |
+| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element. | Owner decision; current source and tests | Current behavior |
+| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged. | Current target inventory; compatibility policy | Current behavior |
+| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role, except on a Banner added inside a mounted live container (`spec:AST-086` FR4). Async outcomes MUST announce from the transition handler through `useAnnounce`, except inside a mounted live container, where `spec:AST-086` FR4 applies; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior |
### Allowed variation
@@ -154,11 +154,15 @@ runtime work.
`status` communicates visual category through color and icon; it does not choose
announcement urgency. Banner renders no live-region role by default. A caller may
provide `role="status"` through the standard DOM surface when the visible banner
-is intentionally a persistent semantic mirror. Async outcomes use `useAnnounce`
+is intentionally a persistent semantic mirror, except on a Banner added inside a
+mounted live container. Async outcomes use `useAnnounce`
from the transition handler, which writes into a previously mounted live region;
+inside a mounted live container, that container delivers them
+(`spec:AST-086` FR4);
a Banner mounted together with its message is not a reliable announcement.
`role="alert"` remains available as an explicit native role, but is reserved for
-genuinely urgent content that should interrupt current speech.
+genuinely urgent content that should interrupt current speech; it is not used on
+a Banner added inside a mounted live container.
Dismissal focus handoff, disclosure controls, and accessible control names remain
unchanged.
@@ -247,8 +251,9 @@ placement and would imply that the target must remain on the outermost element.
Banner status selects color and icon only. It does not assign `role="status"` or
`role="alert"`. Async outcomes announce through `useAnnounce` from the transition
handler so the message reaches a persistent live region rather than one mounted
-with its content. An explicit native role remains available through BaseProps for
-a persistent semantic mirror or the rare genuinely urgent alert.
+with its content; inside a mounted live container, `spec:AST-086` FR4 applies. An explicit native role remains available through BaseProps for
+a persistent semantic mirror or the rare genuinely urgent alert, except on a
+Banner added inside a mounted live container.
Rejected: deriving alert urgency from `warning` or `error`. Severity and urgency
are independent, and a static error present on first paint is not an event that
diff --git a/packages/core/src/FieldStatus/FieldStatus.spec.md b/packages/core/src/FieldStatus/FieldStatus.spec.md
index 4a73e5c7e0..1d701cadbc 100644
--- a/packages/core/src/FieldStatus/FieldStatus.spec.md
+++ b/packages/core/src/FieldStatus/FieldStatus.spec.md
@@ -38,7 +38,8 @@ detached presentations; consumer usage remains documented in
- Released default preserved: `yes`
- Compatibility class: additive documentation only; runtime, DOM, styling, and
- public API remain unchanged
+ public API remain unchanged, except that delivery inside a mounted live
+ container follows `spec:AST-086` FR4
- Controlled/uncontrolled behavior: not applicable
- Migration decision: direct `FieldStatus variant="tooltip"` support is rejected.
`tooltip` remains a field-family sentinel that MUST be handled before rendering
@@ -127,7 +128,7 @@ intentional decision.
- **AR1 — Programmatic announcement channel.** Errors MUST update the persistent
assertive region; warnings and successes MUST update the persistent polite
region, including on first mount and when message or type changes, without
- moving focus.
+ moving focus. Inside a mounted live container, `spec:AST-086` FR4 applies.
- **AR5 — Assistive-technology output.** Claims about whether, when, or how the
message is spoken or presented in braille MUST be verified through the real-AT
evidence process in `spec:AST-009`; DOM and accessibility-tree checks prove