@boostdev/design-system-components 2.14.1 → 2.16.0

package/src/web-components/layout/BdsGrid.stories.tsx

@@ -70,7 +70,7 @@ const cellStyle = {
 const meta = {
   title: 'Web Components/Layout/Grid',
   component: BdsGrid,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     variant: { control: 'select', options: ['main', 'page', 'funnel', 'custom'] },

package/src/web-components/layout/BdsGridItem.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsGridItem.stories';
 
 Grid cell for `<bds-grid>`. Sets `grid-column` / `grid-row` on its host element using the foundation span tokens.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Examples
 

package/src/web-components/layout/BdsGridItem.stories.tsx

@@ -38,7 +38,7 @@ const cellStyle = {
 const meta = {
   title: 'Web Components/Layout/GridItem',
   component: BdsGridItem,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     columnSpan: {

package/src/web-components/ui/BdsAlert.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsAlert.stories';
 
 Framework-agnostic alert custom element for inline status messages. Supports four semantic variants, an optional heading, and a dismissible mode.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -38,6 +38,9 @@ import '@boostdev/design-system-components/web-components';
 ### Dismissible
 <Canvas of={Stories.Dismissible} />
 
+### Gradient
+<Canvas of={Stories.Gradient} />
+
 ## Props
 
 <ArgTypes of={Stories} />
@@ -47,6 +50,7 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Semantic colour and icon |
+| `appearance` | `"default" \| "gradient"` | `"default"` | `gradient` fades the variant tint to the surface, with a 3px accent line and a shadow |
 | `heading` | string | — | Optional heading displayed above body content |
 | `title` | string | — | **Deprecated.** Alias for `heading`, used as a fallback when `heading` is unset. Avoid: it shares its name with the global HTML `title` attribute, which makes the browser show a native tooltip on hover. Will be removed in a later major — use `heading` instead. |
 | `dismissible` | boolean | `false` | Shows a dismiss (×) button |
@@ -58,6 +62,20 @@ import '@boostdev/design-system-components/web-components';
 | `(default)` | Alert body text or content |
 | `icon` | Custom icon, placed left of the content area |
 
+## CSS Custom Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--alert_bg` / `--alert_text` / `--alert_border` | per variant | Colours for all variants. Per-variant forms: `--alert_bg--info`, `--alert_text--info`, `--alert_border--info` (and `success`, `warning`, `error`). |
+| `--alert_border-width` | `var(--bds-space_s)` (`3px` with `appearance="gradient"`) | Width of the inline-start accent line |
+| `--alert_gradient` | `linear-gradient(100deg, transparent 35%, var(--bds-color_bg--strong, var(--bds-color_bg)) 100%)` | Gradient over the variant background, `appearance="gradient"` only |
+| `--alert_shadow` | `var(--bds-shadow_s)` | Box shadow, `appearance="gradient"` only |
+| `--alert_accent--info` | `var(--bds-color_on-blue--subtle)` | Accent line colour with `appearance="gradient"`; `--alert_border--info` and `--alert_border` win |
+| `--alert_accent--success` | `var(--bds-color_on-success--subtle)` | Same, success |
+| `--alert_accent--warning` | `var(--bds-color_warning)` | Same, warning |
+| `--alert_accent--error` | `var(--bds-color_error)` | Same, error |
+| `--alert_dismiss-border` / `--alert_dismiss-radius` / `--alert_dismiss-opacity--hover` | | Dismiss button border, radius and hover opacity |
+
 ## Events
 
 | Event | Detail | Bubbles | Composed | Description |

package/src/web-components/ui/BdsAlert.stories.tsx

@@ -1,17 +1,19 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import type { AlertVariant } from './bds-alert';
+import type { AlertAppearance, AlertVariant } from './bds-alert';
 import '../index'; // auto-registers all custom elements
 
 // Thin React wrapper so Storybook controls work with the custom element's props
 function BdsAlert({
   variant = 'info',
+  appearance,
   heading,
   dismissible,
   children,
   onDismiss,
 }: {
   variant?: AlertVariant;
+  appearance?: AlertAppearance;
   heading?: string;
   dismissible?: boolean;
   children?: React.ReactNode;
@@ -19,7 +21,7 @@ function BdsAlert({
 }) {
   return React.createElement(
     'bds-alert',
-    { variant, heading, dismissible: dismissible || undefined, onbdsdismiss: onDismiss },
+    { variant, appearance, heading, dismissible: dismissible || undefined, onbdsdismiss: onDismiss },
     children,
   );
 }
@@ -27,10 +29,11 @@ function BdsAlert({
 const meta = {
   title: 'Web Components/UI/Alert',
   component: BdsAlert,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+    appearance: { control: 'select', options: ['default', 'gradient'] },
   },
 } satisfies Meta<typeof BdsAlert>;
 
@@ -58,3 +61,26 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+const gradientIcon = (path: string) =>
+  React.createElement(
+    'svg',
+    { slot: 'icon', viewBox: '0 0 24 24', width: 20, height: 20, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+    React.createElement('circle', { cx: 12, cy: 12, r: 10 }),
+    React.createElement('path', { d: path }),
+  );
+
+export const Gradient: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: 500 }}>
+      {(['info', 'success', 'warning', 'error'] as const).map(v =>
+        React.createElement(
+          'bds-alert',
+          { key: v, variant: v, appearance: 'gradient', heading: v.charAt(0).toUpperCase() + v.slice(1) },
+          gradientIcon(v === 'success' ? 'm8 12 3 3 5-6' : v === 'info' ? 'M12 16v-4M12 8h.01' : 'M12 7v6M12 16h.01'),
+          `This is a ${v} alert.`,
+        ),
+      )}
+    </div>
+  ),
+};

package/src/web-components/ui/BdsAvatar.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsAvatar.stories';
 
 Framework-agnostic Avatar custom element. Displays a user photo when `src` is provided, or falls back to initials derived from the `name` attribute.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -37,6 +37,12 @@ import '@boostdev/design-system-components/web-components';
 ### Large
 <Canvas of={Stories.Large} />
 
+### Tones
+<Canvas of={Stories.AllTones} />
+
+### Automatic tone from the name
+<Canvas of={Stories.AutoTone} />
+
 ## Props
 
 <ArgTypes of={Stories} />
@@ -49,6 +55,7 @@ import '@boostdev/design-system-components/web-components';
 | `alt` | string | `name` or `"User avatar"` | Alt text for the `<img>` element. Pass `alt=""` explicitly to mark a decorative image — an empty attribute is preserved as-is and is not replaced by `name`/`"User avatar"`. |
 | `name` | string | — | Full name; used to compute up to two initials and as `aria-label` |
 | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Diameter scale |
+| `tone` | `"auto" \| "primary" \| "secondary" \| "accent-1" \| "accent-2" \| "accent-3"` | `"auto"` | Colour of the initials fallback. `auto` picks a tone from `name` (same name, same tone; no name gives `primary`). Image avatars ignore it. |
 
 ## CSS Custom Properties
 
@@ -56,8 +63,18 @@ import '@boostdev/design-system-components/web-components';
 |----------|-------------|
 | `--avatar_size` | Diameter override (wins over the `size` attribute's preset); defaults to `3em` |
 | `--avatar_radius` | Corner radius; defaults to `var(--bds-border_radius--circle)` |
-| `--avatar_bg` | Background colour of the fallback initials circle |
-| `--avatar_text` | Text colour of the initials |
+| `--avatar_bg` | Background colour of the fallback initials circle; wins over every tone |
+| `--avatar_text` | Text colour of the initials; wins over every tone |
+| `--avatar_bg--primary` | Background for `tone="primary"`; defaults to `var(--bds-color_primary--subtle)` |
+| `--avatar_text--primary` | Text colour for `tone="primary"`; defaults to `var(--bds-color_on-primary--subtle)` |
+| `--avatar_bg--secondary` | Background for `tone="secondary"`; defaults to `var(--bds-color_secondary--subtle)` |
+| `--avatar_text--secondary` | Text colour for `tone="secondary"`; defaults to `var(--bds-color_on-secondary--subtle)` |
+| `--avatar_bg--accent-1` | Background for `tone="accent-1"`; defaults to `var(--bds-color_accent-1--subtle)` |
+| `--avatar_text--accent-1` | Text colour for `tone="accent-1"`; defaults to `var(--bds-color_on-accent-1--subtle)` |
+| `--avatar_bg--accent-2` | Background for `tone="accent-2"`; defaults to `var(--bds-color_accent-2--subtle)` |
+| `--avatar_text--accent-2` | Text colour for `tone="accent-2"`; defaults to `var(--bds-color_on-accent-2--subtle)` |
+| `--avatar_bg--accent-3` | Background for `tone="accent-3"`; defaults to `var(--bds-color_accent-3--subtle)` |
+| `--avatar_text--accent-3` | Text colour for `tone="accent-3"`; defaults to `var(--bds-color_on-accent-3--subtle)` |
 
 ## Usage in plain HTML
 

package/src/web-components/ui/BdsAvatar.stories.tsx

@@ -7,22 +7,25 @@ function BdsAvatar({
   alt,
   name,
   size = 'medium',
+  tone = 'auto',
 }: {
   src?: string;
   alt?: string;
   name?: string;
   size?: 'small' | 'medium' | 'large';
+  tone?: 'auto' | 'primary' | 'secondary' | 'accent-1' | 'accent-2' | 'accent-3';
 }) {
-  return React.createElement('bds-avatar', { src, alt, name, size });
+  return React.createElement('bds-avatar', { src, alt, name, size, tone });
 }
 
 const meta = {
   title: 'Web Components/UI/Avatar',
   component: BdsAvatar,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     size: { control: 'select', options: ['small', 'medium', 'large'] },
+    tone: { control: 'select', options: ['auto', 'primary', 'secondary', 'accent-1', 'accent-2', 'accent-3'] },
   },
 } satisfies Meta<typeof BdsAvatar>;
 
@@ -46,3 +49,23 @@ export const AllSizes: Story = {
     </div>
   ),
 };
+
+export const AllTones: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
+      {['primary', 'secondary', 'accent-1', 'accent-2', 'accent-3'].map(tone =>
+        React.createElement('bds-avatar', { key: tone, name: tone, tone }),
+      )}
+    </div>
+  ),
+};
+
+export const AutoTone: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
+      {['Jane Doe', 'Bjorn Boonen', 'Sam Visser', 'Noor de Vries', 'Lars Bakker'].map(name =>
+        React.createElement('bds-avatar', { key: name, name }),
+      )}
+    </div>
+  ),
+};

package/src/web-components/ui/BdsBadge.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsBadge.stories';
 
 Framework-agnostic badge custom element for short status labels and counts. Five semantic variants covering the common status palette.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsBadge.stories.tsx

@@ -11,7 +11,7 @@ function BdsBadge({ variant = 'primary', children }: { variant?: BadgeVariant; c
 const meta = {
   title: 'Web Components/UI/Badge',
   component: BdsBadge,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     variant: { control: 'select', options: ['primary', 'secondary', 'success', 'error', 'warning'] },

package/src/web-components/ui/BdsBreadcrumb.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsBreadcrumb.stories';
 
 Framework-agnostic Breadcrumb custom element. Renders a horizontal navigation trail from a JSON array of `{ label, href? }` items. The last item is treated as the current page and rendered without a link. Non-last items without an `href` render as plain (non-interactive) text instead of an unusable link.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsBreadcrumb.stories.tsx

@@ -10,7 +10,7 @@ function BdsBreadcrumb({ items = [] }: { items?: BreadcrumbItem[] }) {
 const meta = {
   title: 'Web Components/UI/Breadcrumb',
   component: BdsBreadcrumb,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
 } satisfies Meta<typeof BdsBreadcrumb>;
 

package/src/web-components/ui/BdsButtonContainer.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsButtonContainer.stories';
 
 Framework-agnostic layout wrapper for a row of action buttons (Cancel / Confirm, Back / Next). Web-component port of the React `ButtonContainer`.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 Buttons stack vertically (primary on top, via `column-reverse`) on narrow containers and lay out in a row once the container is at least `30rem` wide. The `variant` controls alignment: `flow` (multi-step navigation), `card` (single-form submit), `modal` (dialog actions, aligned end), `content` (inline actions, aligned start).
 

package/src/web-components/ui/BdsButtonContainer.stories.tsx

@@ -18,7 +18,7 @@ function BdsButtonContainer({
 const meta = {
   title: 'Web Components/Layout/ButtonContainer',
   component: BdsButtonContainer,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     variant: { control: 'radio', options: ['flow', 'card', 'modal', 'content'] },

package/src/web-components/ui/BdsCalendar.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsCalendar.stories';
 
 Framework-agnostic Calendar date picker custom element. Renders a keyboard-navigable month grid for selecting a date. Participates in HTML forms via the Form-Associated Custom Elements API.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsCalendar.stories.tsx

@@ -20,7 +20,7 @@ function BdsCalendar({
 const meta = {
   title: 'Web Components/UI/Calendar',
   component: BdsCalendar,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     value:          { control: 'text' },

package/src/web-components/ui/BdsCalendarRange.mdx

@@ -8,7 +8,7 @@ import * as Stories from './BdsCalendarRange.stories';
 Form-associated range date picker custom element. Two-click selection with
 hover/focus preview; value is an ISO range `"YYYY-MM-DD/YYYY-MM-DD"`.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsCalendarRange.stories.tsx

@@ -13,7 +13,7 @@ function BdsCalendarRange({
 const meta = {
   title: 'Web Components/UI/CalendarRange',
   component: BdsCalendarRange,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     value:  { control: 'text' },

package/src/web-components/ui/BdsCard.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsCard.stories';
 
 Framework-agnostic Card layout custom element. A versatile container with three visual variants, five padding variants, text alignment, and an optional clickable mode. Each padding variant's resolved value can be overridden via the `--card_padding` CSS custom property.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsCard.stories.tsx

@@ -34,7 +34,7 @@ function BdsCard({
 const meta = {
   title: 'Web Components/Layout/Card',
   component: BdsCard,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     variant:   { control: 'select', options: ['default', 'elevated', 'outlined'] },

package/src/web-components/ui/BdsCarousel.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsCarousel.stories';
 
 Framework-agnostic Carousel custom element. A scroll-snap based slider where each direct child becomes a slide. Supports dot indicators, looping, and custom previous/next buttons via named slots.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsCarousel.stories.tsx

@@ -47,7 +47,7 @@ const slides = ['Slide 1', 'Slide 2', 'Slide 3'].map(label =>
 const meta = {
   title: 'Web Components/UI/Carousel',
   component: BdsCarousel,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     currentIndex: { control: 'number' },

package/src/web-components/ui/BdsDescriptionList.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsDescriptionList.stories';
 
 Framework-agnostic Description List custom element. Wraps slotted `<dt>`/`<dd>` pairs in a styled `<dl>` with stacked or inline layout.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsDescriptionList.stories.tsx

@@ -15,7 +15,7 @@ function BdsDescriptionList({
 const meta = {
   title: 'Web Components/UI/DescriptionList',
   component: BdsDescriptionList,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     layout: { control: 'radio', options: ['stacked', 'inline'] },

package/src/web-components/ui/BdsIconWrapper.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsIconWrapper.stories';
 
 Framework-agnostic Icon Wrapper custom element. Displays a slotted icon inside a circular container with design-system background and foreground colour theming.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsIconWrapper.stories.tsx

@@ -25,7 +25,7 @@ function BdsIconWrapper({
 const meta = {
   title: 'Web Components/Layout/IconWrapper',
   component: BdsIconWrapper,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     ariaHidden: { control: 'text' },

package/src/web-components/ui/BdsLink.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsLink.stories';
 
 Framework-agnostic Link custom element. Renders a styled `<a>` tag with three visual variants, automatic external link handling, and design-token colours.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsLink.stories.tsx

@@ -34,7 +34,7 @@ function BdsLink({
 const meta = {
   title: 'Web Components/UI/Link',
   component: BdsLink,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     variant:  { control: 'select', options: ['default', 'subtle', 'standalone'] },

package/src/web-components/ui/BdsLoading.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsLoading.stories';
 
 Framework-agnostic Loading spinner custom element. Displays an animated circular spinner to indicate that a process is in progress.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsLoading.stories.tsx

@@ -9,7 +9,7 @@ function BdsLoading({ size = 'medium' }: { size?: 'small' | 'medium' | 'large' }
 const meta = {
   title: 'Web Components/UI/Loading',
   component: BdsLoading,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     size: { control: 'select', options: ['small', 'medium', 'large'] },

package/src/web-components/ui/BdsNotificationBanner.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsNotificationBanner.stories';
 
 Framework-agnostic Notification Banner custom element. Renders a full-width status banner at the top of a page or section with optional dismiss button and action slot.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -38,6 +38,9 @@ import '@boostdev/design-system-components/web-components';
 ### Error
 <Canvas of={Stories.Error} />
 
+### Gradient
+<Canvas of={Stories.Gradient} />
+
 ### Dismissible
 <Canvas of={Stories.Dismissible} />
 
@@ -53,6 +56,7 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `variant` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Visual style and semantic urgency |
+| `appearance` | `"default" \| "gradient"` | `"default"` | `gradient` fades the variant tint to the surface and adds a shadow |
 | `dismissible` | boolean | `false` | Shows a dismiss (×) button |
 | `dismiss-label` | string | `"Dismiss notification"` | `aria-label` for the dismiss button |
 
@@ -61,6 +65,7 @@ import '@boostdev/design-system-components/web-components';
 | Slot | Description |
 |------|-------------|
 | `(default)` | Banner body text or HTML |
+| `icon` | Optional icon before the content (rendered `aria-hidden`) |
 | `action` | Optional action area (e.g. a `<button>` or `<a>`) |
 
 ## CSS Custom Properties
@@ -74,6 +79,10 @@ import '@boostdev/design-system-components/web-components';
 | `--banner_bg--success` / `--banner_text--success` / `--banner_border--success` | Success variant colours |
 | `--banner_bg--warning` / `--banner_text--warning` / `--banner_border--warning` | Warning variant colours |
 | `--banner_bg--error` / `--banner_text--error` / `--banner_border--error` | Error variant colours |
+| `--banner_border-width` | Width of the block-end accent line (default `3px`) |
+| `--banner_gradient` | Gradient over the variant background, `appearance="gradient"` only (default `linear-gradient(100deg, transparent 35%, var(--bds-color_bg--strong, var(--bds-color_bg)) 100%)`) |
+| `--banner_shadow` | Box shadow, `appearance="gradient"` only (default `var(--bds-shadow_s)`) |
+| `--banner_accent--info` / `--banner_accent--success` / `--banner_accent--warning` / `--banner_accent--error` | Accent line colour with `appearance="gradient"` (defaults `--bds-color_on-blue--subtle`, `--bds-color_on-success--subtle`, `--bds-color_warning`, `--bds-color_error`). `--banner_border--{variant}` and `--banner_border` win. |
 | `--banner_dismiss-size` | Dismiss button minimum touch target (default `2.75rem`, WCAG 2.5.5); the visible icon stays 1rem |
 | `--banner_dismiss-radius` | Dismiss button border radius |
 | `--banner_dismiss-border` | Dismiss button border |

package/src/web-components/ui/BdsNotificationBanner.stories.tsx

@@ -1,16 +1,18 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import type { NotificationBannerVariant } from './bds-notification-banner';
+import type { NotificationBannerAppearance, NotificationBannerVariant } from './bds-notification-banner';
 import '../index'; // auto-registers all custom elements
 
 function BdsNotificationBanner({
   variant = 'info',
+  appearance,
   dismissible,
   dismissLabel,
   children,
   action,
 }: {
   variant?: NotificationBannerVariant;
+  appearance?: NotificationBannerAppearance;
   dismissible?: boolean;
   dismissLabel?: string;
   children?: React.ReactNode;
@@ -20,6 +22,7 @@ function BdsNotificationBanner({
     'bds-notification-banner',
     {
       variant,
+      appearance,
       dismissible: dismissible || undefined,
       'dismiss-label': dismissLabel,
     },
@@ -33,10 +36,11 @@ function BdsNotificationBanner({
 const meta = {
   title: 'Web Components/UI/NotificationBanner',
   component: BdsNotificationBanner,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'fullscreen' },
   argTypes: {
     variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+    appearance: { control: 'select', options: ['default', 'gradient'] },
     dismissible: { control: 'boolean' },
   },
 } satisfies Meta<typeof BdsNotificationBanner>;
@@ -82,3 +86,26 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+const gradientIcon = (path: string) =>
+  React.createElement(
+    'svg',
+    { slot: 'icon', viewBox: '0 0 24 24', width: 20, height: 20, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+    React.createElement('circle', { cx: 12, cy: 12, r: 10 }),
+    React.createElement('path', { d: path }),
+  );
+
+export const Gradient: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      {(['info', 'success', 'warning', 'error'] as const).map(v =>
+        React.createElement(
+          'bds-notification-banner',
+          { key: v, variant: v, appearance: 'gradient' },
+          gradientIcon(v === 'success' ? 'm8 12 3 3 5-6' : v === 'info' ? 'M12 16v-4M12 8h.01' : 'M12 7v6M12 16h.01'),
+          `This is a ${v} notification banner.`,
+        ),
+      )}
+    </div>
+  ),
+};

package/src/web-components/ui/BdsPagination.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsPagination.stories';
 
 Framework-agnostic Pagination navigation custom element. Renders previous/next buttons and a page number list with smart ellipsis truncation.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsPagination.stories.tsx

@@ -18,7 +18,7 @@ function BdsPagination({
 const meta = {
   title: 'Web Components/UI/Pagination',
   component: BdsPagination,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     currentPage: { control: { type: 'number', min: 1 } },

package/src/web-components/ui/BdsProgress.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsProgress.stories';
 
 Framework-agnostic horizontal Progress bar custom element. Tracks progress toward a goal with optional label and percentage display.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

package/src/web-components/ui/BdsProgress.stories.tsx

@@ -27,7 +27,7 @@ function BdsProgress({
 const meta = {
   title: 'Web Components/UI/Progress',
   component: BdsProgress,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     value:     { control: { type: 'range', min: 0, max: 100 } },

package/src/web-components/ui/BdsProgressCircle.mdx

@@ -7,7 +7,7 @@ import * as Stories from './BdsProgressCircle.stories';
 
 Framework-agnostic circular Progress custom element. Renders an SVG ring that fills proportionally to the `value` attribute, with an optional centred percentage label.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation