@boostdev/design-system-components 2.15.0 → 2.17.0

package/src/components/layout/SectionHeader/SectionHeader.spec.tsx

@@ -1,4 +1,6 @@
 import { render, screen } from '@testing-library/react';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { SectionHeader } from './SectionHeader';
 
 describe('SectionHeader', () => {
@@ -33,4 +35,46 @@ describe('SectionHeader', () => {
     const { container } = render(<SectionHeader title="XS Title" size="xs" />);
     expect(container.firstChild).toHaveClass('--xs');
   });
+
+  it.each(['xs', 'small', 'medium', 'large'] as const)('maps the %s size to its own class', (size) => {
+    const { container } = render(<SectionHeader title="Title" size={size} />);
+    expect(container.firstChild).toHaveClass(`--${size}`);
+  });
+
+  it('does not add the gradient class by default', () => {
+    const { container } = render(<SectionHeader title="Title" />);
+    expect(container.firstChild).not.toHaveClass('--gradient');
+  });
+
+  it('adds the gradient class for appearance="gradient"', () => {
+    const { container } = render(<SectionHeader title="Title" appearance="gradient" />);
+    expect(container.firstChild).toHaveClass('--gradient');
+  });
+
+  describe('styles', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/layout/SectionHeader/SectionHeader.module.css'), 'utf8');
+
+    it('gives every size its own title and subtitle token', () => {
+      const table: Record<string, [string, string]> = {
+        xs: ['body', 'body--s'],
+        small: ['heading-3', 'body'],
+        medium: ['heading-2', 'body'],
+        large: ['heading-1', 'heading-3'],
+      };
+      Object.entries(table).forEach(([size, [title, subtitle]]) => {
+        expect(css).toMatch(new RegExp(`\\.--${size} \\.title \\{[^}]*--sectionHeader_title-size, var\\(--bds-font_size--${title}\\)`));
+        expect(css).toMatch(new RegExp(`\\.--${size} \\.subtitle \\{[^}]*--sectionHeader_subtitle-size, var\\(--bds-font_size--${subtitle}\\)`));
+      });
+    });
+
+    it('uses the heading font family and muted subtitle colour by default', () => {
+      expect(css).toMatch(/--sectionHeader_title-font-family, var\(--bds-font_family--heading\)/);
+      expect(css).toMatch(/--sectionHeader_subtitle-color, var\(--bds-color_on-bg--muted, var\(--bds-color_grey--strong\)\)/);
+    });
+
+    it('clips the gradient to the text inside @supports with a forced-colors fallback', () => {
+      expect(css).toMatch(/@supports \(background-clip: text\)[^]*--sectionHeader_title-gradient[^]*background-clip: text/);
+      expect(css).toMatch(/@media \(forced-colors: active\)[^]*CanvasText/);
+    });
+  });
 });

package/src/components/layout/SectionHeader/SectionHeader.stories.tsx

@@ -7,6 +7,7 @@ const meta = {
   argTypes: {
     alignment: { control: 'select', options: ['start', 'center', 'end'] },
     size: { control: 'select', options: ['xs', 'small', 'medium', 'large'] },
+    appearance: { control: 'select', options: ['default', 'gradient'] },
   },
 } satisfies Meta<typeof SectionHeader>;
 
@@ -19,3 +20,7 @@ export const Centered: Story = { args: { title: 'Centered Title', subtitle: 'Cen
 export const ExtraSmall: Story = { args: { title: 'Extra Small Header', subtitle: 'Extra small size.', size: 'xs' } };
 export const Small: Story = { args: { title: 'Small Header', subtitle: 'Small size.', size: 'small' } };
 export const Large: Story = { args: { title: 'Large Header', subtitle: 'Large size.', size: 'large' } };
+export const Gradient: Story = { args: { title: 'Gradient Header', subtitle: 'Gradient title.', appearance: 'gradient' } };
+export const GradientExtraSmall: Story = { args: { title: 'Gradient Extra Small', subtitle: 'Gradient title.', appearance: 'gradient', size: 'xs' } };
+export const GradientSmall: Story = { args: { title: 'Gradient Small', subtitle: 'Gradient title.', appearance: 'gradient', size: 'small' } };
+export const GradientLarge: Story = { args: { title: 'Gradient Large', subtitle: 'Gradient title.', appearance: 'gradient', size: 'large' } };

package/src/components/layout/SectionHeader/SectionHeader.tsx

@@ -10,6 +10,7 @@ type SectionHeaderProps = WithClassName & Omit<HTMLAttributes<HTMLDivElement>, '
   subtitle?: string;
   alignment?: 'start' | 'center' | 'end';
   size?: 'xs' | 'small' | 'medium' | 'large';
+  appearance?: 'default' | 'gradient';
   titleAs?: IntrinsicElement;
 };
 
@@ -19,12 +20,13 @@ export function SectionHeader({
   className,
   alignment = 'start',
   size = 'medium',
+  appearance = 'default',
   titleAs = 'h2',
   ...rest
 }: Readonly<SectionHeaderProps>) {
   const Title = titleAs;
   return (
-    <div {...rest} className={cn(css.sectionHeader, css[`--${alignment}`], css[`--${size}`], className)}>
+    <div {...rest} className={cn(css.sectionHeader, css[`--${alignment}`], css[`--${size}`], appearance === 'gradient' && css['--gradient'], className)}>
       <Title className={css.title}>{title}</Title>
       {subtitle && <p className={css.subtitle}>{subtitle}</p>}
     </div>

package/src/components/ui/Alert/Alert.mdx

@@ -38,6 +38,10 @@ Inline contextual feedback message. Use for confirmations, warnings, errors, and
 ### Dismissible
 <Canvas of={Stories.Dismissible} />
 
+### Gradient
+`appearance="gradient"` fades the variant tint to the surface, uses a 3px accent line and a shadow. The default appearance is unchanged.
+<Canvas of={Stories.Gradient} />
+
 ## Props
 
 > **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
@@ -72,6 +76,13 @@ The override surface is **layered**. Setting a public token on the alert (or any
 <tr><td>`--alert_bg`</td><td>per variant</td><td>Background colour. Set this to theme every variant at once.</td></tr>
 <tr><td>`--alert_text`</td><td>per variant</td><td>Text and icon colour.</td></tr>
 <tr><td>`--alert_border`</td><td>per variant</td><td>Inline-start border (the coloured strip).</td></tr>
+<tr><td>`--alert_border-width`</td><td>`var(--bds-space_s)` (`3px` with `appearance="gradient"`)</td><td>Width of the inline-start accent line.</td></tr>
+<tr><td>`--alert_gradient`</td><td>`linear-gradient(100deg, transparent 35%, var(--bds-color_bg--strong, var(--bds-color_bg)) 100%)`</td><td>Gradient laid over the variant background. Only used with `appearance="gradient"`.</td></tr>
+<tr><td>`--alert_shadow`</td><td>`var(--bds-shadow_s)`</td><td>Box shadow. Only used with `appearance="gradient"`; the default appearance has none.</td></tr>
+<tr><td>`--alert_accent--info`</td><td>`var(--bds-color_on-blue--subtle)`</td><td>Accent line colour of the info variant with `appearance="gradient"`. `--alert_border--info` and `--alert_border` win over it.</td></tr>
+<tr><td>`--alert_accent--success`</td><td>`var(--bds-color_on-success--subtle)`</td><td>Same, success variant.</td></tr>
+<tr><td>`--alert_accent--warning`</td><td>`var(--bds-color_warning)`</td><td>Same, warning variant.</td></tr>
+<tr><td>`--alert_accent--error`</td><td>`var(--bds-color_error)`</td><td>Same, error variant.</td></tr>
 <tr><td>`--alert_radius`</td><td>`var(--bds-border_radius--s)`</td><td>Root border radius.</td></tr>
 <tr><td>`--alert_dismiss-border`</td><td>`none`</td><td>Dismiss button border.</td></tr>
 <tr><td>`--alert_dismiss-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Dismiss button border radius.</td></tr>
@@ -105,7 +116,7 @@ Each variant's actual default resolution:
 <tr><td>`info`</td><td>`--bds-color_blue--subtle`</td><td>`--bds-color_on-blue--subtle`</td><td>`--bds-color_blue`</td></tr>
 <tr><td>`success`</td><td>`--bds-color_success--subtle`</td><td>`--bds-color_on-success--subtle`</td><td>`--bds-color_success`</td></tr>
 <tr><td>`warning`</td><td>`--bds-color_orange--subtle`</td><td>`--bds-color_on-orange--subtle`</td><td>`--bds-color_warning`</td></tr>
-<tr><td>`error`</td><td>relative-colour mix of `--bds-color_error` (12% alpha)</td><td>`--bds-color_on-bg`</td><td>`--bds-color_error`</td></tr>
+<tr><td>`error`</td><td>`--bds-color_error--subtle`</td><td>`--bds-color_on-error--subtle`</td><td>`--bds-color_error`</td></tr>
 </tbody>
 </table>
 

package/src/components/ui/Alert/Alert.module.css

@@ -11,9 +11,12 @@
            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
@@ -37,11 +40,37 @@
     }
 
     .--variant_error {
-        --alert_bg--variant:     var(--alert_bg--error, rgb(from var(--bds-color_error) r g b / 12%));
-        --alert_text--variant:   var(--alert_text--error, var(--bds-color_on-bg));
+        --alert_bg--variant:     var(--alert_bg--error, var(--bds-color_error--subtle));
+        --alert_text--variant:   var(--alert_text--error, var(--bds-color_on-error--subtle));
         --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. */
+    .--appearance_gradient {
+        --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));
+    }
+
+    .--appearance_gradient.--variant_info {
+        --alert_border--variant: var(--alert_border--info, var(--alert_accent--info, var(--bds-color_on-blue--subtle)));
+    }
+
+    .--appearance_gradient.--variant_success {
+        --alert_border--variant: var(--alert_border--success, var(--alert_accent--success, var(--bds-color_on-success--subtle)));
+    }
+
+    .--appearance_gradient.--variant_warning {
+        --alert_border--variant: var(--alert_border--warning, var(--alert_accent--warning, var(--bds-color_warning)));
+    }
+
+    .--appearance_gradient.--variant_error {
+        --alert_border--variant: var(--alert_border--error, var(--alert_accent--error, var(--bds-color_error)));
+    }
+
     .icon {
         display: flex;
         align-items: center;

package/src/components/ui/Alert/Alert.spec.tsx

@@ -80,4 +80,31 @@ describe('Alert', () => {
     expect(dismissRule).toMatch(/min-inline-size:\s*var\(--alert_dismiss-size,\s*2\.75rem\)/);
     expect(dismissRule).toMatch(/min-block-size:\s*var\(--alert_dismiss-size,\s*2\.75rem\)/);
   });
+
+  it('adds the gradient appearance class with appearance="gradient"', () => {
+    render(<Alert appearance="gradient">Message</Alert>);
+    expect(screen.getByRole('status').className).toMatch(/appearance_gradient/);
+  });
+
+  it('does not add the gradient class by default', () => {
+    render(<Alert>Message</Alert>);
+    expect(screen.getByRole('status').className).not.toMatch(/appearance_gradient/);
+  });
+
+  it('wires the gradient hooks in the CSS', () => {
+    expect(cssSource).toMatch(/background-image:\s*var\(--alert_gradient,\s*linear-gradient\(100deg/);
+    expect(cssSource).toMatch(/box-shadow:\s*var\(--alert_shadow,\s*var\(--bds-shadow_s\)\)/);
+    expect(cssSource).toMatch(/--alert_border-width--variant:\s*3px/);
+    expect(cssSource).toMatch(/\.alert \{[^}]*--alert_border-width--variant:\s*initial/);
+    expect(cssSource).toMatch(/var\(--alert_border-width,\s*var\(--alert_border-width--variant,\s*var\(--bds-space_s\)\)\)/);
+    ['info', 'success', 'warning', 'error'].forEach(v => {
+      expect(cssSource).toContain(`--alert_accent--${v}`);
+    });
+  });
+
+  it('paints the error variant with the error subtle pair, like the other variants', () => {
+    expect(cssSource).toMatch(/\.--variant_error \{[^}]*--alert_bg--variant:\s*var\(--alert_bg--error,\s*var\(--bds-color_error--subtle\)\)/);
+    expect(cssSource).toMatch(/\.--variant_error \{[^}]*--alert_text--variant:\s*var\(--alert_text--error,\s*var\(--bds-color_on-error--subtle\)\)/);
+    expect(cssSource).not.toContain('rgb(from var(--bds-color_error)');
+  });
 });

package/src/components/ui/Alert/Alert.stories.tsx

@@ -2,11 +2,19 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { Alert } from './Alert';
 
+const icons = {
+  info: <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="12" cy="12" r="10" /><path d="M12 16v-4M12 8h.01" /></svg>,
+  success: <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="12" cy="12" r="10" /><path d="m8 12 3 3 5-6" /></svg>,
+  warning: <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 3 2 21h20L12 3Z" /><path d="M12 10v5M12 18h.01" /></svg>,
+  error: <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="12" cy="12" r="10" /><path d="M12 7v6M12 16h.01" /></svg>,
+};
+
 const meta = {
   title: 'React/UI/Alert',
   component: Alert,
   argTypes: {
     variant: { control: 'select', options: ['info', 'success', 'warning', 'error'] },
+    appearance: { control: 'select', options: ['default', 'gradient'] },
   },
 } satisfies Meta<typeof Alert>;
 
@@ -50,3 +58,15 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+export const Gradient: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+      {(['info', 'success', 'warning', 'error'] as const).map(v => (
+        <Alert key={v} variant={v} appearance="gradient" icon={icons[v]} title={v.charAt(0).toUpperCase() + v.slice(1)}>
+          This is a {v} alert message.
+        </Alert>
+      ))}
+    </div>
+  ),
+};

package/src/components/ui/Alert/Alert.tsx

@@ -5,6 +5,7 @@ import type { WithClassName } from '../../../types';
 
 interface AlertProps extends WithClassName, Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
   variant?: 'info' | 'success' | 'warning' | 'error';
+  appearance?: 'default' | 'gradient';
   icon?: ReactNode;
   title?: string;
   onDismiss?: () => void;
@@ -12,6 +13,7 @@ interface AlertProps extends WithClassName, Omit<HTMLAttributes<HTMLDivElement>,
 
 export function Alert({
   variant = 'info',
+  appearance = 'default',
   icon,
   title,
   children,
@@ -27,7 +29,12 @@ export function Alert({
       role={isUrgent ? 'alert' : 'status'}
       aria-live={isUrgent ? 'assertive' : 'polite'}
       aria-atomic="true"
-      className={cn(css.alert, css[`--variant_${variant}`], className)}
+      className={cn(
+        css.alert,
+        css[`--variant_${variant}`],
+        appearance === 'gradient' && css['--appearance_gradient'],
+        className,
+      )}
     >
       {icon && (
         <span className={css.icon} aria-hidden="true">

package/src/components/ui/Avatar/Avatar.mdx

@@ -22,6 +22,12 @@ Circular user representation. Displays a profile image when available, falling b
 ### All sizes
 <Canvas of={Stories.AllSizes} />
 
+### Tones
+<Canvas of={Stories.AllTones} />
+
+### Automatic tone from the name
+<Canvas of={Stories.AutoTone} />
+
 ### Single name (one initial)
 <Canvas of={Stories.SingleName} />
 
@@ -34,6 +40,10 @@ Circular user representation. Displays a profile image when available, falling b
 
 <ArgTypes of={Stories} />
 
+## Tone
+
+`tone` colours the initials fallback with the subtle set of a palette: `'auto'` (default), `'primary'`, `'secondary'`, `'accent-1'`, `'accent-2'` or `'accent-3'`. With `auto` the tone is picked from `name`, so the same name always gets the same colour; no name gives `primary`. Image avatars ignore `tone`.
+
 ## CSS variables
 
 The override surface is **layered** — `--avatar_size` wins over the per-`size`-prop default, so you can theme one avatar or every avatar under an ancestor selector.
@@ -45,8 +55,18 @@ The override surface is **layered** — `--avatar_size` wins over the per-`size`
 <tbody>
 <tr><td>`--avatar_size`</td><td>per `size` (`2em` / `3em` / `4.5em`)</td><td>Avatar diameter. Set on the avatar or an ancestor to override the `size` prop's default.</td></tr>
 <tr><td>`--avatar_radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Avatar corner radius</td></tr>
-<tr><td>`--avatar_bg`</td><td>`var(--bds-color_blue)`</td><td>Background colour for the initials fallback</td></tr>
-<tr><td>`--avatar_text`</td><td>`var(--bds-color_on-blue)`</td><td>Text colour for the initials</td></tr>
+<tr><td>`--avatar_bg`</td><td>per `tone`</td><td>Background colour for the initials fallback; wins over every tone</td></tr>
+<tr><td>`--avatar_text`</td><td>per `tone`</td><td>Text colour for the initials; wins over every tone</td></tr>
+<tr><td>`--avatar_bg--primary`</td><td>`var(--bds-color_primary--subtle)`</td><td>Background for `tone="primary"`</td></tr>
+<tr><td>`--avatar_text--primary`</td><td>`var(--bds-color_on-primary--subtle)`</td><td>Text for `tone="primary"`</td></tr>
+<tr><td>`--avatar_bg--secondary`</td><td>`var(--bds-color_secondary--subtle)`</td><td>Background for `tone="secondary"`</td></tr>
+<tr><td>`--avatar_text--secondary`</td><td>`var(--bds-color_on-secondary--subtle)`</td><td>Text for `tone="secondary"`</td></tr>
+<tr><td>`--avatar_bg--accent-1`</td><td>`var(--bds-color_accent-1--subtle)`</td><td>Background for `tone="accent-1"`</td></tr>
+<tr><td>`--avatar_text--accent-1`</td><td>`var(--bds-color_on-accent-1--subtle)`</td><td>Text for `tone="accent-1"`</td></tr>
+<tr><td>`--avatar_bg--accent-2`</td><td>`var(--bds-color_accent-2--subtle)`</td><td>Background for `tone="accent-2"`</td></tr>
+<tr><td>`--avatar_text--accent-2`</td><td>`var(--bds-color_on-accent-2--subtle)`</td><td>Text for `tone="accent-2"`</td></tr>
+<tr><td>`--avatar_bg--accent-3`</td><td>`var(--bds-color_accent-3--subtle)`</td><td>Background for `tone="accent-3"`</td></tr>
+<tr><td>`--avatar_text--accent-3`</td><td>`var(--bds-color_on-accent-3--subtle)`</td><td>Text for `tone="accent-3"`</td></tr>
 </tbody>
 </table>
 

package/src/components/ui/Avatar/Avatar.module.css

@@ -16,11 +16,38 @@
   }
 
   .avatar.--fallback {
-    background-color: var(--avatar_bg, var(--bds-color_blue));
-    color: var(--avatar_text, var(--bds-color_on-blue));
+    background-color: var(--avatar_bg, var(--avatar_bg--variant));
+    color: var(--avatar_text, var(--avatar_text--variant));
     font-weight: var(--bds-font_weight--semibold);
   }
 
+  /* Tone slots: the outer --avatar_bg / --avatar_text still win, and each
+     tone has its own public hook (--avatar_bg--primary etc.). */
+  .avatar.--tone_primary {
+    --avatar_bg--variant: var(--avatar_bg--primary, var(--bds-color_primary--subtle, var(--bds-color_blue--subtle)));
+    --avatar_text--variant: var(--avatar_text--primary, var(--bds-color_on-primary--subtle, var(--bds-color_on-blue--subtle)));
+  }
+
+  .avatar.--tone_secondary {
+    --avatar_bg--variant: var(--avatar_bg--secondary, var(--bds-color_secondary--subtle, var(--bds-color_blue--subtle)));
+    --avatar_text--variant: var(--avatar_text--secondary, var(--bds-color_on-secondary--subtle, var(--bds-color_on-blue--subtle)));
+  }
+
+  .avatar.--tone_accent-1 {
+    --avatar_bg--variant: var(--avatar_bg--accent-1, var(--bds-color_accent-1--subtle, var(--bds-color_green--subtle)));
+    --avatar_text--variant: var(--avatar_text--accent-1, var(--bds-color_on-accent-1--subtle, var(--bds-color_on-green--subtle)));
+  }
+
+  .avatar.--tone_accent-2 {
+    --avatar_bg--variant: var(--avatar_bg--accent-2, var(--bds-color_accent-2--subtle, var(--bds-color_orange--subtle)));
+    --avatar_text--variant: var(--avatar_text--accent-2, var(--bds-color_on-accent-2--subtle, var(--bds-color_on-orange--subtle)));
+  }
+
+  .avatar.--tone_accent-3 {
+    --avatar_bg--variant: var(--avatar_bg--accent-3, var(--bds-color_accent-3--subtle, var(--bds-color_blue--subtle)));
+    --avatar_text--variant: var(--avatar_text--accent-3, var(--bds-color_on-accent-3--subtle, var(--bds-color_on-blue--subtle)));
+  }
+
   .avatar.--size_small  { --avatar_size--variant: 2em; }
   .avatar.--size_medium { --avatar_size--variant: 3em; }
   .avatar.--size_large  { --avatar_size--variant: 4.5em; }

package/src/components/ui/Avatar/Avatar.spec.tsx

@@ -1,5 +1,6 @@
 import { render, screen } from '@testing-library/react';
 import { Avatar } from './Avatar';
+import { toneFromName } from './avatarTone';
 
 describe('Avatar', () => {
   it('renders an image when src is provided', () => {
@@ -46,4 +47,29 @@ describe('Avatar', () => {
     render(<Avatar name="Jane Doe" className="custom" />);
     expect(screen.getByRole('img')).toHaveClass('custom');
   });
+
+  it('applies the tone class derived from the name by default', () => {
+    render(<Avatar name="Jane Doe" />);
+    expect(screen.getByRole('img').className).toContain(`--tone_${toneFromName('Jane Doe')}`);
+  });
+
+  it('applies primary when there is no name and no tone', () => {
+    render(<Avatar />);
+    expect(screen.getByRole('img').className).toContain('--tone_primary');
+  });
+
+  it('lets an explicit tone win over auto', () => {
+    render(<Avatar name="Jane Doe" tone="accent-3" />);
+    expect(screen.getByRole('img').className).toContain('--tone_accent-3');
+  });
+
+  it('applies the same tone class for tone="auto" as for no tone', () => {
+    render(<Avatar name="Jane Doe" tone="auto" />);
+    expect(screen.getByRole('img').className).toContain(`--tone_${toneFromName('Jane Doe')}`);
+  });
+
+  it('does not apply a tone class to image avatars', () => {
+    const { container } = render(<Avatar src="https://example.com/photo.jpg" name="Jane Doe" tone="accent-1" />);
+    expect(container.firstElementChild?.className).not.toContain('--tone_');
+  });
 });

package/src/components/ui/Avatar/Avatar.stories.tsx

@@ -6,6 +6,7 @@ const meta = {
   component: Avatar,
   argTypes: {
     size: { control: 'radio', options: ['small', 'medium', 'large'] },
+    tone: { control: 'select', options: ['auto', 'primary', 'secondary', 'accent-1', 'accent-2', 'accent-3'] },
   },
 } satisfies Meta<typeof Avatar>;
 
@@ -41,3 +42,25 @@ export const AllSizes: Story = {
     </div>
   ),
 };
+
+export const AllTones: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+      <Avatar name="Primary" tone="primary" />
+      <Avatar name="Secondary" tone="secondary" />
+      <Avatar name="Accent One" tone="accent-1" />
+      <Avatar name="Accent Two" tone="accent-2" />
+      <Avatar name="Accent Three" tone="accent-3" />
+    </div>
+  ),
+};
+
+export const AutoTone: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+      {['Jane Doe', 'Bjorn Boonen', 'Sam Visser', 'Noor de Vries', 'Lars Bakker'].map(name => (
+        <Avatar key={name} name={name} />
+      ))}
+    </div>
+  ),
+};

package/src/components/ui/Avatar/Avatar.tsx

@@ -2,12 +2,14 @@ import { HTMLAttributes } from 'react';
 import css from './Avatar.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 import type { WithClassName } from '../../../types';
+import { resolveAvatarTone, type AvatarTone } from './avatarTone';
 
 interface AvatarProps extends WithClassName, HTMLAttributes<HTMLSpanElement> {
   src?: string;
   alt?: string;
   name?: string;
   size?: 'small' | 'medium' | 'large';
+  tone?: AvatarTone;
 }
 
 function getInitials(name: string): string {
@@ -19,7 +21,7 @@ function getInitials(name: string): string {
     .join('');
 }
 
-export function Avatar({ src, alt, name, size = 'medium', className, ...rest }: Readonly<AvatarProps>) {
+export function Avatar({ src, alt, name, size = 'medium', tone = 'auto', className, ...rest }: Readonly<AvatarProps>) {
   const sizeClass = css[`--size_${size}`];
 
   if (src) {
@@ -37,7 +39,7 @@ export function Avatar({ src, alt, name, size = 'medium', className, ...rest }:
       {...rest}
       role="img"
       aria-label={name ?? 'User avatar'}
-      className={cn(css.avatar, css['--fallback'], sizeClass, className)}
+      className={cn(css.avatar, css['--fallback'], css[`--tone_${resolveAvatarTone(tone, name)}`], sizeClass, className)}
     >
       <span className={css.initials} aria-hidden="true">
         {initials}

package/src/components/ui/Avatar/avatarTone.spec.ts

@@ -0,0 +1,41 @@
+import { AVATAR_TONES, resolveAvatarTone, toneFromName } from './avatarTone';
+
+describe('avatarTone', () => {
+  it('returns the same tone for the same name', () => {
+    expect(toneFromName('Jane Doe')).toBe(toneFromName('Jane Doe'));
+  });
+
+  it('ignores case and surrounding whitespace', () => {
+    expect(toneFromName('  JANE doe ')).toBe(toneFromName('jane doe'));
+  });
+
+  it('returns primary when there is no name', () => {
+    expect(toneFromName()).toBe('primary');
+    expect(toneFromName('')).toBe('primary');
+    expect(toneFromName('   ')).toBe('primary');
+  });
+
+  it('only returns known tones', () => {
+    const names = ['Alice', 'Bob', 'Carol', 'Dave', 'Eve', 'Frank', 'Grace', 'Heidi'];
+    names.forEach(name => expect(AVATAR_TONES).toContain(toneFromName(name)));
+  });
+
+  it('spreads different names over more than one tone', () => {
+    const names = ['Alice', 'Bob', 'Carol', 'Dave', 'Eve', 'Frank', 'Grace', 'Heidi'];
+    expect(new Set(names.map(toneFromName)).size).toBeGreaterThan(1);
+  });
+
+  it('falls back to the name for an unknown tone', () => {
+    // @ts-expect-error simulates an invalid attribute value from HTML
+    expect(resolveAvatarTone('foo', 'Jane Doe')).toBe(toneFromName('Jane Doe'));
+  });
+
+  it('lets an explicit tone win over the name', () => {
+    expect(resolveAvatarTone('accent-2', 'Jane Doe')).toBe('accent-2');
+  });
+
+  it('derives the tone from the name for auto and undefined', () => {
+    expect(resolveAvatarTone('auto', 'Jane Doe')).toBe(toneFromName('Jane Doe'));
+    expect(resolveAvatarTone(undefined, 'Jane Doe')).toBe(toneFromName('Jane Doe'));
+  });
+});

package/src/components/ui/Avatar/avatarTone.ts

@@ -0,0 +1,22 @@
+export const AVATAR_TONES = ['primary', 'accent-1', 'accent-2', 'accent-3', 'secondary'] as const;
+
+export type AvatarToneName = (typeof AVATAR_TONES)[number];
+export type AvatarTone = 'auto' | AvatarToneName;
+
+/** Picks a stable tone from a name: the same name always gives the same tone. */
+export function toneFromName(name?: string): AvatarToneName {
+  const normalised = (name ?? '').trim().toLowerCase();
+  if (!normalised) return 'primary';
+
+  const hash = [...normalised].reduce(
+    (h, ch) => (Math.imul(h, 31) + (ch.codePointAt(0) ?? 0)) >>> 0,
+    0,
+  );
+  return AVATAR_TONES[hash % AVATAR_TONES.length];
+}
+
+/** An explicit tone wins; `auto` (or no tone) derives one from the name. */
+export function resolveAvatarTone(tone: AvatarTone | undefined, name?: string): AvatarToneName {
+  const isKnownTone = (value: string): value is AvatarToneName => AVATAR_TONES.some(known => known === value);
+  return tone && isKnownTone(tone) ? tone : toneFromName(name);
+}

package/src/components/ui/Badge/Badge.mdx

@@ -75,7 +75,7 @@ The override surface is **layered**. Setting a public token on the badge (or any
 </tbody>
 </table>
 
-Defaults resolve to foundation tokens per variant: `success`/`error`/`warning` map directly to `--bds-color_{variant}` / `--bds-color_on-{variant}`. `primary` maps to `--bds-color_interactive` / `--bds-color_on-interactive`, and `secondary` maps to `--bds-color_bg` / `--bds-color_on-bg` — neither follows the generic `{variant}` naming.
+Defaults resolve to foundation tokens per variant: `success`/`error`/`warning` map directly to `--bds-color_{variant}` / `--bds-color_on-{variant}`. `primary` maps to `--bds-color_interactive` / `--bds-color_on-interactive`, and `secondary` maps to the neutral `--bds-color_grey` / `--bds-color_on-grey`, so it has a solid surface like the other variants. Neither follows the generic `{variant}` naming.
 
 
 ## Accessibility

package/src/components/ui/Badge/Badge.module.css

@@ -22,8 +22,8 @@
   }
 
   .--variant_secondary {
-    --badge_bg--variant:   var(--badge_bg--secondary, var(--bds-color_bg));
-    --badge_text--variant: var(--badge_text--secondary, var(--bds-color_on-bg));
+    --badge_bg--variant:   var(--badge_bg--secondary, var(--bds-color_grey));
+    --badge_text--variant: var(--badge_text--secondary, var(--bds-color_on-grey));
   }
 
   .--variant_success {

package/src/components/ui/Badge/Badge.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import { Badge } from './Badge';
 
@@ -16,4 +18,10 @@ describe('Badge', () => {
     render(<Badge className="custom">Test</Badge>);
     expect(screen.getByText('Test')).toHaveClass('custom');
   });
+
+  it('gives the secondary variant a solid neutral surface through its own hooks', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/ui/Badge/Badge.module.css'), 'utf8');
+    expect(css).toMatch(/\.--variant_secondary \{[^}]*--badge_bg--variant:\s*var\(--badge_bg--secondary,\s*var\(--bds-color_grey\)\)/);
+    expect(css).toMatch(/\.--variant_secondary \{[^}]*--badge_text--variant:\s*var\(--badge_text--secondary,\s*var\(--bds-color_on-grey\)\)/);
+  });
 });

package/src/components/ui/Collapsible/Collapsible.module.css

@@ -2,11 +2,10 @@
   .collapsible {
     border: var(--collapsible_border, none);
     --bdc_color: var(--collapsible_border-color, var(--bds-color_bg--subtle));
-    --bdc-outline_width: var(--collapsible_border-width, 1px);
     --bdc-outline_radius: var(--collapsible_border-radius, var(--bds-border_radius--m));
 
     border-radius: var(--bdc-outline_radius);
-    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
+    box-shadow: inset 0 0 0 var(--collapsible_border-width, var(--bdc-outline_width)) var(--bdc_color);
     overflow: hidden;
   }