@boostdev/design-system-components 2.14.1 → 2.16.0

package/src/components/interaction/DropdownMenu/DropdownMenu.tsx

@@ -2,6 +2,7 @@ import {
   HTMLAttributes,
   KeyboardEvent,
   ReactElement,
+  Fragment,
   cloneElement,
   isValidElement,
   useEffect,
@@ -20,8 +21,29 @@ export interface DropdownMenuItem {
   disabled?: boolean;
   icon?: ReactElement;
   separator?: boolean;
+  /** Renders the item in the error colour, for actions that delete or discard. */
+  destructive?: boolean;
+  /** Keyboard shortcut as display text. Decorative (`aria-hidden`); the consumer wires the actual key. */
+  shortcut?: string;
+  /** Consecutive items with the same group render inside a labelled `role="group"`. */
+  group?: string;
 }
 
+interface IndexedItem {
+  item: DropdownMenuItem;
+  index: number;
+}
+
+/** Splits items into runs of consecutive items sharing the same `group`. */
+const toSegments = (items: DropdownMenuItem[]): IndexedItem[][] =>
+  items.reduce<IndexedItem[][]>((segments, item, index) => {
+    const last = segments[segments.length - 1];
+    const startsNewSegment = !last || item.group === undefined || last[0].item.group !== item.group;
+    return startsNewSegment
+      ? [...segments, [{ item, index }]]
+      : [...segments.slice(0, -1), [...last, { item, index }]];
+  }, []);
+
 export interface DropdownMenuProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
   trigger: ReactElement;
   items: DropdownMenuItem[];
@@ -125,23 +147,53 @@ export function DropdownMenu({
           role="menu"
           className={cn(css.menu, css[`--placement_${placement}`])}
         >
-          {items.map((item, index) => (
-            <li key={item.id} role="presentation">
-              {item.separator && <hr className={css.separator} role="separator" />}
-              <button
-                ref={el => { itemRefs.current[index] = el; }}
-                type="button"
-                role="menuitem"
-                disabled={item.disabled}
-                className={css.item}
-                onClick={() => { item.onClick?.(); close(true); }}
-                onKeyDown={e => handleItemKeyDown(e, index)}
-              >
-                {item.icon && <span className={css.icon} aria-hidden="true">{item.icon}</span>}
-                {item.label}
-              </button>
-            </li>
-          ))}
+          {toSegments(items).map(segment => {
+            const { item: first } = segment[0];
+            const groupLabel = first.group;
+            const renderSeparator = () => (
+              <li role="presentation" className={css.separatorRow}>
+                <hr className={css.separator} role="separator" />
+              </li>
+            );
+            /* The first item's separator sits before the group, so the group holds only its label and items. */
+            const leadingSeparator = groupLabel !== undefined && first.separator;
+            const rows = segment.map(({ item, index }, position) => (
+              <Fragment key={item.id}>
+                {item.separator && !(leadingSeparator && position === 0) && renderSeparator()}
+                <li role="presentation">
+                  <button
+                    ref={el => { itemRefs.current[index] = el; }}
+                    type="button"
+                    role="menuitem"
+                    disabled={item.disabled}
+                    className={cn(css.item, item.destructive && css['--destructive'])}
+                    onClick={() => { item.onClick?.(); close(true); }}
+                    onKeyDown={e => handleItemKeyDown(e, index)}
+                  >
+                    {item.icon && <span className={css.icon} aria-hidden="true">{item.icon}</span>}
+                    <span className={css.label}>{item.label}</span>
+                    {item.shortcut && <span className={css.shortcut} aria-hidden="true">{item.shortcut}</span>}
+                  </button>
+                </li>
+              </Fragment>
+            ));
+
+            return groupLabel === undefined ? (
+              rows
+            ) : (
+              <Fragment key={`group-${first.id}`}>
+                {leadingSeparator && renderSeparator()}
+                <li role="presentation">
+                <ul role="group" aria-labelledby={`${menuId}-group-${first.id}`} className={css.group}>
+                  <li role="presentation" id={`${menuId}-group-${first.id}`} className={css.groupLabel}>
+                    {groupLabel}
+                  </li>
+                  {rows}
+                </ul>
+                </li>
+              </Fragment>
+            );
+          })}
         </ul>
       )}
     </div>

package/src/components/interaction/form/Checkbox/Checkbox.module.css

@@ -65,5 +65,6 @@
 
   .checkboxError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 }

package/src/components/interaction/form/Checkbox/Checkbox.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Checkbox } from './Checkbox';
@@ -42,4 +44,9 @@ describe('Checkbox', () => {
     const checkbox = screen.getByLabelText('Accept terms');
     expect(checkbox.id).not.toBe('consumer-supplied-id');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Checkbox/Checkbox.module.css'), 'utf8');
+    expect(css).toMatch(/\.checkboxError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.mdx

@@ -57,3 +57,4 @@ All public override tokens. Set on the CheckboxGroup or any ancestor; they casca
 - `disabled` on the group sets the HTML `disabled` attribute on the `<fieldset>`, which disables all child inputs
 - When `required` is true, the legend shows a visible `*` (hidden from assistive tech via `aria-hidden`) plus a visually-hidden "(required)" span, so the fieldset's accessible name resolves to `"<legend> (required)"` (e.g. `"Contact preferences (required)"`). `aria-required` is intentionally **not** set on the `<fieldset>` — it is not supported ARIA on a `role=group` element and would be ignored by assistive tech
 - Error and hint messages are linked via `aria-describedby`
+- With `error`, the child controls show the error ring (`--bdc-outline_width--error`, `--bdc_color--error`) and the message gets a warning icon. Message hooks (`--formMessage_*`) are listed on FormInput

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.module.css

@@ -42,4 +42,11 @@
     flex-direction: column;
     gap: var(--checkboxGroup_items-gap, var(--bds-space_xs));
   }
+
+  /* Error ring on the controls inside; state rules on the control itself
+     (checked, focus) still win because they have higher specificity. */
+  .groupError input {
+    --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
+  }
 }

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import { Checkbox } from '../Checkbox';
 import { CheckboxGroup } from './CheckboxGroup';
@@ -114,4 +116,24 @@ describe('CheckboxGroup', () => {
     );
     expect(screen.getByRole('group')).toBeDisabled();
   });
+
+  it('marks the group with the error class so the controls inside show the error ring', () => {
+    render(
+      <CheckboxGroup legend="Pick" error="Required">
+        <Checkbox label="One" name="one" value="1" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByRole('group', { name: 'Pick' }).className).toContain('groupError');
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/CheckboxGroup/CheckboxGroup.module.css'), 'utf8');
+    expect(css).toMatch(/\.groupError input \{[^}]*--bdc_color: var\(--bdc_color--error\)[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
+
+  it('does not mark the group without an error', () => {
+    render(
+      <CheckboxGroup legend="Pick">
+        <Checkbox label="One" name="one" value="1" />
+      </CheckboxGroup>
+    );
+    expect(screen.getByRole('group', { name: 'Pick' }).className).not.toContain('groupError');
+  });
 });

package/src/components/interaction/form/CheckboxGroup/CheckboxGroup.tsx

@@ -28,7 +28,7 @@ export function CheckboxGroup({
   return (
     <fieldset
       {...rest}
-      className={cn(css.group, className)}
+      className={cn(css.group, error && css.groupError, className)}
       aria-describedby={describedBy}
     >
       <legend className={css.legend}>

package/src/components/interaction/form/Combobox/Combobox.module.css

@@ -45,6 +45,7 @@
 
   .inputError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 
   .chevron {

package/src/components/interaction/form/Combobox/Combobox.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Combobox } from './Combobox';
@@ -125,4 +127,9 @@ describe('Combobox', () => {
     expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
     expect(combobox).not.toHaveAttribute('aria-activedescendant');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Combobox/Combobox.module.css'), 'utf8');
+    expect(css).toMatch(/\.inputError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/FormInput/FormInput.mdx

@@ -43,9 +43,18 @@ Text input field with label, optional hint, and error state. The label and input
 <tr><td>`--formInput_border`</td><td>`none`</td><td>Border</td></tr>
 <tr><td>`--formInput_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Corner radius</td></tr>
 <tr><td>`--formInput_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Box shadow</td></tr>
+<tr><td>`--formMessage_font-size`</td><td>`var(--bds-font_size--body--s)`</td><td>Font size of the error and hint message (shared by all form controls)</td></tr>
+<tr><td>`--formMessage_gap`</td><td>`var(--bds-space_xxs)`</td><td>Gap between the error icon and the error text</td></tr>
+<tr><td>`--formMessage_icon-size`</td><td>`1.15em`</td><td>Size of the error icon</td></tr>
+<tr><td>`--formMessage_color--error`</td><td>`var(--bds-color_error_on-bg)`</td><td>Error message colour</td></tr>
+<tr><td>`--formMessage_font-weight--error`</td><td>`var(--bds-font_weight--semibold)`</td><td>Error message weight</td></tr>
+<tr><td>`--formMessage_color--hint`</td><td>`inherit`</td><td>Hint colour</td></tr>
+<tr><td>`--formMessage_font-style--hint`</td><td>`italic`</td><td>Hint font style</td></tr>
 </tbody>
 </table>
 
+In the error state the control draws a `--bdc-outline_width--error` (2px) ring in `--bdc_color--error`, and the message gets a warning icon.
+
 `--input_*` (e.g. `--input_border`, `--input_radius`, `--input_shadow`, `--input_color`, `--input_color_bg`) are deprecated aliases for the `--formInput_*` tokens above — they still work but `--formInput_*` is the documented, forward-compatible name.
 
 

package/src/components/interaction/form/FormInput/FormInput.module.css

@@ -42,5 +42,6 @@
 
   .inputError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 }

package/src/components/interaction/form/FormInput/FormInput.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { FormInput } from './FormInput';
@@ -60,4 +62,9 @@ describe('FormInput', () => {
     render(<FormInput label="Email" name="email" ariaLabel="Deprecated label" aria-label="Native label" />);
     expect(screen.getByRole('textbox')).toHaveAccessibleName('Deprecated label');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/FormInput/FormInput.module.css'), 'utf8');
+    expect(css).toMatch(/\.inputError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/NumberInput/NumberInput.module.css

@@ -49,6 +49,7 @@
 
   .inputError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 
   .stepper {

package/src/components/interaction/form/NumberInput/NumberInput.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { useState } from 'react';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -97,4 +99,9 @@ describe('NumberInput', () => {
     expect(input).toHaveValue(null);
     expect(onChange).not.toHaveBeenCalledWith(0);
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/NumberInput/NumberInput.module.css'), 'utf8');
+    expect(css).toMatch(/\.inputError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/Radio/Radio.module.css

@@ -78,5 +78,6 @@
 
   .radioError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 }

package/src/components/interaction/form/Radio/Radio.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Radio } from './Radio';
@@ -50,4 +52,9 @@ describe('Radio', () => {
     const radio = screen.getByLabelText('Option');
     expect(radio).toHaveAttribute('id', 'custom-radio-id');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Radio/Radio.module.css'), 'utf8');
+    expect(css).toMatch(/\.radioError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/RadioGroup/RadioGroup.mdx

@@ -57,4 +57,5 @@ All public override tokens. Set on the RadioGroup or any ancestor; they cascade.
 - `disabled` on the group sets the HTML `disabled` attribute on the `<fieldset>`, which disables all child inputs
 - When `required` is true, the legend shows a visible `*` (hidden from assistive tech via `aria-hidden`) plus a visually-hidden "(required)" span, so the fieldset's accessible name resolves to `"<legend> (required)"` (e.g. `"Preferred contact (required)"`). `aria-required` is intentionally **not** set on the `<fieldset>` — it is not supported ARIA on a `role=group` element and would be ignored by assistive tech
 - Error and hint messages are linked via `aria-describedby`
+- With `error`, the child controls show the error ring (`--bdc-outline_width--error`, `--bdc_color--error`) and the message gets a warning icon. Message hooks (`--formMessage_*`) are listed on FormInput
 - Arrow keys move between options within the group; `Tab` moves focus out of the group

package/src/components/interaction/form/RadioGroup/RadioGroup.module.css

@@ -42,4 +42,11 @@
     flex-direction: column;
     gap: var(--radioGroup_items-gap, var(--bds-space_xs));
   }
+
+  /* Error ring on the controls inside; state rules on the control itself
+     (checked, focus) still win because they have higher specificity. */
+  .groupError input {
+    --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
+  }
 }

package/src/components/interaction/form/RadioGroup/RadioGroup.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import { Radio } from '../Radio';
 import { RadioGroup } from './RadioGroup';
@@ -102,4 +104,24 @@ describe('RadioGroup', () => {
     );
     expect(screen.getByRole('group')).toBeDisabled();
   });
+
+  it('marks the group with the error class so the controls inside show the error ring', () => {
+    render(
+      <RadioGroup legend="Pick" error="Required">
+        <Radio label="One" name="one" value="1" />
+      </RadioGroup>
+    );
+    expect(screen.getByRole('group', { name: 'Pick' }).className).toContain('groupError');
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/RadioGroup/RadioGroup.module.css'), 'utf8');
+    expect(css).toMatch(/\.groupError input \{[^}]*--bdc_color: var\(--bdc_color--error\)[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
+
+  it('does not mark the group without an error', () => {
+    render(
+      <RadioGroup legend="Pick">
+        <Radio label="One" name="one" value="1" />
+      </RadioGroup>
+    );
+    expect(screen.getByRole('group', { name: 'Pick' }).className).not.toContain('groupError');
+  });
 });

package/src/components/interaction/form/RadioGroup/RadioGroup.tsx

@@ -28,7 +28,7 @@ export function RadioGroup({
   return (
     <fieldset
       {...rest}
-      className={cn(css.group, className)}
+      className={cn(css.group, error && css.groupError, className)}
       aria-describedby={describedBy}
     >
       <legend className={css.legend}>

package/src/components/interaction/form/Select/Select.module.css

@@ -46,6 +46,7 @@
 
   .selectError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 
   .chevron {

package/src/components/interaction/form/Select/Select.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Select } from './Select';
@@ -93,4 +95,9 @@ describe('Select', () => {
     expect(select).toHaveAttribute('aria-describedby', 'custom-iderror');
     expect(screen.getByText('Required')).toHaveAttribute('id', 'custom-iderror');
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Select/Select.module.css'), 'utf8');
+    expect(css).toMatch(/\.selectError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/Switch/Switch.module.css

@@ -74,6 +74,7 @@
   /* Error state — declared before checked/focus so higher-specificity states can override */
   .switch.switchError + .track {
     --bdc_color: var(--switch_border-color--error, var(--bds-color_error));
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 
   /* Checked state via CSS sibling combinator */

package/src/components/interaction/form/Switch/Switch.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Switch } from './Switch';
@@ -88,4 +90,9 @@ describe('Switch', () => {
     render(<Switch label="Toggle" name="toggle" role="checkbox" />);
     expect(screen.getByRole('switch')).toBeInTheDocument();
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Switch/Switch.module.css'), 'utf8');
+    expect(css).toMatch(/\.switchError \+ \.track \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/Textarea/Textarea.module.css

@@ -40,5 +40,6 @@
 
   .textareaError {
     --bdc_color: var(--bdc_color--error);
+    --bdc-outline_width: var(--bdc-outline_width--error, 2px);
   }
 }

package/src/components/interaction/form/Textarea/Textarea.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { Textarea } from './Textarea';
@@ -63,4 +65,9 @@ describe('Textarea', () => {
       ?.split(' ')
       .forEach((describedById) => expect(describedById.startsWith('custom-id')).toBe(true));
   });
+
+  it('widens the outline in the error state', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/Textarea/Textarea.module.css'), 'utf8');
+    expect(css).toMatch(/\.textareaError \{[^}]*--bdc-outline_width: var\(--bdc-outline_width--error, 2px\)/);
+  });
 });

package/src/components/interaction/form/atoms/Message.module.css

@@ -1,15 +1,26 @@
 @layer boostdev.component {
   .error,
   .hint {
-    font-size: var(--bds-font_size--body--s);
+    font-size: var(--formMessage_font-size, var(--bds-font_size--body--s));
     margin-inline-start: var(--labelPosition, 0);
   }
 
   .error {
-    color: var(--bds-color_error_on-bg);
+    display: flex;
+    align-items: flex-start;
+    gap: var(--formMessage_gap, var(--bds-space_xxs));
+    color: var(--formMessage_color--error, var(--bds-color_error_on-bg));
+    font-weight: var(--formMessage_font-weight--error, var(--bds-font_weight--semibold));
   }
 
   .hint {
-    font-style: italic;
+    color: var(--formMessage_color--hint, inherit);
+    font-style: var(--formMessage_font-style--hint, italic);
+  }
+
+  .icon {
+    inline-size: var(--formMessage_icon-size, 1.15em);
+    block-size: var(--formMessage_icon-size, 1.15em);
+    flex-shrink: 0;
   }
 }

package/src/components/interaction/form/atoms/Message.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import { Message } from './Message';
 
@@ -26,4 +28,24 @@ describe('Message', () => {
     render(<Message inputId="field-1" type="error" message="Required" />);
     expect(screen.getByRole('alert')).toHaveAttribute('id', 'field-1error');
   });
+
+  it('renders an aria-hidden icon before the error text', () => {
+    render(<Message inputId="field-1" type="error" message="Required" />);
+    const icon = screen.getByRole('alert').querySelector('svg');
+    expect(icon).toHaveAttribute('aria-hidden', 'true');
+    expect(screen.getByRole('alert')).toHaveTextContent('Required');
+  });
+
+  it('renders no icon for a hint', () => {
+    render(<Message inputId="field-1" type="hint" message="Hint" />);
+    expect(screen.getByText('Hint').querySelector('svg')).toBeNull();
+  });
+
+  it('exposes the message hooks in the stylesheet', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/atoms/Message.module.css'), 'utf8');
+    ['--formMessage_gap', '--formMessage_icon-size', '--formMessage_color--error', '--formMessage_font-weight--error',
+      '--formMessage_color--hint', '--formMessage_font-style--hint', '--formMessage_font-size'].forEach((hook) => {
+      expect(css).toContain(hook);
+    });
+  });
 });

package/src/components/interaction/form/atoms/Message.tsx

@@ -13,6 +13,11 @@ export const Message = ({ message, type, inputId, className }: MessageProps) =>
 
   return (
     <p id={inputId + type} role={type === 'error' ? 'alert' : undefined} className={cn(css[type], className)}>
+      {type === 'error' && (
+        <svg className={css.icon} aria-hidden="true" viewBox="0 0 256 256" fill="currentColor">
+          <path d="M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm-8,56a8,8,0,0,1,16,0v56a8,8,0,0,1-16,0Zm8,104a12,12,0,1,1,12-12A12,12,0,0,1,128,184Z" />
+        </svg>
+      )}
       {message}
     </p>
   );

package/src/components/layout/SectionHeader/SectionHeader.mdx

@@ -31,6 +31,17 @@ Heading block with optional subtitle for introducing a content section.
 ### Centered
 <Canvas of={Stories.Centered} />
 
+### Gradient
+Set `appearance="gradient"` for a gradient-filled title. The gradient spans the text, not the row. Where `background-clip: text` is unsupported the title keeps its normal colour; in forced-colors mode it uses `CanvasText`.
+
+<Canvas of={Stories.Gradient} />
+
+<Canvas of={Stories.GradientExtraSmall} />
+
+<Canvas of={Stories.GradientSmall} />
+
+<Canvas of={Stories.GradientLarge} />
+
 ## Props
 
 <ArgTypes of={Stories} />
@@ -43,12 +54,14 @@ Heading block with optional subtitle for introducing a content section.
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--sectionHeader_title-color`</td><td>`var(--bds-color_on-bg)`</td><td>Title text colour</td></tr>
-<tr><td>`--sectionHeader_title-size`</td><td>varies by `size` prop</td><td>Title font-size (overrides the variant default)</td></tr>
+<tr><td>`--sectionHeader_title-color`</td><td>`var(--bds-color_on-bg)`</td><td>Title text colour; no effect with `appearance="gradient"`, where the colour comes from `--sectionHeader_title-gradient`</td></tr>
+<tr><td>`--sectionHeader_title-font-family`</td><td>`var(--bds-font_family--heading)`</td><td>Title font family</td></tr>
+<tr><td>`--sectionHeader_title-gradient`</td><td>`linear-gradient(90deg, var(--bds-color_primary--strong), var(--bds-color_accent-3--strong))`</td><td>Title gradient, only with `appearance="gradient"`</td></tr>
+<tr><td>`--sectionHeader_title-size`</td><td>`xs` body, `small` heading-3, `medium` heading-2, `large` heading-1</td><td>Title font-size (overrides the variant default)</td></tr>
 <tr><td>`--sectionHeader_title-line-height`</td><td>varies by `size` prop</td><td>Title line-height</td></tr>
-<tr><td>`--sectionHeader_title-weight`</td><td>`var(--bds-font_weight--bold)`</td><td>Title font-weight</td></tr>
-<tr><td>`--sectionHeader_subtitle-color`</td><td>`var(--bds-color_grey--strong)`</td><td>Subtitle text colour</td></tr>
-<tr><td>`--sectionHeader_subtitle-size`</td><td>varies by `size` prop</td><td>Subtitle font-size</td></tr>
+<tr><td>`--sectionHeader_title-weight`</td><td>`var(--bds-font_weight--heading)`</td><td>Title font-weight</td></tr>
+<tr><td>`--sectionHeader_subtitle-color`</td><td>`var(--bds-color_on-bg--muted)`</td><td>Subtitle text colour</td></tr>
+<tr><td>`--sectionHeader_subtitle-size`</td><td>`xs` body--s, `small`/`medium` body, `large` heading-3</td><td>Subtitle font-size</td></tr>
 <tr><td>`--sectionHeader_subtitle-line-height`</td><td>`1.4` (`xs`/`small`), `1.3` (`medium`/`large`)</td><td>Subtitle line-height</td></tr>
 <tr><td>`--sectionHeader_gap`</td><td>`var(--bds-space_m)`</td><td>Gap between title and subtitle</td></tr>
 </tbody>