@boostdev/design-system-components 2.15.0 → 2.17.0

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
 
@@ -57,6 +57,7 @@ import '@boostdev/design-system-components/web-components';
 |----------|-------------|
 | `--badge_bg` | Badge background colour |
 | `--badge_text` | Badge text colour |
+| `--badge_bg--secondary` / `--badge_text--secondary` | `secondary` variant colours (defaults `--bds-color_grey`, `--bds-color_on-grey`). The other variants have the same pair: `--badge_bg--{variant}` / `--badge_text--{variant}`. |
 | `--badge_font-size` | Font size |
 | `--badge_radius` | Border radius |
 

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
@@ -73,7 +78,11 @@ import '@boostdev/design-system-components/web-components';
 | `--banner_bg--info` / `--banner_text--info` / `--banner_border--info` | Info variant colours |
 | `--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_bg--error` / `--banner_text--error` / `--banner_border--error` | Error variant colours (defaults `--bds-color_error--subtle`, `--bds-color_on-error--subtle`, `--bds-color_error`) |
+| `--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
 
@@ -59,8 +59,11 @@ import '@boostdev/design-system-components/web-components';
 
 | Variable | Default | Description |
 |----------|---------|--------------|
-| `--rating_color` | `var(--bds-color_bg)` | Colour of unfilled stars |
+| `--rating_color` | `var(--bds-color_bg)` | Fill of unfilled stars |
 | `--rating_color--filled` | `var(--bds-color_warning)` | Colour of filled stars |
+| `--rating_stroke-color` | `var(--bds-color_on-bg--as-surface)` | Outline of unfilled stars, a non-text mark (falls back to `--bds-color_on-bg--border`, then `--bds-color_on-bg`, on foundations before 2.3.0) |
+| `--rating_stroke-color--filled` | `currentcolor` | Outline of filled stars, the filled colour by default so both kinds keep the same size |
+| `--rating_stroke-width` | `var(--bdc-outline_width)` | Outline width, in the star's 24-unit viewBox |
 
 ## Accessibility
 

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>`.