@boostdev/design-system-components 2.15.0 → 2.16.0

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
 

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

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

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsRating.stories';
 
 Framework-agnostic read-only star Rating custom element. Renders a row of SVG stars with filled/empty states based on `value` and `max`.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

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

@@ -15,7 +15,7 @@ function BdsRating({
 const meta = {
   title: 'Web Components/Interaction/Rating',
   component: BdsRating,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     value: { control: { type: 'range', min: 0, max: 10 } },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsSectionHeader.stories';
 
 Framework-agnostic Section Header custom element. Combines a title and optional subtitle into a consistently styled page or section heading with size and alignment variants.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -41,6 +41,15 @@ import '@boostdev/design-system-components/web-components';
 ### Centered
 <Canvas of={Stories.Centered} />
 
+### Gradient
+<Canvas of={Stories.Gradient} />
+
+<Canvas of={Stories.GradientExtraSmall} />
+
+<Canvas of={Stories.GradientSmall} />
+
+<Canvas of={Stories.GradientLarge} />
+
 ### Title only
 <Canvas of={Stories.TitleOnly} />
 
@@ -57,6 +66,7 @@ import '@boostdev/design-system-components/web-components';
 | `subtitle` | string | — | Optional subheading text |
 | `alignment` | `"start" \| "center" \| "end"` | `"start"` | Text and flex alignment |
 | `size` | `"xs" \| "small" \| "medium" \| "large"` | `"medium"` | Font size scale for title and subtitle |
+| `appearance` | `"default" \| "gradient"` | `"default"` | `gradient` fills the title with a gradient that spans the text. Falls back to the normal colour without `background-clip: text` support, and to `CanvasText` in forced-colors mode |
 | `title-as` | string | `"h2"` | Override the HTML element rendered for the title |
 
 ## Usage in plain HTML
@@ -79,13 +89,15 @@ import '@boostdev/design-system-components/web-components';
 
 | Token | Default | Description |
 |-------|---------|--------------|
+| `--sectionHeader_title-font-family` | `--bds-font_family--heading` | Title font family |
+| `--sectionHeader_title-gradient` | `linear-gradient(90deg, --bds-color_primary--strong, --bds-color_accent-3--strong)` | Title gradient, only with `appearance="gradient"` |
 | `--sectionHeader_gap` | `--bds-space_m` | Gap between title and subtitle |
-| `--sectionHeader_title-color` | `--bds-color_on-bg` | Title text color (`--sectionHeader-title-color`, kebab-delimited, is a deprecated alias) |
-| `--sectionHeader_subtitle-color` | `--bds-color_grey--strong` | Subtitle text color |
-| `--sectionHeader_title-size` | Size-variant font-size token (e.g. `--bds-font_size--display` for medium/large) | Title font size |
+| `--sectionHeader_title-color` | `--bds-color_on-bg` | Title text color; no effect with `appearance="gradient"`, where the colour comes from `--sectionHeader_title-gradient` (`--sectionHeader-title-color`, kebab-delimited, is a deprecated alias) |
+| `--sectionHeader_subtitle-color` | `--bds-color_on-bg--muted` | Subtitle text color |
+| `--sectionHeader_title-size` | `xs` body, `small` heading-3, `medium` heading-2, `large` heading-1 | Title font size |
 | `--sectionHeader_title-line-height` | Size-variant line-height token | Title line height |
-| `--sectionHeader_title-weight` | `--bds-font_weight--bold` | Title font weight |
-| `--sectionHeader_subtitle-size` | Size-variant font-size token | Subtitle font size |
+| `--sectionHeader_title-weight` | `--bds-font_weight--heading` | Title font weight |
+| `--sectionHeader_subtitle-size` | `xs` body--s, `small`/`medium` body, `large` heading-3 | Subtitle font size |
 | `--sectionHeader_subtitle-line-height` | `1.3` (medium/large) or `1.4` (xs/small) | Subtitle line height |
 
 The host also sets `grid-column: var(--bds-grid_span-100)` so the header spans the full row when placed inside `<bds-grid>`.

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

@@ -7,25 +7,28 @@ function BdsSectionHeader({
   subtitle,
   alignment = 'start',
   size = 'medium',
+  appearance = 'default',
   titleAs,
 }: {
   heading?: string;
   subtitle?: string;
   alignment?: 'start' | 'center' | 'end';
   size?: 'xs' | 'small' | 'medium' | 'large';
+  appearance?: 'default' | 'gradient';
   titleAs?: string;
 }) {
-  return React.createElement('bds-section-header', { heading, subtitle, alignment, size, 'title-as': titleAs });
+  return React.createElement('bds-section-header', { heading, subtitle, alignment, size, appearance, 'title-as': titleAs });
 }
 
 const meta = {
   title: 'Web Components/Layout/SectionHeader',
   component: BdsSectionHeader,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'padded' },
   argTypes: {
     alignment: { control: 'select', options: ['start', 'center', 'end'] },
     size:      { control: 'select', options: ['xs', 'small', 'medium', 'large'] },
+    appearance: { control: 'select', options: ['default', 'gradient'] },
     titleAs:   { control: 'text' },
   },
 } satisfies Meta<typeof BdsSectionHeader>;
@@ -54,3 +57,8 @@ export const AllSizes: Story = {
     </div>
   ),
 };
+
+export const Gradient: Story = { args: { heading: 'Gradient Header', subtitle: 'Gradient title', appearance: 'gradient' } };
+export const GradientExtraSmall: Story = { args: { heading: 'Gradient Extra Small', subtitle: 'Gradient title', appearance: 'gradient', size: 'xs' } };
+export const GradientSmall: Story = { args: { heading: 'Gradient Small', subtitle: 'Gradient title', appearance: 'gradient', size: 'small' } };
+export const GradientLarge: Story = { args: { heading: 'Gradient Large', subtitle: 'Gradient title', appearance: 'gradient', size: 'large' } };

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsSeparator.stories';
 
 Framework-agnostic Separator custom element. Renders a thin decorative line to visually divide content. Supports both horizontal and vertical orientations.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 
@@ -56,6 +56,7 @@ Or in HTML without a bundler:
 |----------|-------------|
 | `--separator_color` | Line colour (defaults to `--bds-color_on-bg--as-surface`, the non-text member of the set — a rule is not text, so it needs 3:1, not 4.5:1) |
 | `--separator_thickness` | Line thickness (default: `1px`) |
+| `--separator_spacing` | Space around the line: inline for vertical (default: `var(--bds-space_s)`), block for horizontal (default: `0`) |
 
 ## Usage in plain HTML
 

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

@@ -13,7 +13,7 @@ function BdsSeparator({
 const meta = {
   title: 'Web Components/UI/Separator',
   component: BdsSeparator,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     orientation: { control: 'radio', options: ['horizontal', 'vertical'] },
@@ -53,3 +53,15 @@ export const Vertical: Story = {
     </div>
   ),
 };
+
+export const BetweenLinks: Story = {
+  render: () => (
+    <nav aria-label="Example" style={{ display: 'flex', alignItems: 'center' }}>
+      <a href="#one">Home</a>
+      {React.createElement('bds-separator', { orientation: 'vertical' })}
+      <a href="#two">Pricing</a>
+      {React.createElement('bds-separator', { orientation: 'vertical' })}
+      <a href="#three">Contact</a>
+    </nav>
+  ),
+};

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsSkeleton.stories';
 
 Framework-agnostic Skeleton loading placeholder custom element. Displays an animated shimmer while real content is loading. Size is set via inline styles or CSS on the host element.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

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

@@ -10,7 +10,7 @@ function BdsSkeleton({ width = '200px', height = '1rem' }: { width?: string; hei
 const meta = {
   title: 'Web Components/UI/Skeleton',
   component: BdsSkeleton,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     width:  { control: 'text' },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsTable.stories';
 
 Framework-agnostic scrollable Table wrapper custom element. Apply design-system styles to a standard `<table>` element by nesting it in the default slot.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 > **Light-DOM styling contract:** `::slotted()` can only match the node placed directly into
 > the slot (the `<table>` itself), never its descendants. `<thead>`/`<th>`/`<td>` styling is
@@ -57,6 +57,10 @@ import '@boostdev/design-system-components/web-components';
 | Property | Description |
 |----------|-------------|
 | `--table_divider-color` | Colour of the header underline and row rules (default: `--bds-color_on-bg--as-surface`, the non-text member of the set — ≥ 3:1, not a ground colour) |
+| `--table_header-font-size` | Header cell font size (default: `var(--bds-font_size--body)`) |
+| `--table_header-font-weight` | Header cell font weight (default: `var(--bds-font_weight--bold)`) |
+| `--table_header-color` | Header cell text colour (default: `var(--bds-color_on-bg--subtle)`) |
+| `--table_header-bg` | Header row background (default: `var(--bds-color_bg--subtle)`) |
 | `--table_border` | Wrapper border (default: `none`) |
 | `--table_radius` | Wrapper corner radius (default: `var(--bdc-outline_radius)`, itself set to `var(--bds-border_radius--s)` on the wrapper) |
 | `--table_row-bg--hover` | Row background on hover, pointer devices only (default: `var(--bds-color_bg--subtle)`) |

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

@@ -58,7 +58,7 @@ const sampleTable = () =>
 const meta = {
   title: 'Web Components/UI/Table',
   component: BdsTable,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'fullscreen' },
   argTypes: {
     stickyHeader: { control: 'boolean' },

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

@@ -7,7 +7,7 @@ import * as Stories from './BdsTypography.stories';
 
 Framework-agnostic Typography custom element. Renders slotted text inside the appropriate semantic HTML element (`h1`–`h3`, `p`) based on the `variant` attribute, with optional tag override via `component`.
 
-> **Status: experimental** — API may change before stable release.
+> **Status: alpha** — API may change before stable release.
 
 ## Installation
 

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

@@ -18,7 +18,7 @@ function BdsTypography({
 const meta = {
   title: 'Web Components/UI/Typography',
   component: BdsTypography,
-  tags: ['!stable', 'experimental'],
+  tags: ['!stable', 'alpha'],
   parameters: { layout: 'centered' },
   argTypes: {
     variant: { control: 'select', options: ['h1', 'h2', 'h3', 'body', 'body_s'] },

package/src/web-components/ui/bds-alert.spec.ts

@@ -121,4 +121,31 @@ describe('bds-alert', () => {
     expect(div!.getAttribute('role')).toBe('alert');
     cleanup(el);
   });
+
+  it('defaults to appearance="default"', async () => {
+    const el = await fixture('<bds-alert>Message</bds-alert>');
+    expect(el.getAttribute('appearance')).toBe('default');
+    cleanup(el);
+  });
+
+  it('reflects appearance="gradient"', async () => {
+    const el = await fixture('<bds-alert appearance="gradient">Message</bds-alert>') as BdsAlert;
+    expect(el.appearance).toBe('gradient');
+    el.appearance = 'default';
+    await el.updateComplete;
+    expect(el.getAttribute('appearance')).toBe('default');
+    cleanup(el);
+  });
+
+  it('wires the gradient hooks in the styles', () => {
+    const styles = String(BdsAlert.styles);
+    expect(styles).toContain(":host([appearance='gradient']) .alert");
+    expect(styles).toMatch(/background-image:\s*var\(--alert_gradient,\s*linear-gradient\(100deg/);
+    expect(styles).toMatch(/box-shadow:\s*var\(--alert_shadow,\s*var\(--bds-shadow_s\)\)/);
+    expect(styles).toContain('--alert_border-width--variant: 3px');
+    expect(styles).toMatch(/\.alert \{[^}]*--alert_border-width--variant:\s*initial/);
+    ['info', 'success', 'warning', 'error'].forEach(v => {
+      expect(styles).toContain(`--alert_accent--${v}`);
+    });
+  });
 });

package/src/web-components/ui/bds-alert.ts

@@ -1,12 +1,14 @@
 import { LitElement, css, html, nothing } from 'lit';
 
 export type AlertVariant = 'info' | 'success' | 'warning' | 'error';
+export type AlertAppearance = 'default' | 'gradient';
 
 /**
  * `<bds-alert>` — framework-agnostic Alert custom element.
  *
  * Attributes:
  *   variant     — "info" (default) | "success" | "warning" | "error"
+ *   appearance  — "default" | "gradient" (fades the tint to the surface, 3px accent line, shadow)
  *   heading     — optional heading above the body text
  *   title       — deprecated alias for `heading`. Collides with the global HTML
  *                 `title` attribute, which triggers a native browser tooltip on
@@ -60,9 +62,12 @@ export class BdsAlert extends LitElement {
          defaults. Variants write to the inner --alert_*--variant slot. */
       background-color:    var(--alert_bg, var(--alert_bg--variant, var(--bds-color_blue--subtle)));
       color:               var(--alert_text, var(--alert_text--variant, var(--bds-color_on-blue--subtle)));
-      border-inline-start: var(--bds-space_s) solid var(--alert_border, var(--alert_border--variant, var(--bds-color_blue)));
+      border-inline-start: var(--alert_border-width, var(--alert_border-width--variant, var(--bds-space_s))) solid var(--alert_border, var(--alert_border--variant, var(--bds-color_blue)));
       font-size: var(--bds-font_size--body);
       line-height: var(--bds-font_line-height--body);
+
+      /* Reset the slot so a nested default alert does not inherit a parent's gradient width. */
+      --alert_border-width--variant: initial;
     }
 
     /* Per-variant resting overrides — consumers can theme per-variant via
@@ -91,6 +96,31 @@ export class BdsAlert extends LitElement {
       --alert_border--variant: var(--alert_border--error, var(--bds-color_error));
     }
 
+    /* Gradient appearance: the variant background stays the base colour and a
+       gradient fades it to the surface. The accent line is thinner and uses a
+       per-variant accent slot; --alert_border still wins over it. */
+    :host([appearance='gradient']) .alert {
+      --alert_border-width--variant: 3px;
+      background-image: var(--alert_gradient, linear-gradient(100deg, transparent 35%, var(--bds-color_bg--strong, var(--bds-color_bg)) 100%));
+      box-shadow: var(--alert_shadow, var(--bds-shadow_s));
+    }
+
+    :host([appearance='gradient'][variant='info']) .alert {
+      --alert_border--variant: var(--alert_border--info, var(--alert_accent--info, var(--bds-color_on-blue--subtle)));
+    }
+
+    :host([appearance='gradient'][variant='success']) .alert {
+      --alert_border--variant: var(--alert_border--success, var(--alert_accent--success, var(--bds-color_on-success--subtle)));
+    }
+
+    :host([appearance='gradient'][variant='warning']) .alert {
+      --alert_border--variant: var(--alert_border--warning, var(--alert_accent--warning, var(--bds-color_warning)));
+    }
+
+    :host([appearance='gradient'][variant='error']) .alert {
+      --alert_border--variant: var(--alert_border--error, var(--alert_accent--error, var(--bds-color_error)));
+    }
+
     /* Icon slot wrapper — hidden unless slot has content */
     .icon {
       display: none;
@@ -151,6 +181,7 @@ export class BdsAlert extends LitElement {
 
   static properties = {
     variant:     { type: String, reflect: true },
+    appearance:  { type: String, reflect: true },
     heading:     { type: String },
     title:       { type: String },
     dismissible: { type: Boolean, reflect: true },
@@ -160,6 +191,7 @@ export class BdsAlert extends LitElement {
   // `declare` annotates the type without emitting a class field initializer
   // that would shadow Lit's reactive accessors on the prototype.
   declare variant: AlertVariant;
+  declare appearance: AlertAppearance;
   declare heading: string;
   /**
    * @deprecated Use `heading` instead. Sharing the name with the global HTML
@@ -173,6 +205,7 @@ export class BdsAlert extends LitElement {
   constructor() {
     super();
     this.variant = 'info';
+    this.appearance = 'default';
     this.heading = '';
     this.title = '';
     this.dismissible = false;

package/src/web-components/ui/bds-avatar.spec.ts

@@ -1,5 +1,6 @@
 import { fixture, cleanup } from '../test/helpers';
 import { BdsAvatar } from './bds-avatar';
+import { toneFromName } from '../../components/ui/Avatar/avatarTone';
 
 describe('bds-avatar', () => {
   it('is registered as a custom element', () => {
@@ -101,4 +102,50 @@ describe('bds-avatar', () => {
     // The public --avatar_size token itself must never be set directly by a size selector.
     expect(cssText).not.toMatch(/:host\(\[size=[^)]*\]\)\s*\{\s*--avatar_size:/);
   });
+
+  it('defaults to tone="auto"', async () => {
+    const el = await fixture('<bds-avatar name="Jane Doe"></bds-avatar>');
+    expect(el.getAttribute('tone')).toBe('auto');
+    cleanup(el);
+  });
+
+  it('picks the same tone as the React Avatar for the same name', async () => {
+    const el = await fixture('<bds-avatar name="Jane Doe"></bds-avatar>');
+    const fallback = el.shadowRoot!.querySelector('.fallback');
+    expect(fallback!.classList.contains(`tone_${toneFromName('Jane Doe')}`)).toBe(true);
+    cleanup(el);
+  });
+
+  it('uses primary when there is no name', async () => {
+    const el = await fixture('<bds-avatar></bds-avatar>');
+    expect(el.shadowRoot!.querySelector('.fallback')!.classList.contains('tone_primary')).toBe(true);
+    cleanup(el);
+  });
+
+  it('falls back to the name tone for an unknown tone attribute', async () => {
+    const el = await fixture('<bds-avatar name="Jane Doe" tone="foo"></bds-avatar>');
+    expect(el.shadowRoot!.querySelector('.fallback')!.classList.contains(`tone_${toneFromName('Jane Doe')}`)).toBe(true);
+  });
+
+  it('lets an explicit tone win over auto', async () => {
+    const el = await fixture('<bds-avatar name="Jane Doe" tone="accent-2"></bds-avatar>');
+    expect(el.shadowRoot!.querySelector('.fallback')!.classList.contains('tone_accent-2')).toBe(true);
+    cleanup(el);
+  });
+
+  it('does not render a tone for image avatars', async () => {
+    const el = await fixture('<bds-avatar src="/photo.jpg" name="Jane Doe" tone="accent-1"></bds-avatar>');
+    expect(el.shadowRoot!.querySelector('.fallback')).toBeNull();
+    cleanup(el);
+  });
+
+  it('exposes a hook per tone and lets --avatar_bg and --avatar_text win', () => {
+    const cssText = BdsAvatar.styles.cssText;
+    expect(cssText).toMatch(/background-color:\s*var\(--avatar_bg,\s*var\(--avatar_bg--variant\)\)/);
+    expect(cssText).toMatch(/color:\s*var\(--avatar_text,\s*var\(--avatar_text--variant\)\)/);
+    ['primary', 'secondary', 'accent-1', 'accent-2', 'accent-3'].forEach(tone => {
+      expect(cssText).toContain(`--avatar_bg--${tone}`);
+      expect(cssText).toContain(`--avatar_text--${tone}`);
+    });
+  });
 });