# Banner

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

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/status/Banner/Banner.tsx

## Guidance

{
  "summary": "An inline advisory strip that annotates present content with a title or eyebrow, a message, and an optional icon, action, and dismiss control.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "An inline informational strip that stays in the flow of content. `variant` sets the\nsemantic treatment. It renders as `role=\"note\"`, so it is advisory — never a required\ndecision. Reach for `EmptyState` when a whole region has no content to show; a Banner\nannotates content that is present, and a `BottomSheet` when a choice must block progress."
    },
    {
      "heading": "Slots",
      "body": "Optional `icon` (leading), `action` (trailing), and `onDismiss` (renders the × button)."
    }
  ],
  "usage": [
    {
      "variant": "info",
      "use": "Neutral context — \"what happens next\", \"from Cloaked\". The only variant currently used in the app.",
      "axis": "Variant"
    },
    {
      "variant": "success",
      "use": "Confirmation that a state is good or protected. Currently unused in the app.",
      "axis": "Variant"
    },
    {
      "variant": "warning",
      "use": "A caution that needs attention but does not block — often paired with an `action`.",
      "avoid": "A hard error the user must resolve before continuing.",
      "axis": "Variant"
    },
    {
      "variant": "danger",
      "use": "A problem the user should notice.",
      "avoid": "A required decision — Banner stays advisory (role=\"note\"); use a BottomSheet to block.",
      "axis": "Variant"
    }
  ],
  "examples": [
    {
      "kind": "dont",
      "caption": "Use `variant='info'` as a passive status strip on a form screen. In light theme\n    `--cds-banner-container` and `--cds-input-container` resolve to the same grey, so a filled,\n    rounded, single-line banner above a column of text fields reads as a search field rather than a\n    message. On form surfaces, say it in a `Text` row and keep Banner for real interruptions."
    }
  ],
  "source": "packages/design-system/src/components/status/Banner/Banner.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "title",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Sentence-case heading above the message. Prefer this over `eyebrow` for a real title.",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 12
      }
    },
    {
      "name": "eyebrow",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Small uppercase label shown before the message, for short status words like \"Could not load\".",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 14
      }
    },
    {
      "name": "icon",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "Leading visual slot, usually an `Icon`.",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 16
      }
    },
    {
      "name": "children",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": true,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 17
      }
    },
    {
      "name": "action",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "Optional control shown beneath the message, usually a `Button`.",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 19
      }
    },
    {
      "name": "onDismiss",
      "type": "(() => void) | undefined",
      "declared_type": "() => void",
      "required": false,
      "description": "Providing this renders the dismiss button; omit for a non-dismissible banner.",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 21
      }
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 22
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 23
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector. The dismiss button derives `${testId}-dismiss`.",
      "source": {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 25
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Banner",
    "public_path": "Banner",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Banner",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
          "line": 32
        },
        "props_type": "BannerProps",
        "props": [
          {
            "name": "title",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Sentence-case heading above the message. Prefer this over `eyebrow` for a real title.",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 12
            }
          },
          {
            "name": "eyebrow",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Small uppercase label shown before the message, for short status words like \"Could not load\".",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 14
            }
          },
          {
            "name": "icon",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Leading visual slot, usually an `Icon`.",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 16
            }
          },
          {
            "name": "children",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 17
            }
          },
          {
            "name": "action",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Optional control shown beneath the message, usually a `Button`.",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 19
            }
          },
          {
            "name": "onDismiss",
            "type": "(() => void) | undefined",
            "declared_type": "() => void",
            "required": false,
            "description": "Providing this renders the dismiss button; omit for a non-dismissible banner.",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 21
            }
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 22
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 23
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector. The dismiss button derives `${testId}-dismiss`.",
            "source": {
              "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
              "line": 25
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/status/Banner/Banner.tsx",
        "line": 10,
        "name": "BannerProps",
        "code": "export interface BannerProps {\n    /** Sentence-case heading above the message. Prefer this over `eyebrow` for a real title. */\n    title?: string;\n    /** Small uppercase label shown before the message, for short status words like \"Could not load\". */\n    eyebrow?: string;\n    /** Leading visual slot, usually an `Icon`. */\n    icon?: React.ReactNode;\n    children: React.ReactNode;\n    /** Optional control shown beneath the message, usually a `Button`. */\n    action?: React.ReactNode;\n    /** Providing this renders the dismiss button; omit for a non-dismissible banner. */\n    onDismiss?: () => void;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Optional test selector. The dismiss button derives `${testId}-dismiss`. */\n    testId?: string;\n}"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Banner",
      "status": "preview",
      "version": "1.0.0",
      "summary": "An inline advisory strip that annotates present content with a title or eyebrow, a message, and an optional icon, action, and dismiss control."
    },
    "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."
      }
    ],
    "allowedDesignChoices": {
      "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": [],
    "measurements": [
      {
        "id": "content-gap",
        "label": "Content gap",
        "kind": "exact",
        "token": "--cds-space-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "root",
          "content"
        ]
      },
      {
        "id": "container-inset",
        "label": "Container inset",
        "kind": "exact",
        "token": "--cds-space-16",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      },
      {
        "id": "corner-radius",
        "label": "Corner radius",
        "kind": "exact",
        "token": "--cds-radius-lg",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "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."
      ]
    },
    "typographyAndColor": {
      "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."
      }
    ],
    "contentAdaptation": [
      {
        "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."
      }
    ],
    "motionHaptics": {
      "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."
        }
      ]
    },
    "platformDifferences": []
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-space-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-space-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-radius-lg",
      "light": "20px",
      "dark": "20px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-banner-container",
      "light": "#f3f1ed",
      "dark": "#141410"
    },
    {
      "name": "--cds-banner-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-banner-text-secondary",
      "light": "#84827e",
      "dark": "#e0ddd6"
    },
    {
      "name": "--cds-input-container",
      "light": "#f3f1ed",
      "dark": "#232321"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-status-banner--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/status/Banner/Banner.stories.tsx

- [With Eyebrow](/storybook/iframe.html?id=cloaked-design-system-status-banner--with-eyebrow&viewMode=story) | export: WithEyebrow | source: packages/design-system/src/components/status/Banner/Banner.stories.tsx

- [With Icon Action And Dismiss](/storybook/iframe.html?id=cloaked-design-system-status-banner--with-icon-action-and-dismiss&viewMode=story) | export: WithIconActionAndDismiss | source: packages/design-system/src/components/status/Banner/Banner.stories.tsx

- [Long Content](/storybook/iframe.html?id=cloaked-design-system-status-banner--long-content&viewMode=story) | export: LongContent | source: packages/design-system/src/components/status/Banner/Banner.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-status-banner--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/status/Banner/Banner.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.