Cloaked Design SystemStatus

Banner

An inline advisory strip that annotates present content with a title or eyebrow, a message, and an optional icon, action, and dismiss control.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Explore every named example, including states, compositions, and theme variants.

5 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/status/Banner/Banner.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

An inline advisory strip that annotates present content with a title or eyebrow, a message, and an optional icon, action, and dismiss control.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Banner } from '@cloakedinc/design-system';

BannerBannerProps

packages/design-system/src/components/status/Banner/Banner.tsx:32

Prop	Type	Presence	Notes
`title`	`string \| undefined`	Optional	Sentence-case heading above the message. Prefer this over `eyebrow` for a real title.
`eyebrow`	`string \| undefined`	Optional	Small uppercase label shown before the message, for short status words like "Could not load".
`icon`	`React.ReactNode`	Optional	Leading visual slot, usually an `Icon`.
`children`	`React.ReactNode`	Required
`action`	`React.ReactNode`	Optional	Optional control shown beneath the message, usually a `Button`.
`onDismiss`	`(() => void) \| undefined`	Optional	Providing this renders the dismiss button; omit for a non-dismissible banner.
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Optional test selector. The dismiss button derives `${testId}-dismiss`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

An inline informational strip that stays in the flow of content. variant sets the semantic treatment. It renders as role="note", so it is advisory — never a required decision. Reach for EmptyState when a whole region has no content to show; a Banner annotates content that is present, and a BottomSheet when a choice must block progress.

Slots

Optional icon (leading), action (trailing), and onDismiss (renders the × button).

Usage by variant

Choice	Use when	Avoid when
`Variant: info`	Neutral context — "what happens next", "from Cloaked". The only variant currently used in the app.
`Variant: success`	Confirmation that a state is good or protected. Currently unused in the app.
`Variant: warning`	A caution that needs attention but does not block — often paired with an `action`.	A hard error the user must resolve before continuing.
`Variant: danger`	A problem the user should notice.	A required decision — Banner stays advisory (role="note"); use a BottomSheet to block.

Do and don’t

Guidance	Example
Don’t	Use `variant='info'` as a passive status strip on a form screen. In light theme `--cds-banner-container` and `--cds-input-container` resolve to the same grey, so a filled, rounded, single-line banner above a column of text fields reads as a search field rather than a message. On form surfaces, say it in a `Text` row and keep Banner for real interruptions.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: root
Label: Root
Description: Grid container carrying the neutral surface and radius.
Required: true

Id: icon
Label: Icon
Description: Optional leading visual marker.

Id: content
Label: Content
Description: Stacks the eyebrow, message, and optional action.

Id: title
Label: Title
Description: Sentence-case heading above the message; the message drops to body-small beneath it.

Id: eyebrow
Label: Eyebrow
Description: Short uppercase label above the message.

Id: body
Label: Message
Description: Primary advisory copy.

Id: action
Label: Action
Description: Optional trailing control.

Id: dismiss
Label: Dismiss
Description: Optional close button.

Allowed Design Choices

Variants

Informational

Label: Informational
Description: The single neutral treatment. Banner carries no tone.

Sizes

Variants

Id: informational
Label: Informational
Description: Neutral advisory strip. Errors belong in a Card, EmptyState, or Toast.
Platforms: ios
android
web

Sizes

None specified

Measurements

Id: content-gap
Label: Content gap
Kind: exact
Token: --cds-space-8
Value: 8
Unit: px
Applies To: root
content

Id: container-inset
Label: Container inset
Kind: exact
Token: --cds-space-16
Value: 16
Unit: px
Applies To: root

Id: corner-radius
Label: Corner radius
Kind: exact
Token: --cds-radius-lg
Value: 20
Unit: px
Applies To: root

Layout

Alignment: Leading icon, content column, and dismiss align to the top of the strip.
Flow: A three-column grid: optional icon, flexible content, optional dismiss.
Notes: Use EmptyState when a whole region has no content, not just a note about present content.

Typography And Color

Typography

Label: Title
Description: Sentence-case heading on the body ramp.
Token: --cds-type-body-size

Label: Eyebrow
Description: Uses the body-small ramp, uppercased.
Token: --cds-type-body-small-size

Label: Message
Description: Uses the body ramp, dropping to body-small when a title is set so the heading stays the larger of the two.
Token: --cds-type-body-size

Colors

Label: Info surface
Description: The banner always paints the neutral container tone; there is no status variant.
Token: --cds-banner-container

Label: Eyebrow text
Description: Primary banner text for the eyebrow and icon.
Token: --cds-banner-text-primary

Label: Message text
Description: Secondary banner text for the message.
Token: --cds-banner-text-secondary

States

Id: info
Label: Info
Description: Neutral banner container.

Id: titled
Label: Titled
Description: A title is set, so the message renders on the body-small ramp beneath it.

Id: dismissible
Label: Dismissible
Description: Shows the close button when onDismiss is provided.

Behavior

Label: Advisory role
Description: Banner is a role=note; it advises and never blocks like a modal.

Label: Dismiss
Description: Render the close button only when a dismiss handler is provided.

Accessibility

Label: Note landmark
Description: The banner exposes role=note so assistive tech treats it as advisory.

Label: Dismiss label
Description: The close button carries an accessible label.

Content Adaptation

Label: Wrapping message
Description: The message wraps to multiple lines while the grid keeps the icon and dismiss aligned.

Label: Optional slots
Description: Icon, action, and dismiss each appear only when supplied.

Motion Haptics

Motion

Label: Static
Description: The banner does not animate its own entrance or exit.

Haptics

Label: Dismiss feedback
Description: Host surfaces may request a light haptic on dismiss.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1