@boostdev/design-system-components 1.2.5 → 1.2.6

package/src/components/interaction/Drawer/Drawer.mdx

@@ -38,6 +38,8 @@ Slide-in panel from the left or right edge of the viewport. Use for navigation,
 <tbody>
 <tr><td>`--drawer_color`</td><td>`var(--bds-color_bg)`</td><td>Panel background colour</td></tr>
 <tr><td>`--drawer_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Text colour</td></tr>
+<tr><td>`--drawer_close-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Close button border radius</td></tr>
+<tr><td>`--drawer_close-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Close button background on hover</td></tr>
 </tbody>
 </table>
 

package/src/components/interaction/Drawer/Drawer.module.css

@@ -95,7 +95,7 @@
 
   @media (hover: hover) and (pointer: fine) {
     .closeButton:hover {
-      background-color: var(--bds-color_bg--subtle);
+      background-color: var(--drawer_close-bg--hover, var(--bds-color_bg--subtle));
     }
   }
 

package/src/components/interaction/DropdownMenu/DropdownMenu.mdx

@@ -33,6 +33,25 @@ Floating menu with a list of selectable actions, triggered by a button. Supports
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--dropdown_border`</td><td>`none`</td><td>Menu container border</td></tr>
+<tr><td>`--dropdown_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Menu container corner radius</td></tr>
+<tr><td>`--dropdown_color`</td><td>`var(--bds-color_bg)`</td><td>Menu background colour</td></tr>
+<tr><td>`--dropdown_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Menu text colour</td></tr>
+<tr><td>`--dropdown_shadow`</td><td>`var(--bds-shadow_m)`</td><td>Menu box shadow</td></tr>
+<tr><td>`--dropdown_item-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Menu item background on hover</td></tr>
+<tr><td>`--dropdown_item-color--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Menu item text colour on hover</td></tr>
+</tbody>
+</table>
+
+
 ## Accessibility
 
 - Implements ARIA menu pattern: `role="menu"`, `role="menuitem"`

package/src/components/interaction/DropdownMenu/DropdownMenu.module.css

@@ -64,8 +64,8 @@
 
   @media (hover: hover) and (pointer: fine) {
     .item:not(:disabled):hover {
-      background-color: var(--bds-color_bg--subtle);
-      color: var(--bds-color_interactive_on-bg);
+      background-color: var(--dropdown_item-bg--hover, var(--bds-color_bg--subtle));
+      color: var(--dropdown_item-color--hover, var(--bds-color_interactive_on-bg));
     }
   }
 

package/src/components/interaction/Rating/Rating.mdx

@@ -32,6 +32,20 @@ Read-only star rating display. Use to show an existing score; for user input, co
 
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--rating_color`</td><td>`var(--bds-color_bg)`</td><td>Empty star colour</td></tr>
+<tr><td>`--rating_color--filled`</td><td>`var(--bds-color_warning)`</td><td>Filled star colour</td></tr>
+</tbody>
+</table>
+
+
 ## Accessibility
 
 - Renders as a `<span>` with `role="img"` and `aria-label="X out of Y stars"`

package/src/components/interaction/Rating/Rating.module.css

@@ -2,7 +2,7 @@
   .rating {
     display: inline-flex;
     gap: var(--bds-space_xxxs);
-    color: var(--bds-color_bg);
+    color: var(--rating_color, var(--bds-color_bg));
   }
 
   .star {
@@ -11,6 +11,6 @@
   }
 
   .--filled {
-    color: var(--bds-color_warning);
+    color: var(--rating_color--filled, var(--bds-color_warning));
   }
 }

package/src/components/interaction/Toast/Toast.mdx

@@ -17,20 +17,26 @@ Transient feedback notification that auto-dismisses after 5 seconds. Provided vi
 
 ## Setup
 
-Wrap your app (or layout root) once with `ToastProvider`:
+Wrap your app (or layout root) once with `ToastProvider`. Since Toast uses React hooks, it requires a client boundary in Next.js:
 
 ```tsx
-import { ToastProvider } from '@boostdev/components';
+// Next.js App Router — use the /client entry inside a 'use client' boundary:
+import { ToastProvider } from '@boostdev/design-system-components/client';
 
+// Non-Next.js / bundler apps:
+import { ToastProvider } from '@boostdev/design-system-components';
+```
+
+```tsx
 <ToastProvider>
   <App />
 </ToastProvider>
 ```
 
-Then call `showToast` anywhere inside:
+Then call `showToast` anywhere inside a client component:
 
 ```tsx
-import { useToast } from '@boostdev/components';
+import { useToast } from '@boostdev/design-system-components/client';
 
 const { showToast } = useToast();
 
@@ -39,6 +45,8 @@ showToast('Something went wrong', 'error');
 showToast('New message received', 'info');
 ```
 
+> **Next.js RSC note:** The root entry (`@boostdev/design-system-components`) is safe to import in Server Components for server-safe components like `Typography` or `Badge`. Toast itself is client-only and must be used inside a `'use client'` boundary.
+
 ## Examples
 
 ### Success

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

@@ -59,4 +59,15 @@ describe('Toast', () => {
     expect(() => render(<Bad />)).toThrow('useToast must be used within a ToastProvider');
     errorSpy.mockRestore();
   });
+
+  it('shares a single lazy-initialised context between provider and consumer (RSC-safe)', () => {
+    // The lazy getToastContext() pattern defers createContext() until first render
+    // so the module can be safely evaluated in Next.js Server Components.
+    // This test verifies provider and consumer share the same context instance.
+    let captured: ReturnType<typeof useToast> | undefined;
+    const Capture = () => { captured = useToast(); return null; };
+    render(<ToastProvider><Capture /></ToastProvider>);
+    expect(captured).toBeDefined();
+    expect(typeof captured!.showToast).toBe('function');
+  });
 });

package/src/components/interaction/Toast/Toast.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, createContext, useContext, ReactNode, useCallback, useMemo, useRef } from 'react';
+import { useState, useEffect, createContext, useContext, ReactNode, useCallback, useMemo, useRef, Context } from 'react';
 import css from './Toast.module.css';
 import { cn } from '@boostdev/design-system-foundation';
 
@@ -14,9 +14,16 @@ interface ToastContextType {
   showToast: (message: string, variant: ToastVariant) => void;
 }
 
-const ToastContext = createContext<ToastContextType | undefined>(undefined);
+// Lazy-initialised so the module can be evaluated in Next.js Server Components
+// without calling `createContext` at import time (which crashes RSC).
+let _ToastContext: Context<ToastContextType | undefined>;
+function getToastContext(): Context<ToastContextType | undefined> {
+  _ToastContext ??= createContext<ToastContextType | undefined>(undefined);
+  return _ToastContext;
+}
 
 export function ToastProvider({ children }: { children: ReactNode }) {
+  const ToastContext = getToastContext();
   const [toasts, setToasts] = useState<Toast[]>([]);
   const containerRef = useRef<HTMLDivElement>(null);
 
@@ -84,8 +91,8 @@ function ToastItem({ toast, onRemove }: { toast: Toast; onRemove: () => void })
   );
 }
 
-export function useToast() {
-  const context = useContext(ToastContext);
+export function useToast(): ToastContextType {
+  const context = useContext(getToastContext());
   if (!context) {
     throw new Error('useToast must be used within a ToastProvider');
   }

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

@@ -46,6 +46,8 @@ Searchable select with type-ahead filtering. Combines a text input with a dropdo
 <tr><td>`--combobox_listbox-border`</td><td>`none`</td><td>Dropdown list border</td></tr>
 <tr><td>`--combobox_listbox-radius`</td><td>`var(--bdc-outline_radius)`</td><td>Dropdown list corner radius</td></tr>
 <tr><td>`--combobox_listbox-shadow`</td><td>`var(--bds-shadow_m)`</td><td>Dropdown list box shadow</td></tr>
+<tr><td>`--combobox_option-bg--highlighted`</td><td>`var(--bds-color_bg--subtle)`</td><td>Highlighted option background</td></tr>
+<tr><td>`--combobox_option-color--highlighted`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Highlighted option text colour</td></tr>
 </tbody>
 </table>
 

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

@@ -73,7 +73,7 @@
     padding: var(--bds-space_xxs) 0;
     border: var(--combobox_listbox-border, none);
     --bdc_color: currentcolor;
-    --bdc-outline_radius: var(--bds-border_radius--xs);
+    --bdc-outline_radius: var(--bds-border_radius--s);
 
     border-radius: var(--combobox_listbox-radius, var(--bdc-outline_radius));
     background-color: var(--combobox_color, var(--bds-color_bg));
@@ -92,8 +92,8 @@
   }
 
   .option.--highlighted {
-    background-color: var(--bds-color_bg--subtle);
-    color: var(--bds-color_interactive_on-bg);
+    background-color: var(--combobox_option-bg--highlighted, var(--bds-color_bg--subtle));
+    color: var(--combobox_option-color--highlighted, var(--bds-color_interactive_on-bg));
   }
 
   .option.--selected {

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

@@ -41,6 +41,8 @@ File upload input with styled trigger button, hint, and error support.
 <tbody>
 <tr><td>`--fileInput_color`</td><td>`var(--bds-color_on-bg)`</td><td>Text colour</td></tr>
 <tr><td>`--fileInput_border-color`</td><td>`currentcolor`</td><td>Drop zone border colour</td></tr>
+<tr><td>`--fileInput_border-color--hover`</td><td>`var(--bds-color_interactive)`</td><td>Drop zone border colour on hover</td></tr>
+<tr><td>`--fileInput_bg--hover`</td><td>`rgb(from var(--bds-color_interactive) r g b / 4%)`</td><td>Drop zone background on hover</td></tr>
 </tbody>
 </table>
 

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

@@ -80,8 +80,8 @@
 
   @media (hover: hover) and (pointer: fine) {
     .dropZone:not(.isDisabled):hover {
-      border-color: var(--bds-color_interactive);
-      background-color: rgb(from var(--bds-color_interactive) r g b / 4%);
+      border-color: var(--fileInput_border-color--hover, var(--bds-color_interactive));
+      background-color: var(--fileInput_bg--hover, rgb(from var(--bds-color_interactive) r g b / 4%));
     }
   }
 }

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

@@ -43,6 +43,10 @@ Numeric text input with increment/decrement stepper buttons. Enforces `min`, `ma
 <tr><td>`--numberInput_border`</td><td>`none`</td><td>Border</td></tr>
 <tr><td>`--numberInput_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Corner radius</td></tr>
 <tr><td>`--numberInput_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Box shadow</td></tr>
+<tr><td>`--numberInput_stepper-color`</td><td>`var(--bds-color_interactive)`</td><td>Stepper button icon colour</td></tr>
+<tr><td>`--numberInput_stepper-bg`</td><td>`var(--bds-color_bg--subtle)`</td><td>Stepper button background</td></tr>
+<tr><td>`--numberInput_stepper-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Stepper button background on hover</td></tr>
+<tr><td>`--numberInput_stepper-opacity--hover`</td><td>`0.7`</td><td>Stepper button opacity on hover</td></tr>
 </tbody>
 </table>
 

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

@@ -58,7 +58,7 @@
     justify-content: center;
     padding: var(--bds-space_xs);
     margin: 1px;
-    background-color: var(--bds-color_bg--subtle);
+    background-color: var(--numberInput_stepper-bg, var(--bds-color_bg--subtle));
     color: var(--numberInput_color, var(--bds-color_on-bg));
     cursor: pointer;
     transition: var(--bds-animation_transition);
@@ -88,8 +88,8 @@
 
   @media (hover: hover) and (pointer: fine) {
     .stepper:not(:disabled):hover {
-      background-color: var(--bds-color_bg--subtle);
-      opacity: 0.7;
+      background-color: var(--numberInput_stepper-bg--hover, var(--bds-color_bg--subtle));
+      opacity: var(--numberInput_stepper-opacity--hover, 0.7);
     }
   }
 }

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

@@ -103,6 +103,7 @@ When `selectedIndex` is omitted, the component auto-detects the active item from
 | `--control_label-color` | `var(--bds-color_on-bg--subtle)` | Inactive item text colour |
 | `--control_label-color--active` | `var(--bds-color_on-interactive)` (filled) / `var(--bds-color_interactive)` (outline) | Active item text colour |
 | `--control_label-color--hover` | `var(--bds-color_on-bg)` | Hovered inactive item text colour |
+| `--control_indicator-color` | `var(--bds-color_interactive)` | Outline indicator border colour (outline variant) |
 
 ## Accessibility
 

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

@@ -109,7 +109,7 @@
 
   .control.--variant_outline .indicator {
     display: block;
-    box-shadow: inset 0 0 0 2px var(--bds-color_interactive);
+    box-shadow: inset 0 0 0 2px var(--control_indicator-color, var(--bds-color_interactive));
   }
 
   @media (hover: hover) and (pointer: fine) {

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

@@ -47,6 +47,10 @@ Range input for selecting a numeric value within a bounded range.
 </thead>
 <tbody>
 <tr><td>`--slider_color-active`</td><td>`var(--bdc-color_active)`</td><td>Filled track and thumb colour</td></tr>
+<tr><td>`--slider_track-bg`</td><td>`var(--bds-color_bg--subtle)`</td><td>Unfilled track background</td></tr>
+<tr><td>`--slider_track-radius`</td><td>`var(--bds-border_radius--full)`</td><td>Track border radius</td></tr>
+<tr><td>`--slider_thumb-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Thumb border radius</td></tr>
+<tr><td>`--slider_color--error`</td><td>`var(--bds-color_error)`</td><td>Track and thumb colour in error state</td></tr>
 </tbody>
 </table>
 

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

@@ -31,8 +31,8 @@
       to right,
       var(--slider_color-active, var(--bdc-color_active)) 0%,
       var(--slider_color-active, var(--bdc-color_active)) var(--slider_fill),
-      var(--bds-color_bg--subtle) var(--slider_fill),
-      var(--bds-color_bg--subtle) 100%
+      var(--slider_track-bg, var(--bds-color_bg--subtle)) var(--slider_fill),
+      var(--slider_track-bg, var(--bds-color_bg--subtle)) 100%
     );
     cursor: pointer;
     transition: var(--bds-animation_transition);
@@ -75,19 +75,19 @@
   .sliderError {
     background: linear-gradient(
       to right,
-      var(--bds-color_error) 0%,
-      var(--bds-color_error) var(--slider_fill),
-      var(--bds-color_bg--subtle) var(--slider_fill),
-      var(--bds-color_bg--subtle) 100%
+      var(--slider_color--error, var(--bds-color_error)) 0%,
+      var(--slider_color--error, var(--bds-color_error)) var(--slider_fill),
+      var(--slider_track-bg, var(--bds-color_bg--subtle)) var(--slider_fill),
+      var(--slider_track-bg, var(--bds-color_bg--subtle)) 100%
     );
   }
 
   .sliderError::-webkit-slider-thumb {
-    background-color: var(--bds-color_error);
+    background-color: var(--slider_color--error, var(--bds-color_error));
   }
 
   .sliderError::-moz-range-thumb {
-    background-color: var(--bds-color_error);
+    background-color: var(--slider_color--error, var(--bds-color_error));
   }
 
   @media (prefers-reduced-motion: reduce) {

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

@@ -56,6 +56,9 @@ Toggle control for binary settings that take immediate effect — without requir
 <tr><td>`--switch_thumb-bg`</td><td>`var(--bds-color_grey)`</td><td>Thumb colour when off (also track outline)</td></tr>
 <tr><td>`--switch_track-bg--active`</td><td>`var(--bdc-color_active--subtle)`</td><td>Track background when on</td></tr>
 <tr><td>`--switch_thumb-bg--active`</td><td>`var(--bdc-color_active--strong)`</td><td>Thumb colour when on (also track outline)</td></tr>
+<tr><td>`--switch_track-radius`</td><td>`var(--bds-border_radius--full)`</td><td>Track border radius</td></tr>
+<tr><td>`--switch_thumb-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Thumb border radius</td></tr>
+<tr><td>`--switch_border-color--error`</td><td>`var(--bds-color_error)`</td><td>Track outline colour in error state</td></tr>
 </tbody>
 </table>
 

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

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

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

@@ -45,7 +45,7 @@ Multi-line text input with label, hint, and error support.
 <tr><td>`--textarea_color_bg`</td><td>`var(--bds-color_bg)`</td><td>Background colour</td></tr>
 <tr><td>`--textarea_color`</td><td>`var(--bds-color_on-bg)`</td><td>Text colour</td></tr>
 <tr><td>`--textarea_border`</td><td>`none`</td><td>Border</td></tr>
-<tr><td>`--textarea_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Corner radius</td></tr>
+<tr><td>`--textarea_radius`</td><td>`var(--bdc-outline_radius--l)` (1.5em)</td><td>Corner radius</td></tr>
 <tr><td>`--textarea_shadow`</td><td>`var(--bdc-outline_shadow)`</td><td>Box shadow</td></tr>
 </tbody>
 </table>

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

@@ -11,7 +11,7 @@
     padding: var(--bds-space_s);
     border: var(--textarea_border, none);
     --bdc_color: currentcolor;
-    --bdc-outline_radius: var(--bds-border_radius--xs);
+    --bdc-outline_radius: var(--bdc-outline_radius--l);
 
     border-radius: var(--textarea_radius, var(--bdc-outline_radius));
     box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--textarea_shadow, var(--bdc-outline_shadow));

package/src/components/layout/ButtonGroup/ButtonGroup.mdx

@@ -7,6 +7,8 @@ import * as Stories from './ButtonGroup.stories';
 
 Layout wrapper that arranges `Button` children according to a contextual variant. Handles spacing, alignment, and direction.
 
+> **Recommended:** Always wrap buttons in a `ButtonGroup` when they appear inside a form. This ensures consistent spacing and alignment for form actions like submit, cancel, and navigation.
+
 ## Variants
 
 

package/src/components/layout/Card/Card.mdx

@@ -40,13 +40,16 @@ Contained surface for grouping related content. Three visual variants provide di
 
 <table>
 <thead>
-<tr><th>Variable</th><th>Description</th></tr>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--card_bg`</td><td>Card background colour</td></tr>
-<tr><td>`--card_on-bg`</td><td>Card text colour</td></tr>
-<tr><td>`--card_border-color`</td><td>Border colour (outlined variant)</td></tr>
-<tr><td>`--card_shadow`</td><td>Box shadow (elevated variant)</td></tr>
+<tr><td>`--card_color`</td><td>`var(--bds-color_bg)`</td><td>Card background colour</td></tr>
+<tr><td>`--card_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Card text colour</td></tr>
+<tr><td>`--card_border`</td><td>`none`</td><td>Border (outlined variant)</td></tr>
+<tr><td>`--card_shadow--clickable-hover`</td><td>`var(--bds-shadow_xl)`</td><td>Box shadow on hover for clickable cards</td></tr>
+<tr><td>`--card_shadow--default-hover`</td><td>`var(--bds-shadow_m)`</td><td>Box shadow on hover for default variant</td></tr>
+<tr><td>`--card_shadow--elevated-hover`</td><td>`var(--bds-shadow_2xl)`</td><td>Box shadow on hover for elevated variant</td></tr>
+<tr><td>`--card_shadow--outlined-hover`</td><td>`var(--bds-shadow_s)`</td><td>Box shadow on hover for outlined variant</td></tr>
 </tbody>
 </table>
 

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

@@ -67,19 +67,19 @@
   @media (hover: hover) and (pointer: fine) {
     .card.--clickable:hover {
       transform: translateY(-2px);
-      box-shadow: var(--bds-shadow_xl);
+      box-shadow: var(--card_shadow--clickable-hover, var(--bds-shadow_xl));
     }
 
     .card.--default:hover {
-      box-shadow: var(--bds-shadow_m);
+      box-shadow: var(--card_shadow--default-hover, var(--bds-shadow_m));
     }
 
     .card.--elevated:hover {
-      box-shadow: var(--bds-shadow_2xl);
+      box-shadow: var(--card_shadow--elevated-hover, var(--bds-shadow_2xl));
     }
 
     .card.--outlined:hover {
-      box-shadow: var(--bds-shadow_s);
+      box-shadow: var(--card_shadow--outlined-hover, var(--bds-shadow_s));
     }
   }
 }

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

@@ -19,12 +19,15 @@ Heading block with optional subtitle for introducing a content section.
 ### Without subtitle
 <Canvas of={Stories.WithoutSubtitle} />
 
-### Large
-<Canvas of={Stories.Large} />
+### Extra Small
+<Canvas of={Stories.ExtraSmall} />
 
 ### Small
 <Canvas of={Stories.Small} />
 
+### Large
+<Canvas of={Stories.Large} />
+
 ### Centered
 <Canvas of={Stories.Centered} />
 
@@ -40,7 +43,12 @@ 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-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>
 </tbody>
 </table>
 

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

@@ -34,37 +34,49 @@
     text-align: end;
   }
 
-  .sectionHeader.--small .title {
-    font-size: var(--bds-font_size--heading-1);
-    line-height: var(--bds-font_line-height--heading);
-    font-weight: var(--bds-font_weight--bold);
+  /* medium first — default size, so MCP extraction picks up its fallbacks */
+  .sectionHeader.--medium .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));
   }
 
-  .sectionHeader.--small .subtitle {
-    font-size: var(--bds-font_size--body);
+  .sectionHeader.--medium .subtitle {
+    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--heading-3));
+    line-height: 1.3;
+  }
+
+  .sectionHeader.--xs .title {
+    font-size: var(--sectionHeader_title-size, 1.5em);
+    line-height: var(--sectionHeader_title-line-height, var(--bds-font_line-height--heading));
+    font-weight: var(--sectionHeader_title-weight, var(--bds-font_weight--bold));
+  }
+
+  .sectionHeader.--xs .subtitle {
+    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--body));
     line-height: 1.4;
   }
 
-  .sectionHeader.--medium .title {
-    font-size: var(--bds-font_size--display);
-    line-height: var(--bds-font_line-height--display);
-    font-weight: var(--bds-font_weight--bold);
+  .sectionHeader.--small .title {
+    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--bold));
   }
 
-  .sectionHeader.--medium .subtitle {
-    font-size: var(--bds-font_size--heading-3);
-    line-height: 1.3;
+  .sectionHeader.--small .subtitle {
+    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--body));
+    line-height: 1.4;
   }
 
   .sectionHeader.--large .title {
-    font-size: var(--bds-font_size--display);
-    line-height: var(--bds-font_line-height--display);
-    font-weight: var(--bds-font_weight--bold);
+    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));
     letter-spacing: var(--bds-font_tracking--tight);
   }
 
   .sectionHeader.--large .subtitle {
-    font-size: var(--bds-font_size--heading-2);
+    font-size: var(--sectionHeader_subtitle-size, var(--bds-font_size--heading-2));
     line-height: 1.3;
     font-weight: var(--bds-font_weight--medium);
   }

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

@@ -28,4 +28,9 @@ describe('SectionHeader', () => {
     const { container } = render(<SectionHeader title="Title" className="custom" />);
     expect(container.firstChild).toHaveClass('custom');
   });
+
+  it('renders the xs size variant', () => {
+    const { container } = render(<SectionHeader title="XS Title" size="xs" />);
+    expect(container.firstChild).toHaveClass('--xs');
+  });
 });

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

@@ -6,7 +6,7 @@ const meta = {
   component: SectionHeader,
   argTypes: {
     alignment: { control: 'select', options: ['start', 'center', 'end'] },
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    size: { control: 'select', options: ['xs', 'small', 'medium', 'large'] },
   },
 } satisfies Meta<typeof SectionHeader>;
 
@@ -16,5 +16,6 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = { args: { title: 'Section Title', subtitle: 'A descriptive subtitle.' } };
 export const WithoutSubtitle: Story = { args: { title: 'Title Only' } };
 export const Centered: Story = { args: { title: 'Centered Title', subtitle: 'Centered subtitle.', alignment: 'center' } };
+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' } };

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

@@ -9,7 +9,7 @@ type SectionHeaderProps = WithClassName & Omit<HTMLAttributes<HTMLDivElement>, '
   title: string;
   subtitle?: string;
   alignment?: 'start' | 'center' | 'end';
-  size?: 'small' | 'medium' | 'large';
+  size?: 'xs' | 'small' | 'medium' | 'large';
   titleAs?: IntrinsicElement;
 };
 

package/src/components/ui/Accordion/Accordion.mdx

@@ -43,6 +43,7 @@ Vertically stacked sections that can be expanded and collapsed independently.
 <tbody>
 <tr><td>`--accordion_border`</td><td>`none`</td><td>Container border</td></tr>
 <tr><td>`--accordion_radius`</td><td>`var(--bdc-outline_radius)`</td><td>Container corner radius</td></tr>
+<tr><td>`--accordion_trigger-bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Trigger button background on hover</td></tr>
 </tbody>
 </table>
 

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

@@ -52,7 +52,7 @@
 
   @media (hover: hover) and (pointer: fine) {
     .trigger:not(:disabled):hover {
-      background-color: var(--bds-color_bg--subtle);
+      background-color: var(--accordion_trigger-bg--hover, var(--bds-color_bg--subtle));
     }
   }
 

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

@@ -47,11 +47,14 @@ Inline contextual feedback message. Use for confirmations, warnings, errors, and
 
 <table>
 <thead>
-<tr><th>Variable</th><th>Description</th></tr>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--alert_color`</td><td>Background colour (defaults to variant semantic token)</td></tr>
-<tr><td>`--alert_on-color`</td><td>Text and icon colour</td></tr>
+<tr><td>`--alert_color`</td><td>Per variant</td><td>Background colour (defaults to variant semantic token)</td></tr>
+<tr><td>`--alert_on-color`</td><td>Per variant</td><td>Text and icon colour</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>
+<tr><td>`--alert_dismiss-opacity--hover`</td><td>`0.7`</td><td>Dismiss button opacity on hover</td></tr>
 </tbody>
 </table>