@boostdev/design-system-components 2.15.0 → 2.17.0

package/src/components/interaction/Rating/Rating.spec.tsx

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import { Rating } from './Rating';
 
@@ -27,4 +29,11 @@ describe('Rating', () => {
     render(<Rating value={3} className="custom" />);
     expect(screen.getByRole('img')).toHaveClass('custom');
   });
+
+  it('outlines empty stars with the as-surface mark colour and strokes filled stars in their own colour', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/Rating/Rating.module.css'), 'utf8');
+    expect(css).toMatch(/\.star \{[^}]*stroke:\s*var\(--rating_stroke-color,\s*var\(--bds-color_on-bg--as-surface,\s*var\(--bds-color_on-bg--border,\s*var\(--bds-color_on-bg\)\)\)\)/);
+    expect(css).toMatch(/\.star \{[^}]*stroke-width:\s*var\(--rating_stroke-width,\s*var\(--bdc-outline_width\)\)/);
+    expect(css).toMatch(/\.--filled \{[^}]*stroke:\s*var\(--rating_stroke-color--filled,\s*currentcolor\)/);
+  });
 });

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

@@ -46,7 +46,7 @@ All public override tokens. Set on the CheckboxGroup or any ancestor; they casca
 | `--checkboxGroup_items-gap` | `var(--bds-space_xs)` | Gap between the child checkboxes. |
 | `--checkboxGroup_legend-color` | `var(--bds-color_on-bg)` | Legend text colour. |
 | `--checkboxGroup_legend-font-family` | `var(--bds-font_family--body)` | Legend font family. |
-| `--checkboxGroup_legend-font-size` | `var(--bds-font_size--body--s)` | Legend font size. |
+| `--checkboxGroup_legend-font-size` | `var(--bds-font_size--body)` | Legend font size, the same as the labels of the other fields. |
 | `--checkboxGroup_legend-font-weight` | `var(--bds-font_weight--medium)` | Legend font weight. |
 | `--checkboxGroup_legend-gap` | `var(--bds-space_xs)` | Space below the legend before the items. |
 | `--checkboxGroup_required-color` | `var(--bds-color_error)` | Colour of the visible `*` required marker. |
@@ -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

@@ -10,7 +10,7 @@
 
   .legend {
     font-family: var(--checkboxGroup_legend-font-family, var(--bds-font_family--body));
-    font-size: var(--checkboxGroup_legend-font-size, var(--bds-font_size--body--s));
+    font-size: var(--checkboxGroup_legend-font-size, var(--bds-font_size--body));
     font-weight: var(--checkboxGroup_legend-font-weight, var(--bds-font_weight--medium));
     color: var(--checkboxGroup_legend-color, var(--bds-color_on-bg));
     padding: 0;
@@ -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,29 @@ 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');
+  });
+
+  it('sizes the legend like the labels of the other fields', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/CheckboxGroup/CheckboxGroup.module.css'), 'utf8');
+    expect(css).toMatch(/\.legend \{[^}]*font-size:\s*var\(--checkboxGroup_legend-font-size,\s*var\(--bds-font_size--body\)\)/);
+  });
 });

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

@@ -46,7 +46,7 @@ All public override tokens. Set on the RadioGroup or any ancestor; they cascade.
 | `--radioGroup_items-gap` | `var(--bds-space_xs)` | Gap between the child radios. |
 | `--radioGroup_legend-color` | `var(--bds-color_on-bg)` | Legend text colour. |
 | `--radioGroup_legend-font-family` | `var(--bds-font_family--body)` | Legend font family. |
-| `--radioGroup_legend-font-size` | `var(--bds-font_size--body--s)` | Legend font size. |
+| `--radioGroup_legend-font-size` | `var(--bds-font_size--body)` | Legend font size, the same as the labels of the other fields. |
 | `--radioGroup_legend-font-weight` | `var(--bds-font_weight--medium)` | Legend font weight. |
 | `--radioGroup_legend-gap` | `var(--bds-space_xs)` | Space below the legend before the items. |
 | `--radioGroup_required-color` | `var(--bds-color_error)` | Colour of the visible `*` required marker. |
@@ -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

@@ -10,7 +10,7 @@
 
   .legend {
     font-family: var(--radioGroup_legend-font-family, var(--bds-font_family--body));
-    font-size: var(--radioGroup_legend-font-size, var(--bds-font_size--body--s));
+    font-size: var(--radioGroup_legend-font-size, var(--bds-font_size--body));
     font-weight: var(--radioGroup_legend-font-weight, var(--bds-font_weight--medium));
     color: var(--radioGroup_legend-color, var(--bds-color_on-bg));
     padding: 0;
@@ -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,29 @@ 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');
+  });
+
+  it('sizes the legend like the labels of the other fields', () => {
+    const css = readFileSync(resolve(process.cwd(), 'src/components/interaction/form/RadioGroup/RadioGroup.module.css'), 'utf8');
+    expect(css).toMatch(/\.legend \{[^}]*font-size:\s*var\(--radioGroup_legend-font-size,\s*var\(--bds-font_size--body\)\)/);
+  });
 });

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>

package/src/components/layout/SectionHeader/SectionHeader.module.css

@@ -10,11 +10,11 @@
     /* --sectionHeader-title-color (kebab delimiter) is deprecated — use --sectionHeader_title-color */
     color: var(--sectionHeader_title-color, var(--sectionHeader-title-color, var(--bds-color_on-bg)));
     margin: 0;
-    font-family: var(--bds-font_family--body);
+    font-family: var(--sectionHeader_title-font-family, var(--bds-font_family--heading));
   }
 
   .subtitle {
-    color: var(--sectionHeader_subtitle-color, var(--bds-color_grey--strong));
+    color: var(--sectionHeader_subtitle-color, var(--bds-color_on-bg--muted, var(--bds-color_grey--strong)));
     margin: 0;
     font-family: var(--bds-font_family--body);
     font-weight: var(--bds-font_weight--medium);
@@ -37,31 +37,31 @@
 
   /* medium first — default size, so MCP extraction picks up its fallbacks */
   .sectionHeader.--medium .title {
-    font-size: var(--sectionHeader_title-size, var(--bds-font_size--heading-1));
+    font-size: var(--sectionHeader_title-size, var(--bds-font_size--heading-2));
     line-height: var(--sectionHeader_title-line-height, var(--bds-font_line-height--heading));
-    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--bold));
+    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--heading, var(--bds-font_weight--bold)));
   }
 
   .sectionHeader.--medium .subtitle {
-    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--heading-3));
+    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--body));
     line-height: var(--sectionHeader_subtitle-line-height, 1.3);
   }
 
   .sectionHeader.--xs .title {
-    font-size: var(--sectionHeader_title-size, var(--bds-font_size--heading-2));
+    font-size: var(--sectionHeader_title-size, var(--bds-font_size--body));
     line-height: var(--sectionHeader_title-line-height, var(--bds-font_line-height--heading));
-    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--bold));
+    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--heading, var(--bds-font_weight--bold)));
   }
 
   .sectionHeader.--xs .subtitle {
-    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--body));
+    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--body--s));
     line-height: var(--sectionHeader_subtitle-line-height, 1.4);
   }
 
   .sectionHeader.--small .title {
-    font-size: var(--sectionHeader_title-size, var(--bds-font_size--heading-1));
+    font-size: var(--sectionHeader_title-size, var(--bds-font_size--heading-3));
     line-height: var(--sectionHeader_title-line-height, var(--bds-font_line-height--heading));
-    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--bold));
+    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--heading, var(--bds-font_weight--bold)));
   }
 
   .sectionHeader.--small .subtitle {
@@ -70,15 +70,36 @@
   }
 
   .sectionHeader.--large .title {
-    font-size: var(--sectionHeader_title-size, var(--bds-font_size--display));
-    line-height: var(--sectionHeader_title-line-height, var(--bds-font_line-height--display));
-    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--bold));
+    font-size: var(--sectionHeader_title-size, var(--bds-font_size--heading-1));
+    line-height: var(--sectionHeader_title-line-height, var(--bds-font_line-height--heading));
+    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--heading, var(--bds-font_weight--bold)));
     letter-spacing: var(--bds-font_tracking--tight);
   }
 
   .sectionHeader.--large .subtitle {
-    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--heading-2));
+    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--heading-3));
     line-height: var(--sectionHeader_subtitle-line-height, 1.3);
     font-weight: var(--bds-font_weight--medium);
   }
+
+  /* Gradient only where background-clip: text is supported; elsewhere the title keeps its normal colour */
+  @supports (background-clip: text) {
+    .sectionHeader.--gradient .title {
+      inline-size: fit-content;
+      max-inline-size: 100%;
+      background-image: var(--sectionHeader_title-gradient, linear-gradient(90deg, var(--bds-color_primary--strong, var(--bds-color_blue--strong)), var(--bds-color_accent-3--strong, var(--bds-color_blue--strong))));
+      background-clip: text;
+      color: transparent;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .sectionHeader.--gradient .title {
+      background-image: none;
+
+      /* system colour keyword: forced-colors mode ignores tokens */
+      /* stylelint-disable-next-line scale-unlimited/declaration-strict-value */
+      color: CanvasText;
+    }
+  }
 }