An open source design system that's fully customizable and agent ready
TypeScript
fix(Banner): make live-region roles explicit (#6630)
Cindy Zhang57e63a6ba32c
diff --git a/.changeset/banner-explicit-announcements.md b/.changeset/banner-explicit-announcements.mdnew file mode 100644index 0000000000..6f234c6ab5--- /dev/null+++ b/.changeset/banner-explicit-announcements.md@@ -0,0 +1,21 @@+---+'@astryxdesign/core': minor+---++[breaking] Stop deriving live-region roles from `Banner.status`. Banners are non-live by default; call `useAnnounce` from the actual async transition handler, or provide an explicit `role="status"` for a persistent semantic mirror.++`role="alert"` is now opt-in rather than automatic for warning and error banners.++@cixzhang++Old usage:+`Banner` derived `role="status"` or `role="alert"` from its `status` variant.++Replacement:+The caller sets the role explicitly, or announces with `useAnnounce`.++Migration:+Call `useAnnounce` from the actual async transition handler, or provide an explicit `role="status"` for a persistent semantic mirror.++Codemod:+None — the right announcement depends on the callsite.diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsindex 8895e7f958..cf6e31de38 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: 'Error and warning banners render as role="alert"; info and success render as role="status". Mount an alert banner in response to an event rather than on first paint, so assistive tech has a change to report.'},+ {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: 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: [@@ -33,6 +33,44 @@ export const docs = {],},+ examples: [+ {+ label: 'Announce an async outcome from its transition handler',+ code: `import {useState} from 'react';+import {Banner} from '@astryxdesign/core/Banner';+import {Button} from '@astryxdesign/core/Button';+import {useAnnounce} from '@astryxdesign/core/hooks';++function SaveSettings() {+ const announce = useAnnounce();+ const [result, setResult] = useState<'success' | 'error' | null>(null);++ async function handleSave() {+ try {+ await saveSettings();+ setResult('success');+ announce('Settings saved');+ } catch {+ setResult('error');+ announce('Settings could not be saved');+ }+ }++ return (+ <>+ <Button label="Save settings" onClick={handleSave} />+ {result != null ? (+ <Banner+ status={result}+ title={result === 'success' ? 'Settings saved' : 'Save failed'}+ />+ ) : null}+ </>+ );+}`,+ },+ ],+props: [{name: 'status',@@ -158,6 +196,8 @@ 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: false, description: '不要只依赖 status 的颜色或图标传达含义;请在标题文本中明确说明状态,因为屏幕阅读器会忽略这个装饰性图标。'},],anatomy: [{name: 'Banner frame', required: true, description: 'Outer frame that groups the status surface and optional content surface. It carries whole-banner elevation and, for elevated card banners, the radius that shapes that silhouette.'},@@ -245,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: 'Error/warning render role="alert", info/success role="status"; mount an alert banner on an event, not first paint, so assistive tech announces it.'},+ {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: 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.spec.md b/packages/core/src/Banner/Banner.spec.mdindex 5bff012157..573f0acb25 100644--- a/packages/core/src/Banner/Banner.spec.md+++ b/packages/core/src/Banner/Banner.spec.md@@ -9,7 +9,7 @@ superseded_by: nullapproved_by: cixzhangapproved_at: 2026-09-07owners: [cixzhang, imdreamrunner]-review_triggers: [public-api, layout, theming]+review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:[packages/core/src/Banner/Banner.test.tsx,@@ -26,7 +26,7 @@ architecture:architecture:theme-compilation,]contributing: []-system_specs: []+system_specs: [spec:AST-009]---# Banner component contract@@ -39,12 +39,10 @@ separately targetable surface. The status and content targets remain unchanged.## Compatibility and migration-- Released default preserved: `yes`-- Compatibility class: additive public theming target; no existing target,- runtime default, DOM, prop, or behavior changes+- 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: none; new themes use `banner-frame` for frame-specific- overrides+- 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 interruptionConsumer migration instructions belong in consumer docs and release notes.@@ -107,15 +105,16 @@ prop vocabulary or extensibility rule changes.The requirements below describe the current implementation and its additiveframe 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 |+| 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 |### Allowed variation@@ -152,8 +151,17 @@ runtime work.## Accessibility contract-This contract does not change Banner's current status roles, announcements,-focus handoff, disclosure controls, or accessible control names.+`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`+from the transition handler, which writes into a previously mounted live region;+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.++Dismissal focus handoff, disclosure controls, and accessible control names remain+unchanged.## Design relationships@@ -204,13 +212,14 @@ the visible frame that owns whole-banner elevation and silhouette.## 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` |-| 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 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` |+| 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@@ -229,6 +238,22 @@ surface.`frame` names the public visual role. `root` is rejected because it describes DOMplacement and would imply that the target must remain on the outermost element.+### DEC-2 — Visual status does not infer announcement urgency++**Reference:** `component:Banner/DEC-2`++**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. An explicit native role remains available through BaseProps for+a persistent semantic mirror or the rare genuinely urgent alert.++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+should interrupt screen-reader output.+## Open questionsNone.diff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsxindex ec2a540443..96730e0020 100644--- a/packages/core/src/Banner/Banner.test.tsx+++ b/packages/core/src/Banner/Banner.test.tsx@@ -3,9 +3,10 @@/*** @file Banner.test.tsx* @input Uses vitest, @testing-library/react, Banner component- * @output Unit tests for Banner component behavior, including the- * 'banner-frame' theme target on the outer elevation/radius painter and the- * 'banner-icon' theme target on the status icon glyph (#4166)+ * @output Unit tests for Banner component behavior, including default and+ * explicit live-region roles, the 'banner-frame' theme target on the outer+ * elevation/radius painter, and the 'banner-icon' theme target on the status+ * icon glyph (#4166)* @position Testing; validates Banner.tsx implementation** SYNC: When modified, update this header@@ -29,24 +30,26 @@ describe('Banner', () => {expect(screen.getByText('Test Banner')).toBeInTheDocument();});- it('renders info status with role="status"', () => {- render(<Banner status="info" title="Info" />);- expect(screen.getByRole('status')).toBeInTheDocument();- });-- it('renders warning status with role="alert"', () => {- render(<Banner status="warning" title="Warning" />);- expect(screen.getByRole('alert')).toBeInTheDocument();+ it('does not infer a live-region role from visual status', () => {+ const statuses = ['info', 'warning', 'error', 'success'] as const;+ for (const status of statuses) {+ const {container, unmount} = render(+ <Banner status={status} title={`${status} banner`} />,+ );+ expect(container.firstElementChild).not.toHaveAttribute('role');+ expect(container.firstElementChild).not.toHaveAttribute('aria-live');+ unmount();+ }});- it('renders error status with role="alert"', () => {- render(<Banner status="error" title="Error" />);- expect(screen.getByRole('alert')).toBeInTheDocument();- });+ it('forwards an explicit persistent or alert role', () => {+ const {rerender} = render(+ <Banner status="info" title="Saved" role="status" />,+ );+ expect(screen.getByRole('status')).toHaveTextContent('Saved');- it('renders success status with role="status"', () => {- render(<Banner status="success" title="Success" />);- expect(screen.getByRole('status')).toBeInTheDocument();+ rerender(<Banner status="error" title="Failed" role="alert" />);+ expect(screen.getByRole('alert')).toHaveTextContent('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.tsxindex 85c0f9c474..39f21b0fb8 100644--- a/packages/core/src/Banner/Banner.tsx+++ b/packages/core/src/Banner/Banner.tsx@@ -29,9 +29,11 @@* default / controlled) lives on that one prop and is driven by the shared* `useCollapsible` hook rather than local state.*- * A status added through `BannerStatusMap` augmentation has no entry in the- * status lookups, so it renders with no status fill, no default glyph and the- * polite `role="status"` rather than losing its ARIA role entirely.+ * Status controls visual treatment only. The root 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.** Title and description render as <div> (not <p>): they accept arbitrary* ReactNode content, and <p> cannot legally contain block-level children@@ -195,8 +197,8 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {// `BannerStatus` is `keyof BannerStatusMap`, and index.ts documents augmenting// that interface to add a status. Every lookup below is therefore partial: an// augmented status the library has never heard of falls through to the base-// treatment (no status fill, no glyph, the polite role) instead of resolving to-// `undefined` and dropping the ARIA role along with it.+// visual treatment: no status fill and no default glyph. Announcement semantics+// remain caller-owned for every status.const defaultIconNames: Partial<Record<BannerStatus, IconName>> = {info: 'info',@@ -205,16 +207,6 @@ const defaultIconNames: Partial<Record<BannerStatus, IconName>> = {success: 'success',};-const statusRole: Partial<Record<BannerStatus, 'alert' | 'status'>> = {- info: 'status',- warning: 'alert',- error: 'alert',- success: 'status',-};--/** An unknown status is not urgent by definition, so it announces politely. */-const FALLBACK_ROLE = 'status';-const statusIconColor: Partial<Record<BannerStatus, IconColor>> = {info: 'accent',warning: 'warning',@@ -413,7 +405,9 @@ const elevationStyles = stylex.create({* even if `onDismiss` is not provided, so product teams don't need to wire* up state management for basic dismiss behavior.*- * Uses `role="alert"` for error/warning and `role="status"` for info/success.+ * 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.** @example* ```@@ -503,7 +497,6 @@ export function Banner({// non-collapsible banner has no toggle, so neither end of the link is used.const contentId = useId();const defaultIconName = defaultIconNames[status];- const role = statusRole[status] ?? FALLBACK_ROLE;const iconColor = statusIconColor[status];const hasChildren = isRenderable(children);// Keep the default tooltip concise while the accessible name identifies@@ -571,7 +564,6 @@ export function Banner({return (<divref={ref}- role={role}onFocusCapture={composeEventHandlers(onFocusCapture, handleFocusCapture)}onPointerDownCapture={composeEventHandlers(onPointerDownCapture,diff --git a/packages/core/src/Banner/index.ts b/packages/core/src/Banner/index.tsindex acf637ac17..c86d275702 100644--- a/packages/core/src/Banner/index.ts+++ b/packages/core/src/Banner/index.ts@@ -33,8 +33,10 @@ export interface BannerContainerMap {* Extensible status map for Banner.** Theme packages can add custom statuses via TypeScript module augmentation.- * A status the library does not know falls through to the base treatment: no- * status fill, no default glyph, and `role="status"`.+ * 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.* @example* ```* declare module '@astryxdesign/core/Banner' {