@boostdev/design-system-components 1.2.5 → 1.2.7

package/src/components/interaction/Button/Button.mdx

@@ -12,6 +12,8 @@ Primary interactive element for triggering actions. Renders as `<button>` or `<a
 - Secondary or ghost actions (`ghost`)
 - Navigation that should look like an action (`href` → renders as `<a>`)
 
+> **Form actions:** When using buttons in a form (submit, reset, cancel), always wrap them in a `ButtonGroup` component. This provides consistent spacing, alignment, and responsive layout for form actions. Use `variant="flow"` for step navigation or `variant="card"` for single-form submissions.
+
 ## When not to use
 - Navigation to another page when it reads naturally as a link — use `Link` instead
 - When the action is purely icon-based without a label — ensure `aria-label` is set
@@ -53,11 +55,17 @@ Primary interactive element for triggering actions. Renders as `<button>` or `<a
 
 <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>`--button_color`</td><td>Identity colour — fills default, outlines ghost. Set this to re-theme.</td></tr>
-<tr><td>`--button_on-color`</td><td>Text/icon colour on the button. Pair with `--button_color`.</td></tr>
+<tr><td>`--button_color`</td><td>`var(--bds-color_interactive)`</td><td>Identity colour — fills default, outlines outline. Set this to re-theme.</td></tr>
+<tr><td>`--button_on-color`</td><td>`var(--bds-color_on-interactive)`</td><td>Text/icon colour on the button. Pair with `--button_color`.</td></tr>
+<tr><td>`--button_color--on-bg`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Text-safe variant of `--button_color` for outline variant text/border</td></tr>
+<tr><td>`--button_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Button border radius</td></tr>
+<tr><td>`--button_bg--hover`</td><td>`var(--bds-color_bg)`</td><td>Default variant background on hover</td></tr>
+<tr><td>`--button_text--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Default variant text colour on hover</td></tr>
+<tr><td>`--button_bg--outline-hover`</td><td>`var(--button_color)`</td><td>Outline variant background on hover</td></tr>
+<tr><td>`--button_text--outline-hover`</td><td>`var(--button_on-color)`</td><td>Outline variant text colour on hover</td></tr>
 </tbody>
 </table>
 

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

@@ -140,9 +140,9 @@
   /* Default hover: outline appears, bg becomes page surface */
   @media (hover: hover) and (pointer: fine) {
     .button.--default:hover {
-      --button_bg:          var(--bds-color_bg);
-      --button_text:        var(--bds-color_interactive_on-bg);
-      --button_pulse-color: var(--bds-color_interactive_on-bg);
+      --button_bg:          var(--button_bg--hover, var(--bds-color_bg));
+      --button_text:        var(--button_text--hover, var(--bds-color_interactive_on-bg));
+      --button_pulse-color: var(--button_pulse-color--hover, var(--bds-color_interactive_on-bg));
       --bdc_color:          currentcolor;
     }
   }
@@ -151,8 +151,8 @@
   @media (hover: hover) and (pointer: fine) {
     .button.--outline:hover,
     .button.--ghost:hover {
-      --button_bg:   var(--button_color);
-      --button_text: var(--button_on-color);
+      --button_bg:   var(--button_bg--outline-hover, var(--button_color));
+      --button_text: var(--button_text--outline-hover, var(--button_on-color));
       --bdc_color:   transparent;
     }
   }

package/src/components/interaction/Command/Command.mdx

@@ -32,6 +32,7 @@ Keyboard-first command palette for searching and executing actions. Commonly tri
 <tr><td>`--command_on-color`</td><td>`var(--bds-color_on-bg)`</td><td>Text and icon colour</td></tr>
 <tr><td>`--command_shadow`</td><td>`var(--bds-shadow_xl)`</td><td>Panel box shadow</td></tr>
 <tr><td>`--command_border`</td><td>`none`</td><td>Panel border</td></tr>
+<tr><td>`--command_item-bg--active`</td><td>`var(--bds-color_bg--subtle)`</td><td>Active/highlighted item background</td></tr>
 </tbody>
 </table>
 

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

@@ -106,7 +106,7 @@
   }
 
   .itemActive {
-    background-color: var(--bds-color_bg--subtle);
+    background-color: var(--command_item-bg--active, var(--bds-color_bg--subtle));
   }
 
   .itemLabel {

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

@@ -5,7 +5,7 @@ import * as Stories from './Card.stories';
 
 # Card
 
-Contained surface for grouping related content. Three visual variants provide different levels of elevation. When `onClick` is supplied, renders as a `<button>`.
+Contained surface for grouping related content. Three visual variants provide different levels of elevation. When `onClick` is supplied, renders as a `<button>`. Use the `as` prop to render as any element or component (e.g. `<a>`, `<section>`, or a Next.js `Link`).
 
 ## When to use
 - Group content that belongs together (product listing, profile summary, dashboard widget)
@@ -31,6 +31,12 @@ Contained surface for grouping related content. Three visual variants provide di
 ### Clickable
 <Canvas of={Stories.Clickable} />
 
+### As a link
+<Canvas of={Stories.AsLink} />
+
+### As a section
+<Canvas of={Stories.AsSection} />
+
 ## Props
 
 <ArgTypes of={Stories} />
@@ -40,13 +46,17 @@ 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_padding`</td><td>varies by `padding` prop</td><td>Card padding (overrides the variant default)</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>
 
@@ -55,4 +65,5 @@ Contained surface for grouping related content. Three visual variants provide di
 
 - Static card renders as `<div>` — no interactive role
 - Clickable card renders as `<button>` — keyboard and screen reader accessible
+- When using `as="a"`, provide a valid `href`; when using a router `Link`, ensure it forwards `className` and `children`
 - Ensure clickable cards have a meaningful accessible name (via visible text content)

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

@@ -27,19 +27,23 @@
   }
 
   .card.--padding-none {
-    padding: 0;
+    padding: var(--card_padding, 0);
   }
 
   .card.--padding-small {
-    padding: var(--bds-space_s);
+    padding: var(--card_padding, var(--bds-space_s));
   }
 
   .card.--padding-medium {
-    padding: var(--bds-space_m);
+    padding: var(--card_padding, var(--bds-space_m));
   }
 
   .card.--padding-large {
-    padding: var(--bds-space_l);
+    padding: var(--card_padding, var(--bds-space_l));
+  }
+
+  .card.--padding-extra-large {
+    padding: var(--card_padding, var(--bds-space_xl));
   }
 
   .card.--text-start {
@@ -67,19 +71,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/Card/Card.spec.tsx

@@ -30,4 +30,34 @@ describe('Card', () => {
     const { container } = render(<Card className="custom">Content</Card>);
     expect(container.firstChild).toHaveClass('custom');
   });
+
+  it('renders as a custom element via the as prop', () => {
+    const { container } = render(<Card as="section">Section card</Card>);
+    expect(container.firstChild?.nodeName).toBe('SECTION');
+  });
+
+  it('renders as an anchor when as="a"', () => {
+    render(<Card as="a" href="/details">Link card</Card>);
+    const link = screen.getByRole('link');
+    expect(link).toHaveAttribute('href', '/details');
+  });
+
+  it('renders as a custom component via the as prop', () => {
+    const CustomWrapper = ({ children, ...props }: { children: React.ReactNode; className?: string }) => (
+      <article {...props} data-testid="custom">{children}</article>
+    );
+    render(<Card as={CustomWrapper}>Custom</Card>);
+    expect(screen.getByTestId('custom')).toBeInTheDocument();
+    expect(screen.getByTestId('custom').nodeName).toBe('ARTICLE');
+  });
+
+  it('prefers as prop over onClick button fallback', () => {
+    const { container } = render(<Card as="div" onClick={() => {}}>Content</Card>);
+    expect(container.firstChild?.nodeName).toBe('DIV');
+  });
+
+  it('renders the extra-large padding variant', () => {
+    const { container } = render(<Card padding="extra-large">Content</Card>);
+    expect(container.firstChild).toHaveClass('--padding-extra-large');
+  });
 });