A full-bleed band at the top of a page carrying one announcement to everyone who lands there — a maintenance window, a new capability, a policy change. The reader acknowledges it with the X and it goes away; nothing else on the page changes when it does.
The boundary against Alert is scope and width. An alert reports a condition about the thing it sits beside, inside the content column, and lives exactly as long as that condition holds; a banner addresses the whole page, spans it, and lives until it is acknowledged. The X is the tell — an alert is forbidden one because dismissing a live condition hides something still true, while an announcement stays true after it is read.
The root and __content both span the available width; the content row supplies only the active responsive page gutter resolved by --ds-page-gutter. The nested exhibit resolves that value from the same specimen chrome gutter as the live Banner and Topbar, so all three demonstrate one inset.
A newer version is ready.
Neutral uses the inverted pair — dark charcoal in light UI, near-white in dark UI — and no status icon. The outline marks the exhibit boundary only; it is specimen chrome, not part of Banner.
Neutral is the high-contrast unmarked base; the four status variants take the solid pair so they carry the same page-level authority rather than reading weaker than neutral. Alert keeps the subtle tier for persistent in-flow conditions. Each Show trigger fires its scenario above the real specimen topbar, where only one page-level announcement can appear.
| Variant | Modifier | Roles | Usage | Demo |
|---|---|---|---|---|
| Neutral | — | text.primarytext.inverse | A high-contrast page-wide update with no status claim; this one carries the optional immediate action | |
| Success | --success | status.success.solid-bgstatus.success.solid-text | Something long-running finished for everyone | |
| Warning | --warning | status.warning.solid-bgstatus.warning.solid-text | Something ahead the reader should plan around; status details remain a Link | |
| Error | --error | status.error.solid-bgstatus.error.solid-text | A live incident affecting the whole page | |
| Info | --info | status.info.solid-bgstatus.info.solid-text | A change worth knowing that makes no success or failure claim |
One line by construction: the content is a single message, never Alert's title-and-body stack. At full page width a two-level stack stops being a band and becomes a slab that pushes the page below the fold — an announcement that needs a paragraph belongs on the page behind its link.
| Part | Element | Notes |
|---|---|---|
root | div.ds-banner | The band: inverted fill edge to edge, no border, no max-width, and no inline padding of its own |
content | div.ds-banner__content | The full-width row — no container cap, the active responsive page gutter, and a space.3 gap at control.lg min-height so the band matches the bar below it |
icon | svg.ds-icon | Optional leading glyph at icon.md, decorative and canonical per variant; omitted on neutral. The banner pins the size, so ds-icon--* is inert |
message | p.ds-banner__message | The announcement in one sentence; takes the row's free space and may carry a Link |
actions | div.ds-banner__actions | Required trailing control cluster on space.1, matching Topbar and Sheet; contains the optional action followed by the persistent dismiss Button |
action | button.ds-button--secondary.ds-button--sm | Optional: at most one ordinary Button inside ds-banner__actions, inheriting the banner's paired foreground and contextual outline states |
dismiss | button.ds-button.ds-button--ghost.ds-button--icon.ds-button--sm.ds-banner__dismiss | The standard small ghost icon Button wearing i-x, with aria-label required. Banner owns placement at the active responsive page gutter; Button owns geometry and interaction states |
Acknowledging is not resolving: the X ends this reader's exposure to the announcement and nothing more. Whether that dismissal survives a reload is host policy — a cookie, a user record, or nothing at all — and L1 contracts only that dismissing removes the band. Escape is deliberately unbound; a banner is page content, not a layer.
A banner speaks to the page, not to anything on it.
| Verdict | Rule |
|---|---|
| Do | Use a banner for something true of the whole page, an alert for a condition about one thing on it, and a toast for the result of an action. |
| Do | Keep it to one sentence. The band carries the announcement; the detail lives on the page it links to. |
| Do | Compose every banner dismiss X from the standard small ghost icon Button. Keep aria-label and i-x; let Banner control placement only. |
| Do | Group the optional action and dismiss Button on space.1. Use space.3 only between message content and the complete action group. |
| Do | Let the banner push the page down. If it must stay visible while scrolling, the host makes it sticky at z.sticky — it still occupies its own space. |
| Don’t | Stack two banners. Two announcements at once means neither is read — pick the one that matters today. |
| Don’t | Put anything behind the X the reader cannot get back to. Acknowledging is not opting out, so a choice with consequences is a Dialog. |
| Don’t | Give it a primary button or more than one action. One secondary Button may act; a plain destination remains a Link inside the message. |
| Don’t | Widen an alert into a band or hand it a dismiss to fake one. If it describes the page rather than a thing on it, it was always a banner. |