@boostdev/design-system-components 2.15.0 → 2.16.0

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>

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;
+    }
+  }
 }

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>

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
@@ -42,6 +45,32 @@
         --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,25 @@ 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}`);
+    });
+  });
 });

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>
+  ),
+};