@boostdev/design-system-components 2.5.1 → 2.7.0

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

@@ -0,0 +1,64 @@
+import { Children, CSSProperties, FieldsetHTMLAttributes, ReactNode } from 'react';
+import { cn } from '@boostdev/design-system-foundation';
+import css from './FieldGroup.module.css';
+import type { WithClassName } from '../../../../types';
+
+/**
+ * Layout variants for FieldGroup.
+ *
+ * - `horizontal` (default) — fields flow into a row, each claiming at least
+ *   `--fieldGroup_min-field-width`. When the container's inline-size is too
+ *   narrow to fit the row, a CSS container query collapses the layout to a
+ *   single column.
+ * - `vertical` — fields always stack one per row.
+ */
+export type FieldGroupVariant = 'horizontal' | 'vertical';
+
+export interface FieldGroupProps
+  extends WithClassName,
+    FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  /** Layout direction. Defaults to `horizontal`. */
+  variant?: FieldGroupVariant;
+  /**
+   * Optional legend rendered above the fields. When omitted, set
+   * `aria-label` or `aria-labelledby` on the fieldset for accessibility.
+   */
+  legend?: ReactNode;
+}
+
+/**
+ * `FieldGroup` semantically groups related form fields under a single
+ * `<fieldset>` and lays them out either horizontally (with container-query
+ * fallback to vertical) or vertically.
+ */
+export function FieldGroup({
+  variant = 'horizontal',
+  legend,
+  children,
+  className,
+  style,
+  ...rest
+}: Readonly<FieldGroupProps>) {
+  // Surface the field count to CSS so the @container collapse threshold
+  // scales with the actual content. The CSS uses
+  //   N * --fieldGroup_min-field-width + (N - 1) * --fieldGroup_gap
+  // which is exactly the inline-size required to lay all fields out at
+  // their minimum width with the configured gap. When the FieldGroup's own
+  // inline-size drops below that, the layout collapses to a single column.
+  const fieldCount = Children.count(children);
+  const styleWithCount = {
+    ...style,
+    '--fieldGroup_field-count': fieldCount,
+  } as CSSProperties;
+
+  return (
+    <fieldset
+      {...rest}
+      style={styleWithCount}
+      className={cn(css.fieldGroup, css[`--variant_${variant}`], className)}
+    >
+      {legend !== undefined && <legend className={css.legend}>{legend}</legend>}
+      <div className={css.fields}>{children}</div>
+    </fieldset>
+  );
+}

package/src/components/interaction/form/FieldGroup/index.ts

@@ -0,0 +1,2 @@
+export { FieldGroup } from './FieldGroup';
+export type { FieldGroupProps, FieldGroupVariant } from './FieldGroup';

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

@@ -8,4 +8,8 @@
   .error {
     color: var(--bds-color_error_on-bg);
   }
+
+  .hint {
+    font-style: italic;
+  }
 }

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

@@ -43,23 +43,35 @@ Contained surface for grouping related content. Three visual variants provide di
 
 ## CSS variables
 
+### Card surface
 
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<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>
+<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 prop default).</td></tr>
+<tr><td>`--card_border`</td><td>`none`</td><td>Border (outlined variant).</td></tr>
 </tbody>
 </table>
 
+### Per-variant box-shadow (resting + hover)
+
+<table>
+<thead>
+<tr><th>Variant</th><th>Resting shadow</th><th>Hover shadow</th></tr>
+</thead>
+<tbody>
+<tr><td>`default`</td><td>`--card_shadow--default` (`var(--bds-shadow_s)`)</td><td>`--card_shadow--default-hover` (`var(--bds-shadow_m)`)</td></tr>
+<tr><td>`elevated`</td><td>`--card_shadow--elevated` (`var(--bds-shadow_m)`)</td><td>`--card_shadow--elevated-hover` (`var(--bds-shadow_2xl)`)</td></tr>
+<tr><td>`outlined`</td><td>`--card_shadow--outlined` (inset border + `var(--bds-shadow_s)`)</td><td>`--card_shadow--outlined-hover` (`var(--bds-shadow_s)`)</td></tr>
+</tbody>
+</table>
+
+Plus `--card_shadow--clickable-hover` (`var(--bds-shadow_xl)`) for hover on any clickable card.
+
 
 ## Accessibility
 

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

@@ -7,19 +7,21 @@
     position: relative;
   }
 
+  /* Resting shadows — consumers can override per-variant via
+     --card_shadow--default / --card_shadow--elevated / --card_shadow--outlined. */
   .card.--default {
-    box-shadow: var(--bds-shadow_s);
+    box-shadow: var(--card_shadow--default, var(--bds-shadow_s));
   }
 
   .card.--elevated {
-    box-shadow: var(--bds-shadow_m);
+    box-shadow: var(--card_shadow--elevated, var(--bds-shadow_m));
   }
 
   .card.--outlined {
     border: var(--card_border, none);
     --bdc_color: currentcolor;
 
-    box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--bds-shadow_s);
+    box-shadow: var(--card_shadow--outlined, inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--bds-shadow_s));
   }
 
   .card.--clickable {

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

@@ -44,20 +44,54 @@ Inline contextual feedback message. Use for confirmations, warnings, errors, and
 
 ## CSS variables
 
+The override surface is **layered**. Setting a public token on the alert (or any ancestor) themes every variant; setting a per-variant token themes only that one variant.
+
+```css
+/* Brand every alert (regardless of variant) */
+.brand-alerts {
+  --alert_bg:     var(--brand-bg);
+  --alert_text:   var(--brand-text);
+  --alert_border: var(--brand-border);
+}
+
+/* Or target a single variant */
+.brand-alerts {
+  --alert_bg--success: var(--brand-success);
+}
+```
+
+### Public override tokens (win over variant defaults)
 
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<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>
+<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_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>
+
+### Per-variant overrides
+
+<table>
+<thead>
+<tr><th>Variant</th><th>Background</th><th>Text</th><th>Border</th></tr>
+</thead>
+<tbody>
+<tr><td>`info`</td><td>`--alert_bg--info`</td><td>`--alert_text--info`</td><td>`--alert_border--info`</td></tr>
+<tr><td>`success`</td><td>`--alert_bg--success`</td><td>`--alert_text--success`</td><td>`--alert_border--success`</td></tr>
+<tr><td>`warning`</td><td>`--alert_bg--warning`</td><td>`--alert_text--warning`</td><td>`--alert_border--warning`</td></tr>
+<tr><td>`error`</td><td>`--alert_bg--error`</td><td>`--alert_text--error`</td><td>`--alert_border--error`</td></tr>
 </tbody>
 </table>
 
+Defaults resolve to the corresponding `--bds-color_{variant}--subtle` / `--bds-color_on-{variant}--subtle` / `--bds-color_{variant}` foundation tokens.
+
 
 ## Accessibility
 

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

@@ -5,35 +5,41 @@
         gap: var(--bds-space_s);
         padding: var(--bds-space_m);
         border-radius: var(--bds-border_radius--s);
-        border-inline-start: var(--bds-space_s) solid var(--alert_border, var(--bds-color_blue));
-        background-color: var(--alert_bg, var(--bds-color_blue--subtle));
-        color: var(--alert_text, var(--bds-color_on-blue--subtle));
+
+        /* Layered cascade: public overrides (--alert_bg, --alert_text, --alert_border)
+           are read OUTERMOST so an ancestor-set value always wins over variant
+           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)));
         font-size: var(--bds-font_size--body);
         line-height: var(--bds-font_line-height--body);
     }
 
+    /* Per-variant resting overrides — consumers can theme per-variant via
+       --alert_bg--info / --alert_bg--success / ... */
     .--variant_info {
-        --alert_bg: var(--bds-color_blue--subtle);
-        --alert_text: var(--bds-color_on-blue--subtle);
-        --alert_border: var(--bds-color_blue);
+        --alert_bg--variant:     var(--alert_bg--info, var(--bds-color_blue--subtle));
+        --alert_text--variant:   var(--alert_text--info, var(--bds-color_on-blue--subtle));
+        --alert_border--variant: var(--alert_border--info, var(--bds-color_blue));
     }
 
     .--variant_success {
-        --alert_bg: var(--bds-color_success--subtle);
-        --alert_text: var(--bds-color_on-success--subtle);
-        --alert_border: var(--bds-color_success);
+        --alert_bg--variant:     var(--alert_bg--success, var(--bds-color_success--subtle));
+        --alert_text--variant:   var(--alert_text--success, var(--bds-color_on-success--subtle));
+        --alert_border--variant: var(--alert_border--success, var(--bds-color_success));
     }
 
     .--variant_warning {
-        --alert_bg: var(--bds-color_orange--subtle);
-        --alert_text: var(--bds-color_on-orange--subtle);
-        --alert_border: var(--bds-color_warning);
+        --alert_bg--variant:     var(--alert_bg--warning, var(--bds-color_orange--subtle));
+        --alert_text--variant:   var(--alert_text--warning, var(--bds-color_on-orange--subtle));
+        --alert_border--variant: var(--alert_border--warning, var(--bds-color_warning));
     }
 
     .--variant_error {
-        --alert_bg: rgb(from var(--bds-color_error) r g b / 12%);
-        --alert_text: var(--bds-color_on-bg);
-        --alert_border: var(--bds-color_error);
+        --alert_bg--variant:     var(--alert_bg--error, rgb(from var(--bds-color_error) r g b / 12%));
+        --alert_text--variant:   var(--alert_text--error, var(--bds-color_on-bg));
+        --alert_border--variant: var(--alert_border--error, var(--bds-color_error));
     }
 
     .icon {

package/src/components/ui/Badge/Badge.mdx

@@ -42,19 +42,39 @@ Compact inline label for status, category, or count. Renders a `<span>` with a s
 
 ## CSS variables
 
-Override these on a parent element to customise the badge without touching global tokens:
+The override surface is **layered**. Setting a public token on the badge (or any ancestor) themes every variant; setting a per-variant token themes only that one variant.
 
+### Public override tokens (win over variant defaults)
 
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--badge_bg`</td><td>`var(--bds-color_blue)`</td><td>Background colour</td></tr>
-<tr><td>`--badge_text`</td><td>`var(--bds-color_on-blue)`</td><td>Text colour</td></tr>
+<tr><td>`--badge_bg`</td><td>per variant</td><td>Background colour. Set to theme every variant at once.</td></tr>
+<tr><td>`--badge_text`</td><td>per variant</td><td>Text colour.</td></tr>
+<tr><td>`--badge_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Badge border radius.</td></tr>
+<tr><td>`--badge_font-size`</td><td>`var(--bds-font_size--body--s)`</td><td>Badge font size.</td></tr>
 </tbody>
 </table>
 
+### Per-variant overrides
+
+<table>
+<thead>
+<tr><th>Variant</th><th>Background</th><th>Text</th></tr>
+</thead>
+<tbody>
+<tr><td>`primary`</td><td>`--badge_bg--primary`</td><td>`--badge_text--primary`</td></tr>
+<tr><td>`secondary`</td><td>`--badge_bg--secondary`</td><td>`--badge_text--secondary`</td></tr>
+<tr><td>`success`</td><td>`--badge_bg--success`</td><td>`--badge_text--success`</td></tr>
+<tr><td>`error`</td><td>`--badge_bg--error`</td><td>`--badge_text--error`</td></tr>
+<tr><td>`warning`</td><td>`--badge_bg--warning`</td><td>`--badge_text--warning`</td></tr>
+</tbody>
+</table>
+
+Defaults resolve to the corresponding `--bds-color_{variant}` / `--bds-color_on-{variant}` foundation tokens.
+
 
 ## Accessibility
 

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

@@ -9,32 +9,35 @@
     font-weight: var(--bds-font_weight--semibold);
     line-height: 1;
     white-space: nowrap;
-    background-color: var(--badge_bg, var(--bds-color_blue));
-    color: var(--badge_text, var(--bds-color_on-blue));
+
+    /* Layered cascade: public overrides (--badge_bg, --badge_text) win over
+       per-variant defaults. Variants write to the inner --badge_*--variant slot. */
+    background-color: var(--badge_bg, var(--badge_bg--variant, var(--bds-color_blue)));
+    color:            var(--badge_text, var(--badge_text--variant, var(--bds-color_on-blue)));
   }
 
   .--variant_primary {
-    --badge_bg:   var(--bds-color_interactive);
-    --badge_text: var(--bds-color_on-interactive);
+    --badge_bg--variant:   var(--badge_bg--primary, var(--bds-color_interactive));
+    --badge_text--variant: var(--badge_text--primary, var(--bds-color_on-interactive));
   }
 
   .--variant_secondary {
-    --badge_bg:   var(--bds-color_bg);
-    --badge_text: var(--bds-color_on-bg);
+    --badge_bg--variant:   var(--badge_bg--secondary, var(--bds-color_bg));
+    --badge_text--variant: var(--badge_text--secondary, var(--bds-color_on-bg));
   }
 
   .--variant_success {
-    --badge_bg:   var(--bds-color_success);
-    --badge_text: var(--bds-color_on-success);
+    --badge_bg--variant:   var(--badge_bg--success, var(--bds-color_success));
+    --badge_text--variant: var(--badge_text--success, var(--bds-color_on-success));
   }
 
   .--variant_error {
-    --badge_bg:   var(--bds-color_error);
-    --badge_text: var(--bds-color_on-error);
+    --badge_bg--variant:   var(--badge_bg--error, var(--bds-color_error));
+    --badge_text--variant: var(--badge_text--error, var(--bds-color_on-error));
   }
 
   .--variant_warning {
-    --badge_bg:   var(--bds-color_warning);
-    --badge_text: var(--bds-color_on-warning);
+    --badge_bg--variant:   var(--badge_bg--warning, var(--bds-color_warning));
+    --badge_text--variant: var(--badge_text--warning, var(--bds-color_on-warning));
   }
 }

package/src/components/ui/Link/Link.mdx

@@ -40,17 +40,35 @@ Styled anchor element with three visual variants. Renders as `<a>` by default, b
 
 ## CSS variables
 
+Resting and hover are **independent** — setting `--link_color` themes only resting; setting `--link_color-hover` themes only hover. Setting either as a per-variant token (`--link_color--subtle`, `--link_color-hover--standalone`, etc.) targets a single variant.
+
+### Public override tokens (win over variant defaults)
 
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--link_color`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Link text colour</td></tr>
-<tr><td>`--link_color-hover`</td><td>`var(--bds-color_blue--strong)`</td><td>Link text colour on hover</td></tr>
+<tr><td>`--link_color`</td><td>per variant</td><td>Link text colour at rest.</td></tr>
+<tr><td>`--link_color-hover`</td><td>per variant</td><td>Link text colour on hover.</td></tr>
+</tbody>
+</table>
+
+### Per-variant overrides
+
+<table>
+<thead>
+<tr><th>Variant</th><th>Resting</th><th>Hover</th></tr>
+</thead>
+<tbody>
+<tr><td>`default`</td><td>`--link_color--default`</td><td>`--link_color-hover--default`</td></tr>
+<tr><td>`subtle`</td><td>`--link_color--subtle`</td><td>`--link_color-hover--subtle`</td></tr>
+<tr><td>`standalone`</td><td>`--link_color--standalone`</td><td>`--link_color-hover--standalone`</td></tr>
 </tbody>
 </table>
 
+Defaults: `default` and `standalone` resolve to `--bds-color_interactive_on-bg` (resting) / `--bds-color_blue--strong` (hover); `subtle` resolves to `--bds-color_on-bg` / `--bds-color_interactive_on-bg`.
+
 
 ## Accessibility
 

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

@@ -1,6 +1,10 @@
 @layer boostdev.component {
   .link {
-    color: var(--link_color, var(--bds-color_interactive_on-bg));
+    /* Layered cascade: public override (--link_color) wins over per-variant defaults.
+       Variants write to the inner --link_color--variant slot.
+       Resting and hover have INDEPENDENT public tokens — setting --link_color on an
+       ancestor themes only resting; setting --link_color-hover themes only hover. */
+    color: var(--link_color, var(--link_color--variant, var(--bds-color_interactive_on-bg)));
     text-decoration: underline;
     text-underline-offset: 0.2em;
     transition: var(--bds-animation_transition);
@@ -15,23 +19,23 @@
 
   @media (hover: hover) and (pointer: fine) {
     .link:hover {
-      --link_color: var(--link_color-hover, var(--bds-color_blue--strong));
+      color: var(--link_color-hover, var(--link_color-hover--variant, var(--bds-color_blue--strong)));
     }
   }
 
   .--variant_default {
-    --link_color:       var(--bds-color_interactive_on-bg);
-    --link_color-hover: var(--bds-color_blue--strong);
+    --link_color--variant:       var(--link_color--default, var(--bds-color_interactive_on-bg));
+    --link_color-hover--variant: var(--link_color-hover--default, var(--bds-color_blue--strong));
   }
 
   .--variant_subtle {
-    --link_color:       var(--bds-color_on-bg);
-    --link_color-hover: var(--bds-color_interactive_on-bg);
+    --link_color--variant:       var(--link_color--subtle, var(--bds-color_on-bg));
+    --link_color-hover--variant: var(--link_color-hover--subtle, var(--bds-color_interactive_on-bg));
   }
 
   .--variant_standalone {
-    --link_color:       var(--bds-color_interactive_on-bg);
-    --link_color-hover: var(--bds-color_blue--strong);
+    --link_color--variant:       var(--link_color--standalone, var(--bds-color_interactive_on-bg));
+    --link_color-hover--variant: var(--link_color-hover--standalone, var(--bds-color_blue--strong));
 
     display: inline-flex;
     align-items: center;

package/src/components/ui/NotificationBanner/NotificationBanner.mdx

@@ -41,21 +41,40 @@ Full-width banner for page-level system messages. Sits at the top of the page or
 
 ## CSS variables
 
+The override surface is **layered**. Setting a public token on the banner (or any ancestor) themes every variant; setting a per-variant token themes only that one variant.
+
+### Public override tokens (win over variant defaults)
 
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--banner_bg`</td><td>Per variant</td><td>Banner background colour</td></tr>
-<tr><td>`--banner_text`</td><td>Per variant</td><td>Banner text colour</td></tr>
-<tr><td>`--banner_border`</td><td>Per variant</td><td>Banner bottom border colour</td></tr>
-<tr><td>`--banner_dismiss-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Dismiss button border radius</td></tr>
-<tr><td>`--banner_dismiss-border`</td><td>`none`</td><td>Dismiss button border</td></tr>
-<tr><td>`--banner_dismiss-opacity--hover`</td><td>`0.7`</td><td>Dismiss button opacity on hover</td></tr>
+<tr><td>`--banner_bg`</td><td>per variant</td><td>Banner background colour. Set to theme every variant at once.</td></tr>
+<tr><td>`--banner_text`</td><td>per variant</td><td>Banner text colour.</td></tr>
+<tr><td>`--banner_border`</td><td>per variant</td><td>Banner block-end border colour.</td></tr>
+<tr><td>`--banner_dismiss-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Dismiss button border radius.</td></tr>
+<tr><td>`--banner_dismiss-border`</td><td>`none`</td><td>Dismiss button border.</td></tr>
+<tr><td>`--banner_dismiss-opacity--hover`</td><td>`0.7`</td><td>Dismiss button opacity on hover.</td></tr>
+</tbody>
+</table>
+
+### Per-variant overrides
+
+<table>
+<thead>
+<tr><th>Variant</th><th>Background</th><th>Text</th><th>Border</th></tr>
+</thead>
+<tbody>
+<tr><td>`info`</td><td>`--banner_bg--info`</td><td>`--banner_text--info`</td><td>`--banner_border--info`</td></tr>
+<tr><td>`success`</td><td>`--banner_bg--success`</td><td>`--banner_text--success`</td><td>`--banner_border--success`</td></tr>
+<tr><td>`warning`</td><td>`--banner_bg--warning`</td><td>`--banner_text--warning`</td><td>`--banner_border--warning`</td></tr>
+<tr><td>`error`</td><td>`--banner_bg--error`</td><td>`--banner_text--error`</td><td>`--banner_border--error`</td></tr>
 </tbody>
 </table>
 
+Defaults resolve to the corresponding foundation tokens.
+
 
 ## Accessibility
 

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

@@ -4,36 +4,39 @@
     align-items: center;
     gap: var(--bds-space_m);
     padding: var(--bds-space_s) var(--bds-space_m);
-    background-color: var(--banner_bg, var(--bds-color_blue--subtle));
-    color: var(--banner_text, var(--bds-color_on-blue--subtle));
-    border-block-end: 3px solid var(--banner_border, var(--bds-color_blue));
+
+    /* Layered cascade: public overrides (--banner_bg, --banner_text, --banner_border)
+       win over per-variant defaults. Variants write to the inner --banner_*--variant slot. */
+    background-color: var(--banner_bg, var(--banner_bg--variant, var(--bds-color_blue--subtle)));
+    color:            var(--banner_text, var(--banner_text--variant, var(--bds-color_on-blue--subtle)));
+    border-block-end: 3px solid var(--banner_border, var(--banner_border--variant, var(--bds-color_blue)));
     font-size: var(--bds-font_size--body);
     line-height: var(--bds-font_line-height--body);
     inline-size: 100%;
   }
 
   .--variant_info {
-    --banner_bg: var(--bds-color_blue--subtle);
-    --banner_text: var(--bds-color_on-blue--subtle);
-    --banner_border: var(--bds-color_blue);
+    --banner_bg--variant:     var(--banner_bg--info, var(--bds-color_blue--subtle));
+    --banner_text--variant:   var(--banner_text--info, var(--bds-color_on-blue--subtle));
+    --banner_border--variant: var(--banner_border--info, var(--bds-color_blue));
   }
 
   .--variant_success {
-    --banner_bg: var(--bds-color_success--subtle);
-    --banner_text: var(--bds-color_on-success--subtle);
-    --banner_border: var(--bds-color_success);
+    --banner_bg--variant:     var(--banner_bg--success, var(--bds-color_success--subtle));
+    --banner_text--variant:   var(--banner_text--success, var(--bds-color_on-success--subtle));
+    --banner_border--variant: var(--banner_border--success, var(--bds-color_success));
   }
 
   .--variant_warning {
-    --banner_bg: var(--bds-color_orange--subtle);
-    --banner_text: var(--bds-color_on-orange--subtle);
-    --banner_border: var(--bds-color_warning);
+    --banner_bg--variant:     var(--banner_bg--warning, var(--bds-color_orange--subtle));
+    --banner_text--variant:   var(--banner_text--warning, var(--bds-color_on-orange--subtle));
+    --banner_border--variant: var(--banner_border--warning, var(--bds-color_warning));
   }
 
   .--variant_error {
-    --banner_bg: rgb(from var(--bds-color_error) r g b / 12%);
-    --banner_text: var(--bds-color_on-bg);
-    --banner_border: var(--bds-color_error);
+    --banner_bg--variant:     var(--banner_bg--error, rgb(from var(--bds-color_error) r g b / 12%));
+    --banner_text--variant:   var(--banner_text--error, var(--bds-color_on-bg));
+    --banner_border--variant: var(--banner_border--error, var(--bds-color_error));
   }
 
   .content {

package/src/components/ui/Pagination/Pagination.mdx

@@ -34,24 +34,37 @@ Navigation control for paged data sets. Renders prev/next buttons plus numbered
 
 ## CSS variables
 
+The override surface is **layered**. Setting `--btn_bg` / `--btn_color` / `--btn_border` on the pagination (or any ancestor) wins in every state — resting, hover, and active. Setting per-state tokens targets only that one state.
+
+### Public override tokens (win over per-state defaults)
 
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--pagination_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Page button border radius</td></tr>
-<tr><td>`--btn_bg`</td><td>`transparent`</td><td>Default button background</td></tr>
-<tr><td>`--btn_color`</td><td>`var(--bds-color_on-bg)`</td><td>Default button text colour</td></tr>
-<tr><td>`--btn_border`</td><td>`var(--bds-color_bg--subtle)`</td><td>Default button border colour</td></tr>
-<tr><td>`--btn_bg--hover`</td><td>`var(--bds-color_bg--subtle)`</td><td>Button background on hover</td></tr>
-<tr><td>`--btn_color--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Button text colour on hover</td></tr>
-<tr><td>`--btn_bg--active`</td><td>`var(--bds-color_interactive)`</td><td>Active (current page) button background</td></tr>
-<tr><td>`--btn_color--active`</td><td>`var(--bds-color_on-interactive)`</td><td>Active (current page) button text colour</td></tr>
-<tr><td>`--btn_border--active`</td><td>`var(--bds-color_interactive)`</td><td>Active (current page) button border colour</td></tr>
+<tr><td>`--pagination_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Page button border radius.</td></tr>
+<tr><td>`--btn_bg`</td><td>`transparent` (per state)</td><td>Button background. Set to theme every state at once.</td></tr>
+<tr><td>`--btn_color`</td><td>per state</td><td>Button text colour.</td></tr>
+<tr><td>`--btn_border`</td><td>per state</td><td>Button border colour.</td></tr>
+</tbody>
+</table>
+
+### Per-state overrides
+
+<table>
+<thead>
+<tr><th>State</th><th>Background</th><th>Text</th><th>Border</th></tr>
+</thead>
+<tbody>
+<tr><td>resting</td><td>(`transparent`)</td><td>(`var(--bds-color_on-bg)`)</td><td>(`var(--bds-color_bg--subtle)`)</td></tr>
+<tr><td>hover</td><td>`--btn_bg--hover`</td><td>`--btn_color--hover`</td><td>—</td></tr>
+<tr><td>active (current page)</td><td>`--btn_bg--active`</td><td>`--btn_color--active`</td><td>`--btn_border--active`</td></tr>
 </tbody>
 </table>
 
+Defaults: hover resolves to `--bds-color_bg--subtle` / `--bds-color_interactive_on-bg`; active resolves to `--bds-color_interactive` / `--bds-color_on-interactive`.
+
 
 ## Accessibility
 

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

@@ -26,13 +26,15 @@
     block-size: 2.25rem;
     padding-inline: var(--bds-space_xs);
     border-radius: var(--pagination_radius, var(--bds-border_radius--full));
-    background-color: var(--btn_bg, transparent);
 
-    --bdc_color: var(--btn_border, var(--bds-color_bg--subtle));
+    /* Layered cascade: public overrides (--btn_bg, --btn_color, --btn_border) win
+       over per-state defaults. Hover/active write to the inner --btn_*--state slot. */
+    background-color: var(--btn_bg, var(--btn_bg--state, transparent));
+    color:            var(--btn_color, var(--btn_color--state, var(--bds-color_on-bg)));
+    --bdc_color:      var(--btn_border, var(--btn_border--state, var(--bds-color_bg--subtle)));
 
     border: none;
     box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
-    color: var(--btn_color, var(--bds-color_on-bg));
     font-family: var(--bds-font_family--body);
     font-size: var(--bds-font_size--body);
     font-variant-numeric: tabular-nums;
@@ -53,15 +55,15 @@
 
   @media (hover: hover) and (pointer: fine) {
     .button:not(:disabled, .--active):hover {
-      --btn_bg:    var(--btn_bg--hover, var(--bds-color_bg--subtle));
-      --btn_color: var(--btn_color--hover, var(--bds-color_interactive_on-bg));
+      --btn_bg--state:    var(--btn_bg--hover, var(--bds-color_bg--subtle));
+      --btn_color--state: var(--btn_color--hover, var(--bds-color_interactive_on-bg));
     }
   }
 
   .button.--active {
-    --btn_bg:     var(--btn_bg--active, var(--bds-color_interactive));
-    --btn_color:  var(--btn_color--active, var(--bds-color_on-interactive));
-    --btn_border: var(--btn_border--active, var(--bds-color_interactive));
+    --btn_bg--state:     var(--btn_bg--active, var(--bds-color_interactive));
+    --btn_color--state:  var(--btn_color--active, var(--bds-color_on-interactive));
+    --btn_border--state: var(--btn_border--active, var(--bds-color_interactive));
   }
 
   .button.--nav svg {