Skip to content

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

TypeScript

fix(Banner): role="alert" covers the urgent message only; bind the urgent alert states (#6779)

Cindy Zhangf8640a4eafdf
diff --git a/.changeset/banner-alert-message-only.md b/.changeset/banner-alert-message-only.md
new file mode 100644
index 0000000000..e2d27723c4
--- /dev/null
+++ b/.changeset/banner-alert-message-only.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Banner: `role="alert"` now sits on the title and description only, not on the whole banner, so an urgent alert holds only its message (`component:Banner` FR8; WCAG 2.2 4.1.3 Status Messages). The dismiss and expand controls, their tooltips, a caller's action, and the supporting content are outside the alert. ARIA attributes passed with `role="alert"`, such as `aria-label`, move with it. Other roles still land on the banner frame. Use `role="alert"` only for an urgent message, and announce every other message with `useAnnounce`. No visual change: the banner renders the same pixels as before.
+
+@cixzhang
diff --git a/apps/storybook/stories/AlertA11y.stories.tsx b/apps/storybook/stories/AlertA11y.stories.tsx
new file mode 100644
index 0000000000..4a203241be
--- /dev/null
+++ b/apps/storybook/stories/AlertA11y.stories.tsx
@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AlertA11y.stories.tsx
+ * @input Uses the Banner alert-state binding inventory and render map
+ * @output One checked-in reproduction story for every Banner alert contract state
+ * @position Stable browser fixtures required by AST-009 FR30 and AST-021
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {BANNER_ALERT_STATE_RENDERS} from '../../../packages/core/src/Banner/__tests__/Alert.a11y.renders';
+import {BANNER_ALERT_BINDING_STATES} from '../../../packages/core/src/Banner/__tests__/Alert.a11y.states';
+
+function alertStory(id: keyof typeof BANNER_ALERT_STATE_RENDERS): StoryObj {
+ const state = BANNER_ALERT_BINDING_STATES.find(
+ candidate => candidate.id === id,
+ );
+ if (state == null) {
+ throw new Error(`no Banner alert binding state "${id}"`);
+ }
+ return {
+ name: `${state.binding} — ${state.id}`,
+ render: () => BANNER_ALERT_STATE_RENDERS[id](),
+ };
+}
+
+const meta: Meta = {
+ title: 'a11y/Alert pattern',
+ tags: ['no-visual'],
+ parameters: {
+ docs: {
+ description: {
+ component:
+ 'Actual Banner states that explicitly request urgent alert semantics. Browser evidence checks role, assertive channel, exposed text, and focus preservation, and reports atomicity; speech and timing remain AST-009 evidence.',
+ },
+ },
+ },
+};
+
+export default meta;
+
+export const BannerErrorAlertMounted = alertStory('banner-error-alert-mounted');
+export const BannerWarningAlertDismissible = alertStory(
+ 'banner-warning-alert-dismissible',
+);
+export const BannerWarningAlertCollapsible = alertStory(
+ 'banner-warning-alert-collapsible',
+);
+export const BannerWarningAlertOpen = alertStory('banner-warning-alert-open');
+export const BannerWarningAlertAlwaysVisible = alertStory(
+ 'banner-warning-alert-always-visible',
+);
+export const BannerErrorAlertEndContent = alertStory(
+ 'banner-error-alert-end-content',
+);
+export const BannerErrorAlertDescription = alertStory(
+ 'banner-error-alert-description',
+);
diff --git a/docs/specs/AST-086-status-announcements/spec.md b/docs/specs/AST-086-status-announcements/spec.md
index 7bdf6ec09e..b4ff63da88 100644
--- a/docs/specs/AST-086-status-announcements/spec.md
+++ b/docs/specs/AST-086-status-announcements/spec.md
@@ -79,12 +79,16 @@ announcement channel.
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, FR10,
- FR11, and FR14 provide. The new element
- MUST NOT carry a live role or `aria-live`.
+ owner announces through the shared announcement channel, except as FR3 (an
+ urgent Banner's `role="alert"` message), FR4, FR10, FR11, and FR14 provide.
+ The new element
+ MUST NOT carry a live role or `aria-live`, except an urgent Banner's
+ `role="alert"` message (FR3).
- **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.
+ It MUST NOT mount that element already holding the text to announce, except
+ an urgent Banner's `role="alert"` message, delivered at FR5's assertive
+ urgency.
- **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
@@ -321,9 +325,10 @@ announcement channel.
FR3). Typeahead and CommandPalette announce their empty state after page load and are otherwise unchanged.
- `component:FieldStatus` AR1 is unchanged: a field message announces on first
mount, because it reports the field's state when the field appears.
-- `component:Banner` FR8 is unchanged: the caller announces an async outcome
- from its transition handler, because only the caller knows whether a Banner
- is a new outcome or persistent content. FR11 and FR12 cover components that
+- `component:Banner` FR8: the caller announces an async outcome from its
+ transition handler, because only the caller knows whether a Banner is a new
+ outcome or persistent content; an urgent message may instead carry
+ `role="alert"`, which Banner places on its message element (FR2, FR3). FR11 and FR12 cover components that
announce their own content.
- `useAnnounce`: messages written in the same frame are joined instead of the
last one replacing the others, except from a `hasReplace` instance (FR9).
diff --git a/docs/specs/components/Banner/Banner.spec.md b/docs/specs/components/Banner/Banner.spec.md
index f3bd93599e..21a3e674fd 100644
--- a/docs/specs/components/Banner/Banner.spec.md
+++ b/docs/specs/components/Banner/Banner.spec.md
@@ -13,6 +13,8 @@ review_triggers: [public-api, behavior, layout, theming, accessibility]
verified_by:
[
packages/core/src/Banner/Banner.test.tsx,
+ packages/core/src/Banner/__tests__/Alert.a11y.test.tsx,
+ packages/core/src/Banner/__tests__/Alert.a11y.chromium.spec.ts,
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
@@ -26,7 +28,7 @@ architecture:
architecture:theme-compilation,
]
contributing: []
-system_specs: [spec:AST-009]
+system_specs: [spec:AST-009, spec:AST-020, spec:AST-021]
---
# Banner component contract
@@ -42,29 +44,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 for the live-region change (DEP-0007), whose visual output, DOM structure, props, theming targets, and interaction behavior are unchanged. FR9 is a visual change: the Info status surface fills with `--color-info-muted` and built-in content takes the on-muted roles; props, DOM structure, and theming targets stay the same
- 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. Inside a mounted live container, `spec:AST-086` FR4 applies instead.
+- Migration decision: announce async outcomes in their transition handler with `useAnnounce`, and reserve `role="alert"` for urgent messages, which Banner places on its message element (FR8). 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. 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 |
+| 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. An urgent message passes `role="alert"`, which Banner places on its message element (FR8). 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`, `useAnnounce` for other messages, and `role="alert"` for an urgent message. 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 with an urgent message passes `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 `role="alert"` only for an urgent message. 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
@@ -111,17 +113,17 @@ 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, 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 |
-| FR9 | The status surface fills with the matching `--color-<status>-muted` role (`--color-info-muted` for Info) and paints its built-in title, description, icon, collapse, and dismiss content with the matching `--color-on-<status>-muted` role. Banner supplies that semantic foreground context to each built-in Button element without changing Button-owned geometry or interaction layers; a sibling tooltip keeps Button's ordinary theme color. Consumer-provided `endContent` remains untouched. | Status-role architecture; Banner and Button source/tests | 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`. The exception is `role="alert"` and the `aria-*` attributes passed with it, which land on the message element (FR8). | 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. A Banner whose message is urgent (an error or time-critical failure the person must act on now) MAY carry `role="alert"`, which the caller passes. Banner places that role, and the `aria-*` attributes passed with it, on its message element, which holds only the title and the description, and never on the frame, the end area, or the content area. Every other Banner announcement goes through `useAnnounce` from the transition that produced it, at the urgency `spec:AST-086` FR5 sets. A Banner with `role="alert"` is not also announced through `useAnnounce` (`spec:AST-086` FR1). Where the role lands changes nothing visual: no element, style or layout changes for it. Inside a mounted live container, `spec:AST-086` FR4 applies and the Banner carries no live role. | Accessibility Checklist §Announcements; owner decision | Current behavior |
+| FR9 | The status surface fills with the matching `--color-<status>-muted` role (`--color-info-muted` for Info) and paints its built-in title, description, icon, collapse, and dismiss content with the matching `--color-on-<status>-muted` role. Banner supplies that semantic foreground context to each built-in Button element without changing Button-owned geometry or interaction layers; a sibling tooltip keeps Button's ordinary theme color. Consumer-provided `endContent` remains untouched. | Status-role architecture; Banner and Button source/tests | Current behavior |
### Allowed variation
@@ -160,21 +162,28 @@ action row of two or more actions.
## Accessibility contract
`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, 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; it is not used on
-a Banner added inside a mounted live container.
+announcement urgency. An urgent Banner's message element carries `role="alert"`;
+its text is the title and the description, separated by a space in the DOM. Controls,
+their tooltips, `endContent` and the content area sit outside it. Other Banner
+messages are announced through `useAnnounce`, and Banner renders no live role
+for them. `useAnnounce` writes into a previously mounted live region; inside a
+mounted live container, that container delivers them (`spec:AST-086` FR4). Any
+other Banner message mounted together with its Banner is not a reliable
+announcement.
Dismissal focus handoff, disclosure controls, and accessible control names remain
unchanged.
+The dedicated alert-state binding exercises only Banner renders that explicitly
+request `role="alert"` through the standard DOM surface. It checks the shared
+status-message contract's DOM, accessibility-tree, and focus-preservation
+outcomes without claiming what assistive technology announces. Announcement
+wording and timing remain under AST-009. The binding reports whole-region
+atomicity but does not fail on it, because that expectation is advisory. Every
+state passes every required expectation: in the plain, dismissible, collapsed,
+open, always-visible, caller-action, and description states, the alert region
+holds the title and the description only.
+
## Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
@@ -228,15 +237,16 @@ context on the Button element, and it does not restyle a consumer-provided
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
-| FR1, FR7 | `Banner.test.tsx` and `themingTargets.test.ts` | Status surface, content surface, current target axes | Moving, removing, or changing an existing target breaks current assertions. | `audit:Banner/theming` |
-| FR2, FR3, FR4 | `Banner.test.tsx` plus current source inspection | Flat/elevated card and elevated section | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state. | `audit:Banner/surfaces` |
-| FR5 | Compiler output plus browser/computed-style evidence | Card with and without content; elevated card | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does. | `audit:Banner/radius` |
-| FR6, FR7 | Implementation PR target, compiler, probe, and component tests | Card/section across none, low, med, and high elevation | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target. | `audit:Banner/theming` |
-| FR8 | `Banner.test.tsx`, consumer docs, Accessibility Checklist A6 | Default info/success/warning/error; explicit status and alert roles | A visual status creates a live region, an explicit role is dropped, or docs tell builders to announce by conditionally mounting Banner. | `audit:Banner/a11y` |
-| FR9 | `Banner.test.tsx` plus Button tooltip and custom-end-content assertions | Four statuses; built-in collapse/dismiss; tooltip; consumer action | Built-in content loses the matching on-muted role, a tooltip is repainted, Button interaction ownership changes, or consumer content is mutated. | `audit:Banner/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Eight anatomy entries and five current targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:Banner/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1, FR7 | `Banner.test.tsx` and `themingTargets.test.ts` | Status surface, content surface, current target axes | Moving, removing, or changing an existing target breaks current assertions. | `audit:Banner/theming` |
+| FR2, FR3, FR4 | `Banner.test.tsx` plus current source inspection | Flat/elevated card and elevated section | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state. | `audit:Banner/surfaces` |
+| FR5 | Compiler output plus browser/computed-style evidence | Card with and without content; elevated card | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does. | `audit:Banner/radius` |
+| FR6, FR7 | Implementation PR target, compiler, probe, and component tests | Card/section across none, low, med, and high elevation | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target. | `audit:Banner/theming` |
+| FR8 | `Banner.test.tsx`, consumer docs, Accessibility Checklist A6 | Default info/success/warning/error; explicit alert role on the message element | A visual status creates a live region, an explicit alert role is dropped or lands outside the message element, or docs tell builders to announce by conditionally mounting Banner. | `audit:Banner/a11y` |
+| FR8 alert state | `Alert.a11y.test.tsx` and `Alert.a11y.chromium.spec.ts` | Explicit urgent error; dismissible, collapsed, open, always-visible, caller-action, and description variants | Role, assertive channel, or focus preservation regresses across a message update; the alert region holds anything other than the title and the description, or the frame carries the role or its `aria-*` attributes. Atomicity is reported, not enforced. | `audit:Banner/a11y` |
+| FR9 | `Banner.test.tsx` plus Button tooltip and custom-end-content assertions | Four statuses; built-in collapse/dismiss; tooltip; consumer action | Built-in content loses the matching on-muted role, a tooltip is repainted, Button interaction ownership changes, or consumer content is mutated. | `audit:Banner/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Eight anatomy entries and five current targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:Banner/theming` |
## Decision log
@@ -261,12 +271,13 @@ placement and would imply that the target must remain on the outermost element.
**Decider:** cixzhang, 2026-09-24
-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; 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.
+Urgency is the caller's call, marked by `role="alert"`, and Banner scopes that
+alert to the message so assistive technology hears the authored words only.
+Every other message uses the standard announce module, so one owner announces
+each message.
+
+Rejected: a live role on the whole frame, which exposes control and tooltip
+text.
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/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index cf6e31de38..ff18625a3e 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -18,7 +18,7 @@ export const docs = {
{guidance: false, description: 'Use Banner for short-lived messages that disappear on their own; use Toast instead.'},
{guidance: false, description: 'Stack multiple banners with the same status; combine related messages into one banner.'},
{guidance: true, description: 'Set collapsible={false} when the user needs the content to act on the message, like the list of fields that failed validation. Keep the default toggle when the detail is long enough to bury the banner\'s own message.'},
- {guidance: true, description: 'Banner status controls color and icon only; it does not create a live region. Announce async outcomes from the transition handler with useAnnounce. Add an explicit role="status" only when the visible banner is intended as a persistent semantic mirror; reserve role="alert" for genuinely urgent, interruptive content.'},
+ {guidance: true, description: 'Banner status controls color and icon only; it does not create a live region. Announce async outcomes from the transition handler with useAnnounce. Pass role="alert" only for an urgent message the person must act on now: Banner puts it on the title and description, so controls, endContent and supporting content are not read as part of the alert. Do not also announce that message with useAnnounce.'},
{guidance: false, description: 'Rely on the status color or icon alone to carry meaning; say which status it is in the title text, because the icon is decorative to a screen reader.'},
],
anatomy: [
@@ -196,7 +196,7 @@ export const docsZh = {
{guidance: true, description: 'Keep titles short and scannable: "Payment failed" not "There was a problem processing your most recent payment."'},
{guidance: false, description: 'Use Banner for short-lived messages that disappear on their own; use Toast instead.'},
{guidance: false, description: 'Stack multiple banners with the same status; combine related messages into one banner.'},
- {guidance: true, description: 'Banner 的 status 仅控制颜色和图标,不创建实时区域。异步结果应在实际的状态转换处理函数中调用 useAnnounce。仅当可见 Banner 需要作为持久语义镜像时显式添加 role="status";只有真正紧急、需要打断当前朗读的内容才使用 role="alert"。'},
+ {guidance: true, description: 'Banner 的 status 仅控制颜色和图标,不创建实时区域。异步结果应在实际的状态转换处理函数中调用 useAnnounce。仅当消息紧急、用户必须立即处理时才传入 role="alert":Banner 会把它放在标题和描述上,因此控件、endContent 和补充内容不会作为警报的一部分被朗读。不要再用 useAnnounce 重复播报同一条消息。'},
{guidance: false, description: '不要只依赖 status 的颜色或图标传达含义;请在标题文本中明确说明状态,因为屏幕阅读器会忽略这个装饰性图标。'},
],
anatomy: [
@@ -285,7 +285,7 @@ export const docsDense = {
{guidance: true, description: 'Keep titles short: "Payment failed" not "There was a problem processing your payment."'},
{guidance: false, description: 'Use for auto-dismissing messages; use Toast instead.'},
{guidance: false, description: 'Stack multiple banners of the same status; combine into one.'},
- {guidance: true, description: 'Status controls color + icon only; Banner is non-live by default. Announce async outcomes from the transition handler with useAnnounce. Add role="status" only for a persistent semantic mirror; reserve role="alert" for genuinely urgent interruption.'},
+ {guidance: true, description: 'Status controls color + icon only; Banner is non-live by default. Announce async outcomes from the transition handler with useAnnounce. role="alert" only for urgent messages; it lands on title + description, not controls or content. Never both.'},
{guidance: false, description: 'Rely on status color or icon alone; state the status in the title text, since the icon is decorative to a screen reader.'},
],
anatomy: [
diff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsx
index 78ab2c1a9c..a81cf220c9 100644
--- a/packages/core/src/Banner/Banner.test.tsx
+++ b/packages/core/src/Banner/Banner.test.tsx
@@ -44,14 +44,65 @@ describe('Banner', () => {
}
});
- it('forwards an explicit persistent or alert role', () => {
- const {rerender} = render(
+ it('forwards an explicit non-alert role to the frame', () => {
+ const {container} = render(
<Banner status="info" title="Saved" role="status" />,
);
- expect(screen.getByRole('status')).toHaveTextContent('Saved');
+ expect(screen.getByRole('status')).toBe(container.firstElementChild);
+ });
+
+ it('puts an urgent role="alert" on the message: the title and the description only', () => {
+ const {container} = render(
+ <Banner
+ status="error"
+ title="Upload failed"
+ description="Check your network and try again."
+ role="alert"
+ isDismissable
+ endContent={<button type="button">Retry</button>}
+ collapsible={{defaultIsOpen: true}}>
+ Supporting details
+ </Banner>,
+ );
+ const alert = screen.getByRole('alert');
+ expect(container.firstElementChild).not.toHaveAttribute('role');
+ expect(alert.textContent).toBe(
+ 'Upload failed Check your network and try again.',
+ );
+ expect(alert).not.toContainElement(
+ screen.getByRole('button', {name: 'Retry'}),
+ );
+ expect(alert).not.toHaveTextContent('Supporting details');
+ });
+
+ it("moves an urgent alert's ARIA attributes onto the message with the role", () => {
+ const {container} = render(
+ <Banner
+ status="error"
+ title="Upload failed"
+ role="alert"
+ aria-label="Upload error"
+ />,
+ );
+ expect(screen.getByRole('alert', {name: 'Upload error'})).toHaveTextContent(
+ 'Upload failed',
+ );
+ expect(container.firstElementChild).not.toHaveAttribute('aria-label');
+ });
+
+ it('keeps ARIA attributes on the frame without an urgent alert', () => {
+ const {container} = render(
+ <Banner status="info" title="Saved" aria-label="Save status" />,
+ );
+ expect(container.firstElementChild).toHaveAttribute(
+ 'aria-label',
+ 'Save status',
+ );
+ });
- rerender(<Banner status="error" title="Failed" role="alert" />);
- expect(screen.getByRole('alert')).toHaveTextContent('Failed');
+ it('reads an urgent title without a description as the title alone', () => {
+ render(<Banner status="error" title="Upload failed" role="alert" />);
+ expect(screen.getByRole('alert').textContent).toBe('Upload failed');
});
it('renders default icon per status with aria-hidden', () => {
diff --git a/packages/core/src/Banner/Banner.tsx b/packages/core/src/Banner/Banner.tsx
index 8b6bea6cb1..566880f8ab 100644
--- a/packages/core/src/Banner/Banner.tsx
+++ b/packages/core/src/Banner/Banner.tsx
@@ -30,11 +30,10 @@
* default / controlled) lives on that one prop and is driven by the shared
* `useCollapsible` hook rather than local state.
*
- * Status controls visual treatment only. The root carries no live-region role by
+ * Status controls visual treatment only. Banner carries no live-region role by
* default: an async outcome is announced from its transition handler through
- * `useAnnounce`, while a caller that needs a persistent semantic mirror may
- * provide `role="status"` through BaseProps. `role="alert"` is explicit and
- * reserved for genuinely urgent content that should interrupt current speech.
+ * `useAnnounce`. A caller marks an urgent message with `role="alert"`, which
+ * lands on the message element (title and description), not on the frame.
*
* Title and description render as <div> (not <p>): they accept arbitrary
* ReactNode content, and <p> cannot legally contain block-level children
@@ -484,8 +483,10 @@ const elevationStyles = stylex.create({
* up state management for basic dismiss behavior.
*
* Status controls visual meaning only. The component adds no live-region role;
- * announce async outcomes from their transition handler with `useAnnounce`, or
- * pass an explicit role when a persistent semantic mirror is appropriate.
+ * announce async outcomes from their transition handler with `useAnnounce`.
+ * Pass `role="alert"` only for an urgent message: Banner places it on the
+ * title and description, so controls and supporting content are not read as
+ * part of the alert.
*
* @example
* ```
@@ -539,6 +540,7 @@ export function Banner({
ref,
onFocusCapture,
onPointerDownCapture,
+ role,
...rest
}: BannerProps) {
const t = useComponentTranslator();
@@ -638,6 +640,19 @@ export function Banner({
// hook's open state.
const showContent = hasChildren && (!isCollapsible || isExpanded);
const isCard = container === 'card';
+ // An urgent alert covers the authored message only, so controls, their
+ // tooltips and the content area stay out of what is announced.
+ const isUrgentAlert = role === 'alert';
+ // The alert's name and other ARIA states belong to the alert element.
+ const alertAriaProps: Record<string, unknown> = {};
+ const frameProps: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(rest)) {
+ if (isUrgentAlert && key.startsWith('aria-')) {
+ alertAriaProps[key] = value;
+ } else {
+ frameProps[key] = value;
+ }
+ }
return (
<div
@@ -658,7 +673,8 @@ export function Banner({
className,
style,
)}
- {...rest}>
+ role={isUrgentAlert ? undefined : role}
+ {...frameProps}>
{/* Header: colored status background — primary theme target ('banner') */}
<div
{...mergeProps(
@@ -702,6 +718,8 @@ export function Banner({
) : null}
</div>
<div
+ role={isUrgentAlert ? 'alert' : undefined}
+ {...alertAriaProps}
{...stylex.props(
styles.headerContent,
isRenderable(endContent) && styles.headerContentWithEndContent,
@@ -713,6 +731,10 @@ export function Banner({
)}>
{title}
</div>
+ {/* A flex container renders no whitespace-only text, so this space
+ only separates the title and the description in the alert's
+ text. */}
+ {isUrgentAlert && isRenderable(description) && ' '}
{isRenderable(description) && (
<div
{...mergeProps(
diff --git a/packages/core/src/Banner/__tests__/Alert.a11y.chromium.spec.ts b/packages/core/src/Banner/__tests__/Alert.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..4df3b06d5b
--- /dev/null
+++ b/packages/core/src/Banner/__tests__/Alert.a11y.chromium.spec.ts
@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/status-message\.|internal/a11y-spec/src/harness|packages/core/src/Banner/|packages/core/src/Button/|packages/core/src/Tooltip/|apps/storybook/stories/AlertA11y)
+
+/** Real-browser and accessibility-tree binding for Banner's urgent alert states. */
+
+import {
+ expect,
+ test,
+ type CDPSession,
+ type Locator,
+ type Page,
+} from '@astryxdesign/a11y-spec/playwright';
+import {
+ STATUS_MESSAGE_PATTERN,
+ blockingResults,
+ checkAccessibilitySpec,
+ formatFailures,
+ formatReport,
+ summarize,
+ unmatchedKnownFailures,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+ createChromiumHarness,
+ holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {BANNER_ALERT_KNOWN_FAILURES} from './Alert.a11y.known-failures';
+import {
+ BANNER_ALERT_BINDING_STATES,
+ type BannerAlertBindingState,
+} from './Alert.a11y.states';
+
+function transitionTestId(name: string): string {
+ return `alert-transition-${name}`;
+}
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+const BOUND_SUBJECT_ATTRIBUTE = 'data-a11y-binding-subject';
+
+function subjectFor(page: Page): Locator {
+ return page.locator(`[${BOUND_SUBJECT_ATTRIBUTE}]`);
+}
+
+async function mountState(
+ page: Page,
+ state: BannerAlertBindingState,
+): Promise<void> {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=${state.storyId}&viewMode=story`,
+ {waitUntil: 'load'},
+ );
+ await holdMotionStill(page);
+ await page.locator('[data-a11y-ready="true"]').waitFor({state: 'attached'});
+ const candidates = page.getByRole('alert', {includeHidden: true});
+ const count = await candidates.count();
+ if (count !== 1) {
+ throw new Error(`${state.id}: expected one alert subject, found ${count}`);
+ }
+ await candidates.first().evaluate((element, attribute) => {
+ element.setAttribute(attribute, '');
+ }, BOUND_SUBJECT_ATTRIBUTE);
+ await expect(subjectFor(page)).toHaveCount(1);
+}
+
+async function transition(page: Page, name: string): Promise<void> {
+ await page
+ .getByTestId(transitionTestId(name))
+ .evaluate(element => (element as HTMLElement).click());
+ await page.evaluate(
+ async () =>
+ new Promise<void>(resolve =>
+ requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+ ),
+ );
+}
+
+async function runState(
+ page: Page,
+ cdp: CDPSession,
+ state: BannerAlertBindingState,
+): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: STATUS_MESSAGE_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: BANNER_ALERT_KNOWN_FAILURES,
+ mount: async () => {
+ await mountState(page, state);
+ return createChromiumHarness({
+ page,
+ cdp,
+ subject: subjectFor(page),
+ related: {
+ 'focus-anchor': page.locator('[data-a11y-relation="focus-anchor"]'),
+ },
+ });
+ },
+ transition: async name => transition(page, name),
+ });
+}
+
+test('all Banner alert states have no unmatched known failure', async ({
+ page,
+}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const results: BindingResult[] = [];
+ for (const state of BANNER_ALERT_BINDING_STATES) {
+ results.push(await runState(page, cdp, state));
+ }
+ expect(unmatchedKnownFailures(BANNER_ALERT_KNOWN_FAILURES, results)).toEqual(
+ [],
+ );
+});
+
+for (const state of BANNER_ALERT_BINDING_STATES) {
+ test(`${state.binding} [${state.id}] — ${state.summary}`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const report = summarize(STATUS_MESSAGE_PATTERN, [result]);
+ // eslint-disable-next-line no-console -- the report is this run's artifact
+ console.log(formatReport(report));
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ expect(report.unrunLayers).toEqual([]);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+}
diff --git a/packages/core/src/Banner/__tests__/Alert.a11y.known-failures.ts b/packages/core/src/Banner/__tests__/Alert.a11y.known-failures.ts
new file mode 100644
index 0000000000..b10e3e3346
--- /dev/null
+++ b/packages/core/src/Banner/__tests__/Alert.a11y.known-failures.ts
@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Alert.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output Exact public-safe baseline failures for Banner's urgent alert binding
+ * @position Shared by the jsdom and Chromium bindings. Empty: the urgent
+ * message element holds the title and the description only (FR8).
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const BANNER_ALERT_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];
diff --git a/packages/core/src/Banner/__tests__/Alert.a11y.renders.tsx b/packages/core/src/Banner/__tests__/Alert.a11y.renders.tsx
new file mode 100644
index 0000000000..625aff9cc3
--- /dev/null
+++ b/packages/core/src/Banner/__tests__/Alert.a11y.renders.tsx
@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Alert.a11y.renders.tsx
+ * @input Uses Banner's public status, role, title, description, dismissibility,
+ * endContent, collapsible, and children surfaces
+ * @output One public-interface rendering for every Banner alert binding state
+ * @position Shared jsdom and checked-in Storybook fixture layer
+ */
+
+import {useState, type ComponentProps, type ReactElement} from 'react';
+import {Banner} from '../Banner';
+import {Button} from '../../Button';
+import type {
+ BannerAlertBindingState,
+ BannerAlertStateId,
+} from './Alert.a11y.states';
+import {BANNER_ALERT_BINDING_STATES} from './Alert.a11y.states';
+
+const transitionTestId = (name: string) => `alert-transition-${name}`;
+
+function collapsibleFor(
+ state: BannerAlertBindingState,
+): ComponentProps<typeof Banner>['collapsible'] {
+ switch (state.contentVisibility) {
+ case 'open':
+ return {defaultIsOpen: true};
+ case 'always-visible':
+ return false;
+ case 'collapsed':
+ case undefined:
+ return undefined;
+ }
+}
+
+function BannerAlertHarness({state}: {state: BannerAlertBindingState}) {
+ if (state.facts.kind !== 'live-region') {
+ throw new Error(
+ `${state.id}: Banner alert facts must describe a live region`,
+ );
+ }
+ const [title, setTitle] = useState(state.title);
+ return (
+ <div>
+ <span data-a11y-ready="true" hidden />
+ <button data-a11y-relation="focus-anchor" type="button">
+ Keep focus
+ </button>
+ <button
+ data-testid={transitionTestId('replace')}
+ type="button"
+ onClick={() => setTitle(state.replacementTitle)}>
+ Replace alert
+ </button>
+ <Banner
+ status={state.status}
+ role="alert"
+ title={title}
+ description={state.description}
+ isDismissable={state.dismissible}
+ endContent={
+ state.endContentLabel == null ? undefined : (
+ <Button label={state.endContentLabel} variant="ghost" />
+ )
+ }
+ collapsible={collapsibleFor(state)}>
+ {state.supportingContent}
+ </Banner>
+ </div>
+ );
+}
+
+export type BannerAlertStateRender = () => ReactElement;
+
+export const BANNER_ALERT_STATE_RENDERS: Record<
+ BannerAlertStateId,
+ BannerAlertStateRender
+> = Object.fromEntries(
+ BANNER_ALERT_BINDING_STATES.map(state => [
+ state.id,
+ () => <BannerAlertHarness state={state} />,
+ ]),
+) as Record<BannerAlertStateId, BannerAlertStateRender>;
+
+export {transitionTestId};
diff --git a/packages/core/src/Banner/__tests__/Alert.a11y.states.ts b/packages/core/src/Banner/__tests__/Alert.a11y.states.ts
new file mode 100644
index 0000000000..60dbba725f
--- /dev/null
+++ b/packages/core/src/Banner/__tests__/Alert.a11y.states.ts
@@ -0,0 +1,195 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Alert.a11y.states.ts
+ * @input Uses StatusMessageStateFacts from the shared accessibility contract
+ * @output The AST-021 inventory for Banner states that explicitly request urgent alert semantics
+ * @position Data-only binding inventory shared by jsdom, Storybook, and Chromium
+ */
+
+import type {StatusMessageStateFacts} from '@astryxdesign/a11y-spec';
+
+type AlertFacts = Extract<StatusMessageStateFacts, {kind: 'live-region'}>;
+
+export interface BannerAlertBindingDefinition {
+ readonly id: string;
+ readonly binding: 'Banner urgent alert';
+ readonly summary: string;
+ readonly facts: AlertFacts;
+ readonly status: 'warning' | 'error';
+ /** The title the caller authors first; the public update replaces it. */
+ readonly title: string;
+ readonly replacementTitle: string;
+ /** Caller-authored description, part of the urgent message. */
+ readonly description?: string;
+ readonly dismissible: boolean;
+ /** Label of a caller-supplied `endContent` action. */
+ readonly endContentLabel?: string;
+ /** Caller-authored supporting content, rendered as Banner children; outside the urgent message. */
+ readonly supportingContent?: string;
+ /**
+ * How Banner shows the supporting content: behind its default closed
+ * disclosure, behind a disclosure that starts open, or always visible.
+ */
+ readonly contentVisibility?: 'collapsed' | 'open' | 'always-visible';
+ readonly storyId: string;
+}
+
+/**
+ * The urgent message is the title and, when present, the description
+ * (component:Banner FR8). Controls, `endContent` and the supporting content
+ * area are outside it, open or closed.
+ */
+function alertFacts(
+ title: string,
+ replacementTitle: string,
+ description?: string,
+): AlertFacts {
+ const message = (value: string) =>
+ description == null ? value : `${value} ${description}`;
+ return {
+ kind: 'live-region',
+ role: 'alert',
+ politeness: 'assertive',
+ messageSource: 'text',
+ initialMessage: message(title),
+ message: message(title),
+ replacement: message(replacementTitle),
+ semanticTransitions: ['replace'],
+ };
+}
+
+export type BannerAlertStateId =
+ | 'banner-error-alert-mounted'
+ | 'banner-warning-alert-dismissible'
+ | 'banner-warning-alert-collapsible'
+ | 'banner-warning-alert-open'
+ | 'banner-warning-alert-always-visible'
+ | 'banner-error-alert-end-content'
+ | 'banner-error-alert-description';
+
+export const BANNER_ALERT_BINDING_STATES: ReadonlyArray<
+ BannerAlertBindingDefinition & {readonly id: BannerAlertStateId}
+> = [
+ {
+ id: 'banner-error-alert-mounted',
+ binding: 'Banner urgent alert',
+ summary:
+ 'an explicitly urgent error banner remains an assertive alert when its message is replaced',
+ facts: alertFacts('Upload failed', 'Connection failed'),
+ status: 'error',
+ title: 'Upload failed',
+ replacementTitle: 'Connection failed',
+ dismissible: false,
+ storyId: 'a11y-alert-pattern--banner-error-alert-mounted',
+ },
+ {
+ id: 'banner-warning-alert-dismissible',
+ binding: 'Banner urgent alert',
+ summary:
+ 'an explicitly urgent dismissible warning remains an assertive alert when its message is replaced',
+ facts: alertFacts('Session expires soon', 'Session has expired'),
+ status: 'warning',
+ title: 'Session expires soon',
+ replacementTitle: 'Session has expired',
+ dismissible: true,
+ storyId: 'a11y-alert-pattern--banner-warning-alert-dismissible',
+ },
+ {
+ id: 'banner-warning-alert-collapsible',
+ binding: 'Banner urgent alert',
+ summary:
+ 'an explicitly urgent warning with collapsed supporting content remains an assertive alert when its message is replaced',
+ facts: alertFacts('Session expires soon', 'Session has expired'),
+ status: 'warning',
+ title: 'Session expires soon',
+ replacementTitle: 'Session has expired',
+ dismissible: false,
+ supportingContent: 'Save your work to keep your changes.',
+ contentVisibility: 'collapsed',
+ storyId: 'a11y-alert-pattern--banner-warning-alert-collapsible',
+ },
+ {
+ id: 'banner-warning-alert-open',
+ binding: 'Banner urgent alert',
+ summary:
+ 'an explicitly urgent warning with open supporting content remains an assertive alert when its title is replaced',
+ facts: alertFacts('Session expires soon', 'Session has expired'),
+ status: 'warning',
+ title: 'Session expires soon',
+ replacementTitle: 'Session has expired',
+ dismissible: false,
+ supportingContent: 'Save your work to keep your changes.',
+ contentVisibility: 'open',
+ storyId: 'a11y-alert-pattern--banner-warning-alert-open',
+ },
+ {
+ id: 'banner-warning-alert-always-visible',
+ binding: 'Banner urgent alert',
+ summary:
+ 'an explicitly urgent warning with always-visible supporting content remains an assertive alert when its title is replaced',
+ facts: alertFacts('Session expires soon', 'Session has expired'),
+ status: 'warning',
+ title: 'Session expires soon',
+ replacementTitle: 'Session has expired',
+ dismissible: false,
+ supportingContent: 'Save your work to keep your changes.',
+ contentVisibility: 'always-visible',
+ storyId: 'a11y-alert-pattern--banner-warning-alert-always-visible',
+ },
+ {
+ id: 'banner-error-alert-end-content',
+ binding: 'Banner urgent alert',
+ summary:
+ 'an explicitly urgent error with a caller action remains an assertive alert when its message is replaced',
+ facts: alertFacts('Upload failed', 'Connection failed'),
+ status: 'error',
+ title: 'Upload failed',
+ replacementTitle: 'Connection failed',
+ dismissible: false,
+ endContentLabel: 'Retry',
+ storyId: 'a11y-alert-pattern--banner-error-alert-end-content',
+ },
+ {
+ id: 'banner-error-alert-description',
+ binding: 'Banner urgent alert',
+ summary:
+ 'an explicitly urgent error with a description remains an assertive alert when its title is replaced',
+ facts: alertFacts(
+ 'Upload failed',
+ 'Connection failed',
+ 'Check your network and try again.',
+ ),
+ status: 'error',
+ title: 'Upload failed',
+ replacementTitle: 'Connection failed',
+ description: 'Check your network and try again.',
+ dismissible: false,
+ storyId: 'a11y-alert-pattern--banner-error-alert-description',
+ },
+];
+
+export type BannerAlertBindingState = BannerAlertBindingDefinition & {
+ readonly id: BannerAlertStateId;
+};
+
+export const BANNER_ALERT_EXCLUSIONS = [
+ {
+ owner: 'component:Banner',
+ part: 'non-alert and status-to-role selection',
+ reason:
+ 'This binding starts after Banner has resolved the public role to alert. Its non-alert states and status-to-role selection remain component-owned.',
+ },
+ {
+ owner: 'Button, Disclosure, and Banner',
+ part: 'disclosure and action control behavior',
+ reason:
+ 'The bound states include the dismiss, disclosure, and caller-action controls only for their effect on the alert region. Button behavior, disclosure state, callback effects, and dismissal focus handoff keep their own component contracts and tests.',
+ },
+ {
+ owner: 'spec:AST-009',
+ part: 'spoken announcement output and timing',
+ reason:
+ 'This binding checks DOM, Chromium accessibility-tree, and browser focus outcomes only; real assistive technology owns speech and timing claims.',
+ },
+] as const;
diff --git a/packages/core/src/Banner/__tests__/Alert.a11y.test.tsx b/packages/core/src/Banner/__tests__/Alert.a11y.test.tsx
new file mode 100644
index 0000000000..029dcce373
--- /dev/null
+++ b/packages/core/src/Banner/__tests__/Alert.a11y.test.tsx
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Alert.a11y.test.tsx
+ * @input Uses the shared status-message contract and Banner alert-state render map
+ * @output Component-facing jsdom evidence for Banner's actual alert states
+ * @position Fast AST-021 migration lane; browser-owned outcomes remain explicitly unrun
+ */
+
+import {describe, expect, it} from 'vitest';
+import {act, cleanup, fireEvent, render, screen} from '@testing-library/react';
+import {
+ STATUS_MESSAGE_PATTERN,
+ expectAccessibilitySpec,
+} from '@astryxdesign/a11y-spec';
+import {BANNER_ALERT_KNOWN_FAILURES} from './Alert.a11y.known-failures';
+import {
+ BANNER_ALERT_STATE_RENDERS,
+ transitionTestId,
+} from './Alert.a11y.renders';
+import {
+ BANNER_ALERT_BINDING_STATES,
+ BANNER_ALERT_EXCLUSIONS,
+ type BannerAlertBindingState,
+} from './Alert.a11y.states';
+
+async function transition(name: string): Promise<void> {
+ fireEvent.click(screen.getByTestId(transitionTestId(name)));
+ await act(async () => Promise.resolve());
+}
+
+function subjectFor(state: BannerAlertBindingState): Element {
+ const matches = screen.getAllByRole('alert', {hidden: true});
+ if (matches.length !== 1) {
+ throw new Error(
+ `${state.id}: expected one alert subject, found ${matches.length}`,
+ );
+ }
+ return matches[0];
+}
+
+describe('Banner alert binding — jsdom lane', () => {
+ it.each(
+ BANNER_ALERT_BINDING_STATES.map(
+ state => [state.id, state.summary, state] as const,
+ ),
+ )('%s — %s', async (_id, _summary, state) => {
+ await expectAccessibilitySpec({
+ spec: STATUS_MESSAGE_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: BANNER_ALERT_KNOWN_FAILURES,
+ render: () => {
+ render(BANNER_ALERT_STATE_RENDERS[state.id]());
+ },
+ subject: () => subjectFor(state),
+ transition,
+ cleanup,
+ });
+ });
+
+ it('records the adjacent Banner states that keep separate owners', () => {
+ expect(BANNER_ALERT_EXCLUSIONS.map(entry => entry.part)).toEqual([
+ 'non-alert and status-to-role selection',
+ 'disclosure and action control behavior',
+ 'spoken announcement output and timing',
+ ]);
+ });
+});
diff --git a/packages/core/src/Banner/index.ts b/packages/core/src/Banner/index.ts
index c86d275702..a71e012771 100644
--- a/packages/core/src/Banner/index.ts
+++ b/packages/core/src/Banner/index.ts
@@ -34,9 +34,10 @@ export interface BannerContainerMap {
*
* Theme packages can add custom statuses via TypeScript module augmentation.
* A status the library does not know falls through to the base visual treatment:
- * no status fill and no default glyph. Status never chooses a live-region role;
- * callers opt into `role="status"` or `role="alert"` through BaseProps only when
- * that semantic is appropriate.
+ * no status fill and no default glyph. Status never chooses a live-region role.
+ * Announce a status change with `useAnnounce`. Pass `role="alert"` through
+ * BaseProps only for an urgent message; Banner puts it on the title and
+ * description.
* @example
* ```
* declare module '@astryxdesign/core/Banner' {