Banner

A Banner is a notification displaying brief messages with helpful information related to a task on the page or something that requires the user's attention.

Status: Definition, usage rules, and variant table below were provided directly by the user (2026-08-19) — treated as authoritative business/product guidance. Anatomy and the props-vs-Figma composition gap are sourced from the Naos Figma documentation page (file hRdTyGxHG6nLoB8Kf5ZdQY, node 5649:748, "🧩 Naos – Feedback and overlays", checked 2026-08-19). The Figma page's own one-line description field is literally the placeholder text "Banner blablabla" — the definition above supersedes it. Anything not covered by either source is left as an explicit TODO.

Source: DTSL/design-system → packages/product/@dtsl-react/src/components/molecular/Banner/types/Banner.types.ts (package @dtsl/react, exported as Banner)

Props (verbatim from source)

export type BannerVariant = 'warning' | 'error' | 'success' | 'info'

export interface BannerProps {
	variant?: BannerVariant
	children: React.ReactNode
	closable?: boolean
	onClose?: () => void
	className?: string
	style?: React.CSSProperties
}

CRITICAL: Variant mismatch between product guidance and shipped code

Product guidance names 5 semantic variants, but the shipped BannerVariant type only has 4. The user-provided variant table includes an "AI" variant ("AI-related announcements/messages") that does not exist in Banner.types.ts (only warning | error | success | info are valid today).

Before publishing the real doc, confirm with engineering/design which is true:

• The Ai variant is planned/designed but not yet implemented in code (doc should say "coming soon" / link a tracking ticket), or
• It shipped under a different prop/value not reflected in this scaffold's source read, or
• The design guidance is ahead of an actual roadmap item with no committed implementation yet

Don't silently document variant="ai" as usable — it will not type-check against current source.

Variants

Variant	Use case
Info	Neutral announcements
Success	Positive news
Warning	Cautionary alerts
Error	Critical alerts
AI (not in shipped code — see CRITICAL note above)	AI-related announcements/messages

Mental model: think of a Banner as a billboard or alert siren at the top of your app — it immediately draws attention to important news.

• Info: just an informational announcement
• Success: something good has happened
• Warning: take notice and be careful
• Error: critical issue requiring attention
• AI: AI-related news/announcements

Anatomy

From the Figma anatomy diagrams (simple link variant and two-line CTA variant):

1. Container — full-width colored background matching the intent
2. Intent icon — circular icon indicating info/success/warning/error(/AI)
3. Message text
4. Action(s) — see "Actions Inside Banner" below
5. Close button — present when closable is true

When to Use

Use a Banner when you need to communicate a message to all users or across the entire app — a page-level, persistent message, not feedback scoped to one user's action.

This matches the Figma placement examples: Banner is shown full-width, anchored directly below GlobalHeader, above the main content area (both desktop and mobile) — confirming it as a persistent, page-anchored message rather than a transient toast.

When NOT to Use

• Feedback limited to a single user action (e.g. a form submit) → use Snackbar
• Contextual help or warnings tied to a specific field or element → use InfoCard
• Very brief hover hints or inline clarifications → use a Tooltip
• The user must immediately acknowledge or resolve something (blocking) → use a confirmation Modal Dialog

Actions Inside Banner

A Banner may include one prominent action (button or link) for follow-up — e.g. "Learn more" or "Check status".

Note on a discrepancy with the Figma file: the Figma variant grid also shows a two-button pair ("Accept all" / "Decline", consent-style) under its "CTA=Button" variant, which reads as more than one action. Treat "one prominent action" as the general rule and the consent-style pair as a specific exception — worth confirming with design which is the intended default guidance.

Also confirmed from Figma (not a prop): neither the action content nor the two-line mobile layout are dedicated props — BannerProps only exposes variant and closable. Any action (Link or button) is composed via children.

Decision Logic

Is this message relevant to all users / the whole app, and persistent (not one-off feedback)?
  NO  → use Snackbar (single-action feedback), InfoCard (field-level), Tooltip (hover hint),
        or a confirmation Modal (blocking) instead
  YES → use Banner

Pick variant:
  Neutral announcement           → info
  Positive news                  → success
  Cautionary alert                → warning
  Critical alert                  → error
  AI-related announcement         → intended as "ai" per product guidance,
                                     but NOT YET a valid value in BannerProps — confirm before using

Needs a dismiss control? → set closable={true}, handle onClose
Needs a follow-up action? → put a single prominent Link or button in children
  (a two-button consent pair appears in Figma as a possible exception — confirm with design)

Accessibility

TODO — not covered by either source. Needs UX/product input.

Common Mistakes

• ❌ Using Banner for feedback on a single user action — use Snackbar instead
• ❌ Using Banner for field-level contextual help — use InfoCard instead
• ❌ Documenting or using variant="ai" before confirming it's actually implemented in BannerProps
• ❌ Looking for a cta/mobile prop — action content and mobile layout come from children composition, not props