Skip to content

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

TypeScript
33.1 KB
Raw Blame

schema_version: 3 template_version: 4 kind: component id: component:Banner authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-07 owners: [cixzhang, imdreamrunner] 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, ] modules: [] families: [] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:theme-compilation, ] contributing: []

system_specs: [spec:AST-009, spec:AST-020, spec:AST-021]

Banner component contract

Intent

Banner presents a persistent status message at the top of a page or section. This contract records the current painted surfaces and the Banner frame as a separately targetable surface. The status and content targets remain unchanged.

Compatibility and migration

  • 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, 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. 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

Field Value
id CLN-0015
lifecycle DEP-0007
delta Banner renders no role and no aria-live unless the caller passes role. Visual status styling, icons, theming targets, and explicit role forwarding are unchanged
rollback Restore the status-to-role map from the final-patch baseline
state pending — lands in a declared minor with its [breaking] Changeset

Ownership boundary

Owns

  • The current status surface as Banner's primary painted surface.
  • The optional content surface below it.
  • The Banner frame that groups both surfaces and carries the current whole-banner elevation and elevated-card silhouette.
  • The semantic foreground context for Banner-authored title, description, icon, collapse, and dismiss content on the status surface. Built-in controls receive that context on their Button element only, so their tooltip remains an ordinary Button surface.

Does not own / non-goals

  • Button geometry, interaction layers, tooltip painting, or consumer-supplied endContent — delegated to component:Button. An action row of two or more actions follows family:action-groups.
  • A new theme property, prop, variant, or DOM element.

Public concepts

The Banner frame is a stable public theming concept. Its target is banner-frame, and it reflects the existing container and elevation axes. The existing banner target remains on the Status surface and continues to reflect container and status.

Consumer props, defaults, and usage remain documented in Banner.doc.mjs. No prop vocabulary or extensibility rule changes.

Behavioral and layout contract

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. 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

  • AV1 — Content presence. The content surface may be absent, collapsed, expanded, or always visible under the existing collapsible contract.
  • AV2 — Target scope. Themes use banner-frame for the whole Banner silhouette and elevation, banner for the primary Status surface, and the existing child targets for their owned parts.

Representative states

State Required current behavior Allowed variation
Flat card, no visible content Status surface is the full rounded painted surface; frame shadow is none and frame radius styling is absent. Status, text, controls, and theme paint
Elevated card, visible content Frame paints the whole shadow and radius; status surface paints top corners; content surface paints bottom corners. Elevation tier and content
Elevated section Frame paints the whole shadow without card radius; status and content surfaces remain square. Elevation tier and content
Custom radius on banner Status surface receives the private radius value; frame and Content surface keep their fallback radius. Authored radius value

Transformation and precedence order

  • ORD1 — Surface resolution. Resolve container, elevation, and visible content; apply whole-banner elevation and any elevated-card radius to the Banner frame; then render the targeted status and optional targeted content surfaces.
  • ORD2 — Current radius routing. Theme compilation writes a borderRadius authored on banner to the private radius variable on the Status surface. That value does not inherit to the ancestor frame or sibling Content surface. Consumers do not author the private variable directly.

Performance and resources

This contract introduces no new measurement, observer, listener, render pass, or runtime work beyond the press tracking family:action-groups FR5 gives an action row of two or more actions.

Accessibility contract

status communicates visual category through color and icon; it does not choose 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
Banner frame Groups the status and optional content surfaces and carries their shared silhouette and elevation. Current source and public docs Supporting FR2, FR3, FR4
Status surface Acts as Banner's primary painted surface, carrying the status fill, message, and controls. Current source and public docs Prominent FR1
Content surface Carries optional supporting detail below the status surface. Current source and public docs Supporting FR4, FR7
Action/dismiss controls Built-in control content receives the Status surface's on-muted foreground on the Button element; interaction layers and tooltips remain Button-owned. Consumer-supplied endContent is unchanged. Banner status context plus component:Button Supporting FR7, FR9

The Banner frame is stable anatomy and owns the additive banner-frame target. The Status surface remains Banner's primary painted surface and keeps the unqualified banner target.

Theming anatomy

{
  "Banner frame": {"target": "banner-frame"},
  "Status surface": {"target": "banner"},
  "Icon": {"target": "banner-icon"},
  "Title": {"inherits": "banner"},
  "Description": {"target": "banner-description"},
  "Action button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Dismiss button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Content surface": {"target": "banner-content"}
}

This map records runtime reachability. banner belongs to the primary Status surface rather than the outermost DOM element, while banner-frame belongs to the visible frame that owns whole-banner elevation and silhouette. Delegation to Button preserves each built-in control's anatomy and interaction ownership. Banner supplies only the status-surface foreground context on the Button element, and it does not restyle a consumer-provided endContent child.

Family and system relationships

  • architecture:component-theming-surface owns target qualification, anatomy mapping, and the requirement that public targets sit on stable painted parts.
  • architecture:public-component-api governs compatibility for the additive target admitted by DEC-1.
  • architecture:theme-compilation owns the private derived-variable route that currently carries Banner radius across its painters.

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 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

DEC-1 — The Banner frame has separate public theme ownership

Reference: component:Banner/DEC-1

Decider: cixzhang, 2026-09-07

The Banner frame is stable visible anatomy that owns whole-banner elevation and the elevated-card silhouette across the Status and optional Content surfaces. It receives the additive banner-frame target with container and elevation selector axes. The existing banner target remains on the primary Status surface.

frame names the public visual role. root is rejected because it describes DOM placement 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

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 should interrupt screen-reader output.

Open questions

None.

Content boundary

This file does not duplicate consumer prop tables or examples, implementation steps, or system theming rules.