Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Add XDSBanner component (#203)

Cindy Zhang5f7cff259983
diff --git a/apps/storybook/stories/Banner.stories.tsx b/apps/storybook/stories/Banner.stories.tsx
new file mode 100644
index 0000000000..c37549ccda
--- /dev/null
+++ b/apps/storybook/stories/Banner.stories.tsx
@@ -0,0 +1,199 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSBanner} from '@xds/core/Banner';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {ShieldCheckIcon} from '@heroicons/react/24/solid';
+
+const meta: Meta<typeof XDSBanner> = {
+ title: 'Core/XDSBanner',
+ component: XDSBanner,
+ tags: ['autodocs'],
+ argTypes: {
+ status: {
+ control: 'select',
+ options: ['info', 'warning', 'error', 'success'],
+ description: 'Status type controlling icon and color',
+ },
+ variant: {
+ control: 'select',
+ options: ['card', 'section'],
+ description: 'Visual variant',
+ },
+ isDismissable: {
+ control: 'boolean',
+ description:
+ 'Whether the banner can be dismissed (manages its own hidden state)',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSBanner>;
+
+export const Info: Story = {
+ args: {
+ status: 'info',
+ title: 'A new software update is available.',
+ },
+};
+
+export const Warning: Story = {
+ args: {
+ status: 'warning',
+ title: 'Your trial expires in 3 days.',
+ },
+};
+
+export const Error: Story = {
+ args: {
+ status: 'error',
+ title: 'There was an error processing your request.',
+ },
+};
+
+export const Success: Story = {
+ args: {
+ status: 'success',
+ title: 'Your changes have been saved successfully.',
+ },
+};
+
+export const WithDescription: Story = {
+ args: {
+ status: 'info',
+ title: 'New update available',
+ description:
+ 'A new version of the application is available. Update now to get the latest features and improvements.',
+ },
+};
+
+export const WithEndButton: Story = {
+ args: {
+ status: 'info',
+ title: 'New update available',
+ description: 'Version 2.0 is ready to install.',
+ endButton: <XDSButton label="Update now" variant="primary" size="sm" />,
+ },
+};
+
+export const Dismissable: Story = {
+ args: {
+ status: 'warning',
+ title: 'Your session will expire soon.',
+ description: 'Please save your work to avoid losing changes.',
+ isDismissable: true,
+ },
+};
+
+export const DismissableWithCallback: Story = {
+ args: {
+ status: 'info',
+ title: 'This banner dismisses itself and calls onDismiss.',
+ isDismissable: true,
+ onDismiss: () => console.log('Dismissed!'),
+ },
+};
+
+export const SectionVariant: Story = {
+ args: {
+ status: 'info',
+ title: 'System maintenance scheduled',
+ description:
+ 'The system will be undergoing maintenance on Saturday from 2:00 AM to 6:00 AM UTC.',
+ variant: 'section',
+ },
+};
+
+export const WithContentArea: Story = {
+ name: 'With Content Area (Card Background)',
+ args: {
+ status: 'error',
+ title: 'Multiple errors found',
+ description: 'The following issues need to be resolved:',
+ children: (
+ <ul style={{margin: 0, paddingInlineStart: '20px', fontSize: '13px'}}>
+ <li>Email address is invalid</li>
+ <li>Password must be at least 8 characters</li>
+ <li>Username is already taken</li>
+ </ul>
+ ),
+ },
+};
+
+export const ContentAreaWithAction: Story = {
+ name: 'Content Area + Action Button',
+ args: {
+ status: 'warning',
+ title: 'Configuration changes detected',
+ description: 'Review the changes before they take effect.',
+ endButton: <XDSButton label="Review" variant="secondary" size="sm" />,
+ isDismissable: true,
+ children: (
+ <div style={{fontSize: '13px'}}>
+ <p style={{margin: '0 0 8px'}}>Changed settings:</p>
+ <ul style={{margin: 0, paddingInlineStart: '20px'}}>
+ <li>Authentication method updated</li>
+ <li>Rate limits modified</li>
+ </ul>
+ </div>
+ ),
+ },
+};
+
+export const AllStatuses: Story = {
+ name: 'All Status Variants',
+ render: () => (
+ <div style={{display: 'flex', flexDirection: 'column', gap: '16px'}}>
+ <XDSBanner status="info" title="Info banner" />
+ <XDSBanner status="warning" title="Warning banner" />
+ <XDSBanner status="error" title="Error banner" />
+ <XDSBanner status="success" title="Success banner" />
+ </div>
+ ),
+};
+
+export const AllFeatures: Story = {
+ name: 'All Features Combined',
+ render: () => (
+ <div style={{display: 'flex', flexDirection: 'column', gap: '16px'}}>
+ <XDSBanner
+ status="info"
+ title="Simple banner"
+ description="Just the colored header area."
+ />
+ <XDSBanner
+ status="info"
+ title="With custom icon"
+ icon={<XDSIcon icon={ShieldCheckIcon} size="md" color="accent" />}
+ />
+ <XDSBanner
+ status="warning"
+ title="Dismissable"
+ description="Click the X to dismiss — works without onDismiss."
+ isDismissable
+ />
+ <XDSBanner
+ status="info"
+ title="With action button"
+ endButton={
+ <XDSButton label="Learn more" variant="secondary" size="sm" />
+ }
+ />
+ <XDSBanner
+ status="error"
+ title="With content area"
+ description="Additional content appears on a card background below.">
+ <div style={{fontSize: '13px'}}>
+ This content sits on a card-colored background, visually distinct from
+ the status header above.
+ </div>
+ </XDSBanner>
+ <XDSBanner
+ status="error"
+ title="Section variant"
+ description="Full-width with no border-radius."
+ variant="section"
+ />
+ </div>
+ ),
+};
diff --git a/packages/core/src/Banner/README.md b/packages/core/src/Banner/README.md
new file mode 100644
index 0000000000..1de2e5bcc2
--- /dev/null
+++ b/packages/core/src/Banner/README.md
@@ -0,0 +1,109 @@
+# XDSBanner
+
+Persistent status notification for info, warning, error, or success messages.
+
+## Visual Structure
+
+The banner has a two-part layout:
+
+1. **Header area** — colored status background with icon, title, description, action buttons, and dismiss
+2. **Content area** (optional) — card background below the header for additional rich content
+
+When no `children` are provided, only the colored header renders.
+
+## Usage
+
+```tsx
+import {XDSBanner} from '@xds/core/Banner';
+
+// Simple — just the colored header
+<XDSBanner status="info" title="New update available" />
+
+// With description and self-dismissing behavior
+<XDSBanner
+ status="error"
+ title="Something went wrong"
+ description="Please try again later."
+ isDismissable
+ onDismiss={() => logDismiss()}
+/>
+
+// With content area (card background below header)
+<XDSBanner
+ status="error"
+ title="Multiple errors found"
+ description="The following issues need to be resolved:"
+>
+ <ul>
+ <li>Email address is invalid</li>
+ <li>Password must be at least 8 characters</li>
+ </ul>
+</XDSBanner>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --------------- | --------------------------------------------- | -------- | ----------------------------------------------------- |
+| `status` | `'info' \| 'warning' \| 'error' \| 'success'` | — | Status type controlling icon and color (required) |
+| `title` | `ReactNode` | — | Title text or ReactNode (required) |
+| `description` | `ReactNode` | — | Description text below the title |
+| `icon` | `ReactNode` | — | Override the default status icon |
+| `isDismissable` | `boolean` | `false` | Whether the banner can be dismissed |
+| `onDismiss` | `() => void` | — | Called on dismiss (banner hides itself regardless) |
+| `endButton` | `ReactNode` | — | Action button in the header area (end-aligned) |
+| `variant` | `'card' \| 'section'` | `'card'` | Visual variant |
+| `children` | `ReactNode` | — | Content rendered in card-background area below header |
+| `xstyle` | `StyleXStyles` | — | StyleX overrides |
+| `data-testid` | `string` | — | Test ID |
+
+## Dismiss Behavior
+
+When `isDismissable` is true, the banner manages its own dismissed state internally.
+Clicking the dismiss button hides the banner immediately, even if `onDismiss` is not provided.
+This ensures product teams get working dismiss behavior out of the box without needing
+to wire up state management. The `onDismiss` callback is optional and fires alongside
+the internal state change for logging or backend sync.
+
+## Status Colors
+
+| Status | Background Token | Role |
+| --------- | ------------------------------- | -------- |
+| `info` | `--color-accent-deemphasized` | `status` |
+| `warning` | `--color-warning-deemphasized` | `alert` |
+| `error` | `--color-negative-deemphasized` | `alert` |
+| `success` | `--color-positive-deemphasized` | `status` |
+
+## Variants
+
+- **Card** (default): Has border-radius, colored header with optional card content area below
+- **Section**: No border-radius, full-width for page-level banners
+
+## Default Icons
+
+Each status has a default icon from `@heroicons/react/24/solid`:
+
+- `info` → `InformationCircleIcon`
+- `warning` → `ExclamationTriangleIcon`
+- `error` → `XCircleIcon`
+- `success` → `CheckCircleIcon`
+
+## Accessibility
+
+- Uses `role="alert"` for error/warning statuses
+- Uses `role="status"` for info/success statuses
+- Dismiss button has `aria-label="Dismiss"`
+- Status icon is `aria-hidden="true"` (status conveyed by role)
+
+## Future
+
+- **Collapsible**: Banner will support collapsing the content area via `useXDSCollapsible` (#187)
+
+## File Manifest
+
+| File | Purpose |
+| -------------------- | ------------------------ |
+| `XDSBanner.tsx` | Component implementation |
+| `XDSBanner.test.tsx` | Unit tests |
+| `index.ts` | Public exports |
+| `README.md` | Documentation |
diff --git a/packages/core/src/Banner/XDSBanner.test.tsx b/packages/core/src/Banner/XDSBanner.test.tsx
new file mode 100644
index 0000000000..2b47fa7d6e
--- /dev/null
+++ b/packages/core/src/Banner/XDSBanner.test.tsx
@@ -0,0 +1,207 @@
+/**
+ * @file XDSBanner.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSBanner component
+ * @output Unit tests for XDSBanner component behavior
+ * @position Testing; validates XDSBanner.tsx implementation
+ *
+ * SYNC: When modified, update this header
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSBanner} from './XDSBanner';
+
+describe('XDSBanner', () => {
+ it('renders with title and status', () => {
+ render(<XDSBanner status="info" title="Test Banner" />);
+ expect(screen.getByText('Test Banner')).toBeInTheDocument();
+ });
+
+ it('renders info status with role="status"', () => {
+ render(<XDSBanner status="info" title="Info" />);
+ expect(screen.getByRole('status')).toBeInTheDocument();
+ });
+
+ it('renders warning status with role="alert"', () => {
+ render(<XDSBanner status="warning" title="Warning" />);
+ expect(screen.getByRole('alert')).toBeInTheDocument();
+ });
+
+ it('renders error status with role="alert"', () => {
+ render(<XDSBanner status="error" title="Error" />);
+ expect(screen.getByRole('alert')).toBeInTheDocument();
+ });
+
+ it('renders success status with role="status"', () => {
+ render(<XDSBanner status="success" title="Success" />);
+ expect(screen.getByRole('status')).toBeInTheDocument();
+ });
+
+ it('renders default icon per status with aria-hidden', () => {
+ const {container} = render(<XDSBanner status="info" title="Info Banner" />);
+ const iconWrapper = container.querySelector('[aria-hidden="true"]');
+ expect(iconWrapper).toBeInTheDocument();
+ // Default icon should be an SVG
+ const svg = iconWrapper?.querySelector('svg');
+ expect(svg).toBeInTheDocument();
+ });
+
+ it('renders custom icon override', () => {
+ render(
+ <XDSBanner
+ status="info"
+ title="Custom Icon"
+ icon={<span data-testid="custom-icon">★</span>}
+ />,
+ );
+ expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+ });
+
+ it('renders description', () => {
+ render(
+ <XDSBanner
+ status="info"
+ title="Title"
+ description="This is a description"
+ />,
+ );
+ expect(screen.getByText('This is a description')).toBeInTheDocument();
+ });
+
+ it('does not render description when not provided', () => {
+ const {container} = render(<XDSBanner status="info" title="Title Only" />);
+ // Only one <p> for the title, no description
+ const paragraphs = container.querySelectorAll('p');
+ expect(paragraphs).toHaveLength(1);
+ });
+
+ it('renders dismiss button when isDismissable', () => {
+ render(<XDSBanner status="info" title="Dismissable" isDismissable />);
+ expect(screen.getByRole('button', {name: 'Dismiss'})).toBeInTheDocument();
+ });
+
+ it('calls onDismiss when dismiss button is clicked', async () => {
+ const user = userEvent.setup();
+ const onDismiss = vi.fn();
+ render(
+ <XDSBanner
+ status="info"
+ title="Dismissable"
+ isDismissable
+ onDismiss={onDismiss}
+ />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides banner on dismiss without onDismiss callback', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSBanner
+ status="info"
+ title="Self Dismissing"
+ isDismissable
+ data-testid="banner"
+ />,
+ );
+ expect(screen.getByTestId('banner')).toBeInTheDocument();
+ await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+ expect(screen.queryByTestId('banner')).not.toBeInTheDocument();
+ });
+
+ it('hides banner on dismiss and calls onDismiss', async () => {
+ const user = userEvent.setup();
+ const onDismiss = vi.fn();
+ render(
+ <XDSBanner
+ status="info"
+ title="Dismissable"
+ isDismissable
+ onDismiss={onDismiss}
+ data-testid="banner"
+ />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+ expect(screen.queryByTestId('banner')).not.toBeInTheDocument();
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not render dismiss button when isDismissable is false', () => {
+ render(<XDSBanner status="info" title="Not Dismissable" />);
+ expect(
+ screen.queryByRole('button', {name: 'Dismiss'}),
+ ).not.toBeInTheDocument();
+ });
+
+ it('renders endButton', () => {
+ render(
+ <XDSBanner
+ status="info"
+ title="With Action"
+ endButton={<button data-testid="end-btn">Action</button>}
+ />,
+ );
+ expect(screen.getByTestId('end-btn')).toBeInTheDocument();
+ });
+
+ it('renders card variant by default', () => {
+ const {container} = render(
+ <XDSBanner status="info" title="Card Variant" />,
+ );
+ const root = container.firstElementChild;
+ expect(root).toBeInTheDocument();
+ });
+
+ it('renders section variant', () => {
+ const {container} = render(
+ <XDSBanner status="info" title="Section Variant" variant="section" />,
+ );
+ const root = container.firstElementChild;
+ expect(root).toBeInTheDocument();
+ });
+
+ it('renders children in a separate content area below header', () => {
+ const {container} = render(
+ <XDSBanner status="info" title="With Children" description="Desc">
+ <div data-testid="child-content">Extra content</div>
+ </XDSBanner>,
+ );
+ expect(screen.getByTestId('child-content')).toBeInTheDocument();
+ expect(screen.getByText('Extra content')).toBeInTheDocument();
+ // Children should be in a separate div from the header (the content area)
+ const root = container.firstElementChild;
+ // Root should have 2 child divs: header + content area
+ expect(root?.children).toHaveLength(2);
+ });
+
+ it('does not render content area when no children', () => {
+ const {container} = render(<XDSBanner status="info" title="No Children" />);
+ const root = container.firstElementChild;
+ // Root should have only 1 child div: the header
+ expect(root?.children).toHaveLength(1);
+ });
+
+ it('supports data-testid', () => {
+ render(<XDSBanner status="info" title="Test ID" data-testid="my-banner" />);
+ expect(screen.getByTestId('my-banner')).toBeInTheDocument();
+ });
+
+ it('renders each status type correctly', () => {
+ const statuses = ['info', 'warning', 'error', 'success'] as const;
+ for (const status of statuses) {
+ const {unmount} = render(
+ <XDSBanner status={status} title={`${status} banner`} />,
+ );
+ expect(screen.getByText(`${status} banner`)).toBeInTheDocument();
+ unmount();
+ }
+ });
+
+ it('forwards ref', () => {
+ const ref = {current: null as HTMLDivElement | null};
+ render(<XDSBanner ref={ref} status="info" title="Ref Test" />);
+ expect(ref.current).toBeInstanceOf(HTMLDivElement);
+ });
+});
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
new file mode 100644
index 0000000000..20c2fbaffc
--- /dev/null
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -0,0 +1,373 @@
+/**
+ * @file XDSBanner.tsx
+ * @input Uses React forwardRef/useState, @heroicons/react/24/solid icons, XDSCloseButton, StyleX
+ * @output Exports XDSBanner component, XDSBannerProps, XDSBannerStatus, XDSBannerVariant types
+ * @position Core implementation; consumed by index.ts, tested by XDSBanner.test.tsx
+ *
+ * Visual structure:
+ * - Header area: colored status background with icon, title, description, actions, dismiss
+ * - Content area (optional): card background below the header for additional content (children)
+ * - No left border accent — color is expressed through the full header background
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Banner/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Banner/XDSBanner.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Banner/index.ts (exports if types change)
+ * - /apps/storybook/stories/Banner.stories.tsx (storybook stories)
+ */
+
+import {forwardRef, useState, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ InformationCircleIcon,
+ ExclamationTriangleIcon,
+ XCircleIcon,
+ CheckCircleIcon,
+} from '@heroicons/react/24/solid';
+import {XDSCloseButton} from '../CloseButton';
+import {XDSIcon} from '../Icon';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ textSizeVars,
+ fontWeightVars,
+ lineHeightVars,
+} from '../theme/tokens.stylex';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Status type controlling the banner's icon and color.
+ */
+export type XDSBannerStatus = 'info' | 'warning' | 'error' | 'success';
+
+/**
+ * Visual variant of the banner.
+ * - `card`: standalone card with border-radius and elevation
+ * - `section`: full-width section banner (no border-radius)
+ */
+export type XDSBannerVariant = 'card' | 'section';
+
+export interface XDSBannerProps {
+ /**
+ * Status type controlling the icon and color scheme.
+ */
+ status: XDSBannerStatus;
+ /**
+ * Title text or ReactNode displayed prominently in the header area.
+ */
+ title: ReactNode;
+ /**
+ * Optional description text below the title in the header area.
+ */
+ description?: ReactNode;
+ /**
+ * Override the default status icon.
+ */
+ icon?: ReactNode;
+ /**
+ * Whether the banner can be dismissed.
+ * When true, shows a close button and manages internal dismissed state
+ * so the banner disappears even if `onDismiss` is not provided.
+ * @default false
+ */
+ isDismissable?: boolean;
+ /**
+ * Called when the dismiss button is clicked.
+ * The banner will hide itself regardless of whether this callback is provided.
+ */
+ onDismiss?: () => void;
+ /**
+ * Action button rendered in the header area (end-aligned).
+ * Typically an XDSButton with a secondary or ghost variant.
+ *
+ * @example
+ * endButton={<XDSButton label="Retry" variant="ghost" onClick={handleRetry} />}
+ */
+ endButton?: ReactNode;
+ /**
+ * Visual variant of the banner.
+ * - `card`: standalone card with border-radius
+ * - `section`: full-width section banner (no border-radius)
+ * @default 'card'
+ */
+ variant?: XDSBannerVariant;
+ /**
+ * Extra content rendered below the header in a card-background area.
+ * Use for rich content like lists, links, or detailed information.
+ * Only renders when provided — without children, only the colored header shows.
+ */
+ children?: ReactNode;
+ /**
+ * StyleX override styles applied to the root element.
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * Test ID for the root element.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Status → Icon mapping
+// =============================================================================
+
+const defaultIcons: Record<XDSBannerStatus, typeof InformationCircleIcon> = {
+ info: InformationCircleIcon,
+ warning: ExclamationTriangleIcon,
+ error: XCircleIcon,
+ success: CheckCircleIcon,
+};
+
+// =============================================================================
+// Status → ARIA role mapping
+// =============================================================================
+
+const statusRole: Record<XDSBannerStatus, 'alert' | 'status'> = {
+ info: 'status',
+ warning: 'alert',
+ error: 'alert',
+ success: 'status',
+};
+
+// =============================================================================
+// Status → Icon color mapping
+// =============================================================================
+
+const statusIconColor = {
+ info: 'accent',
+ warning: 'warning',
+ error: 'negative',
+ success: 'positive',
+} as const;
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ // Root wrapper — handles border-radius clipping and overall shape
+ root: {
+ fontFamily: 'inherit',
+ overflow: 'clip',
+ },
+ card: {
+ borderRadius: radiusVars['--radius-container'],
+ },
+ section: {
+ borderRadius: '0',
+ },
+ // Header area — colored status background with icon, title, description, actions
+ header: {
+ display: 'flex',
+ alignItems: 'flex-start',
+ gap: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-4'],
+ },
+ // Text content area within the header
+ headerContent: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-1'],
+ flex: 1,
+ minWidth: 0,
+ },
+ title: {
+ margin: 0,
+ fontFamily: 'inherit',
+ fontSize: textSizeVars['--text-base'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ lineHeight: lineHeightVars['--leading-base'],
+ color: colorVars['--color-text-primary'],
+ },
+ description: {
+ margin: 0,
+ fontFamily: 'inherit',
+ fontSize: textSizeVars['--text-sm'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ lineHeight: lineHeightVars['--leading-base'],
+ color: colorVars['--color-text-secondary'],
+ },
+ iconWrapper: {
+ display: 'flex',
+ alignItems: 'center',
+ flexShrink: 0,
+ },
+ endArea: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ flexShrink: 0,
+ marginInlineStart: 'auto',
+ },
+ // Content area — card background for additional content below the header
+ contentArea: {
+ backgroundColor: colorVars['--color-card'],
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-4'],
+ borderLeftWidth: 1,
+ borderRightWidth: 1,
+ borderBottomWidth: 1,
+ borderLeftStyle: 'solid',
+ borderRightStyle: 'solid',
+ borderBottomStyle: 'solid',
+ borderLeftColor: colorVars['--color-divider'],
+ borderRightColor: colorVars['--color-divider'],
+ borderBottomColor: colorVars['--color-divider'],
+ },
+ contentAreaCard: {
+ borderBottomLeftRadius: radiusVars['--radius-container'],
+ borderBottomRightRadius: radiusVars['--radius-container'],
+ },
+});
+
+const statusStyles = stylex.create({
+ info: {
+ backgroundColor: colorVars['--color-accent-deemphasized'],
+ },
+ warning: {
+ backgroundColor: colorVars['--color-warning-deemphasized'],
+ },
+ error: {
+ backgroundColor: colorVars['--color-negative-deemphasized'],
+ },
+ success: {
+ backgroundColor: colorVars['--color-positive-deemphasized'],
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A persistent status notification banner for info, warning, error, or success messages.
+ *
+ * Two-part visual structure:
+ * - Header: colored status background with icon, title, description, and actions
+ * - Content (optional): card background area for additional rich content
+ *
+ * Manages its own dismissed state internally — the banner hides on dismiss
+ * even if `onDismiss` is not provided, so product teams don't need to wire
+ * up state management for basic dismiss behavior.
+ *
+ * Uses `role="alert"` for error/warning and `role="status"` for info/success.
+ *
+ * @example
+ * ```tsx
+ * // Simple banner — just the colored header
+ * <XDSBanner status="info" title="New update available" />
+ *
+ * // With description and dismiss
+ * <XDSBanner
+ * status="error"
+ * title="Something went wrong"
+ * description="Please try again later."
+ * isDismissable
+ * onDismiss={() => logDismiss()}
+ * />
+ *
+ * // With extra content in card area below
+ * <XDSBanner
+ * status="error"
+ * title="Multiple errors found"
+ * description="The following issues need to be resolved:"
+ * >
+ * <ul>
+ * <li>Email address is invalid</li>
+ * <li>Password must be at least 8 characters</li>
+ * </ul>
+ * </XDSBanner>
+ * ```
+ */
+export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
+ (
+ {
+ status,
+ title,
+ description,
+ icon,
+ isDismissable = false,
+ onDismiss,
+ endButton,
+ variant = 'card',
+ children,
+ xstyle,
+ 'data-testid': testId,
+ },
+ ref,
+ ) => {
+ const [isDismissed, setIsDismissed] = useState(false);
+ const DefaultIcon = defaultIcons[status];
+ const role = statusRole[status];
+ const iconColor = statusIconColor[status];
+
+ if (isDismissed) {
+ return null;
+ }
+
+ const handleDismiss = () => {
+ setIsDismissed(true);
+ onDismiss?.();
+ };
+
+ return (
+ <div
+ ref={ref}
+ role={role}
+ data-testid={testId}
+ {...stylex.props(
+ styles.root,
+ variant === 'card' && styles.card,
+ variant === 'section' && styles.section,
+ xstyle,
+ )}>
+ {/* Header: colored status background */}
+ <div {...stylex.props(styles.header, statusStyles[status])}>
+ <div {...stylex.props(styles.iconWrapper)} aria-hidden="true">
+ {icon != null ? (
+ icon
+ ) : (
+ <XDSIcon icon={DefaultIcon} size="md" color={iconColor} />
+ )}
+ </div>
+ <div {...stylex.props(styles.headerContent)}>
+ <p {...stylex.props(styles.title)}>{title}</p>
+ {description != null && (
+ <p {...stylex.props(styles.description)}>{description}</p>
+ )}
+ </div>
+ {(endButton != null || isDismissable) && (
+ <div {...stylex.props(styles.endArea)}>
+ {endButton}
+ {isDismissable && (
+ <XDSCloseButton
+ label="Dismiss"
+ size="sm"
+ onClick={handleDismiss}
+ />
+ )}
+ </div>
+ )}
+ </div>
+ {/* Content area: card background for additional content */}
+ {children != null && (
+ <div
+ {...stylex.props(
+ styles.contentArea,
+ variant === 'card' && styles.contentAreaCard,
+ )}>
+ {children}
+ </div>
+ )}
+ </div>
+ );
+ },
+);
+
+XDSBanner.displayName = 'XDSBanner';
diff --git a/packages/core/src/Banner/index.ts b/packages/core/src/Banner/index.ts
new file mode 100644
index 0000000000..d459e8d07e
--- /dev/null
+++ b/packages/core/src/Banner/index.ts
@@ -0,0 +1,15 @@
+/**
+ * @file index.ts
+ * @input Imports XDSBanner component and types from XDSBanner.tsx
+ * @output Exports XDSBanner, XDSBannerProps, XDSBannerStatus, XDSBannerVariant
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/Banner/README.md
+ */
+
+export {XDSBanner} from './XDSBanner';
+export type {
+ XDSBannerProps,
+ XDSBannerStatus,
+ XDSBannerVariant,
+} from './XDSBanner';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 1f5238f43f..8f3305a27c 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -11,6 +11,7 @@
export * from './AspectRatio';
export * from './Avatar';
export * from './Badge';
+export * from './Banner';
export * from './Breadcrumbs';
export * from './Button';
export * from './Card';