## When to use

Three reasons a banner exists at the top of an app: the system is in a degraded state (08j), real-time activity has out-paced the user's view (17f), or product wants to promote something (14e). They share a primitive but differ in tone, dismissibility, and persistence — system banners are non-dismissible while the condition holds; live + announcement are dismissible.

## System status — offline

`variant="warning"` with a network-slash icon. Non-dismissible while the connection is down. The banner disappears on its own when the network returns; users don't dismiss it manually.

You're offline. Changes will sync when the connection returns. Some features are unavailable.

## System status — maintenance window

`variant="info"` with a wrench icon. Posted ahead of a planned outage. Carries the start time and an optional "Learn more" link to a status page. Not dismissible — users need to know.

Scheduled maintenance — Sunday, 2:00–4:00 AM UTC. The service will be read-only during this window.

## System status — update available

`variant="info"` with an arrow-clockwise icon and a primary "Refresh" CTA. Appears when the client detects a newer build. Dismissible (user is in the middle of something) but reappears on next session start.

A new version is available. Refresh to get the latest features and fixes.

## Live updates — "new since you opened this"

`variant="info"` with a count + a "Show new" CTA. Sits above a list / feed / table to signal that the underlying data has new rows the user hasn't seen yet. Clicking the CTA scrolls the new items in and dismisses the banner. Companion to the `data-stream` trait.

12 new items since you opened this view 4 minutes ago.

## Announcement — beta callout

`variant="info"` or `variant="muted"` with a sparkle / flask icon. Promotes a new feature to opted-in users; carries a "Try it" CTA + dismiss. Once dismissed, persists per-user — don't show twice.

New: Saved views. Curate filter sets and reuse them across the workspace. Now in beta.

## Announcement — promo / event

`variant="info"` with a megaphone or calendar icon. Time-boxed (event date, promo end). Dismiss persists for the campaign window. CTA goes to the landing page or signup flow.

UIConf 2026 — May 22, virtual. Two days of sessions on generative UI, A2UI internals, and the road ahead.

## Composition rules

- System banners are non-dismissible while the condition holds — offline, maintenance windows, and incidents disappear on their own when the situation resolves. Forcing a manual dismiss invites confusion ("did I miss something?").
- Update-available is the exception — the user is allowed to keep working through their current task; the banner reappears next session.
- Live-update banners pair with `data-stream` — the banner's count comes from the same stream that's feeding the list below it. The CTA reveals queued items already in memory; the banner is a UX-layer affordance, not a re-fetch.
- Announcements respect a per-user dismiss — once a user closes a beta callout or promo, do not show it again on this device for the campaign window. Persist server-side if the campaign spans devices.
- One banner at a time — stacking three banners above the app shell pushes content down and reads as broken. Prioritize: system > live > announcement; suppress lower-priority banners while higher-priority ones are visible.
- Banner text leads with the noun, not the verb — "12 new items", "Scheduled maintenance", "New version available". Action verbs go on the button.

## See also

- alert-ui — the underlying primitive (variants, closable, icon, slots).
- data-stream — the trait that powers live-update counts.
- toast-ui — transient ephemeral notifications (sibling, not interchangeable).
- auth status pages — full-page status surfaces (sibling for non-banner system states).