@boostdev/design-system-components 2.5.0 → 2.6.0

package/src/components/layout/Grid/masonry.ts

@@ -225,12 +225,19 @@ export function applyMasonryLayout(
   // gaps; only galleries large enough to threaten the cap pay the rounding
   // cost. The unit always grows monotonically with content, so once a gallery
   // is above the threshold its layout is stable across runs.
+  //
+  // The projection treats each item as occupying `rowSpan × colSpan` cells
+  // — a `columnSpan="full"` item is a whole row to itself, a one-quarter
+  // item shares its row with three siblings. Summing the area and dividing
+  // by total columns gives a lower bound on implicit row count. (A naive
+  // `sum(rowSpan) / cols` would silently underestimate by avg-col-span and
+  // leave galleries with multi-column items overflowing browser caps.)
   const cols = countGridColumns(container) || 1;
-  const totalRowSum = heights.reduce(
-    (s, h) => s + Math.max(1, Math.ceil(h + targetGap)),
-    0,
-  );
-  const projectedRows = totalRowSum / cols;
+  const projectedRows = children.reduce((sum, child, i) => {
+    const rowSpan = Math.max(1, Math.ceil(heights[i] + targetGap));
+    const colSpan = readExplicitSpan(child, cols);
+    return sum + rowSpan * colSpan;
+  }, 0) / cols;
   const autoUnit = Math.max(
     1,
     Math.ceil(projectedRows / TARGET_MAX_IMPLICIT_ROWS),

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 {

package/src/components/ui/Tabs/Tabs.mdx

@@ -35,20 +35,35 @@ Organises content into discrete panels accessible via a horizontal tab list.
 
 ## CSS variables
 
+The override surface is **layered**. Setting `--tab_color` / `--tab_border-color` on the tablist (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>`--tab_color`</td><td>`var(--bds-color_on-bg)`</td><td>Default tab text colour</td></tr>
-<tr><td>`--tab_border-color`</td><td>`transparent`</td><td>Default tab bottom border colour</td></tr>
-<tr><td>`--tab_color--active`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Active tab text colour</td></tr>
-<tr><td>`--tab_border-color--active`</td><td>`var(--bds-color_interactive)`</td><td>Active tab bottom border colour</td></tr>
-<tr><td>`--tab_color--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td><td>Tab text colour on hover</td></tr>
+<tr><td>`--tab_color`</td><td>per state</td><td>Tab text colour. Set to theme every state at once.</td></tr>
+<tr><td>`--tab_border-color`</td><td>per state</td><td>Tab block-end border colour.</td></tr>
+</tbody>
+</table>
+
+### Per-state overrides
+
+<table>
+<thead>
+<tr><th>State</th><th>Text</th><th>Border</th></tr>
+</thead>
+<tbody>
+<tr><td>resting</td><td>(`var(--bds-color_on-bg)`)</td><td>(`transparent`)</td></tr>
+<tr><td>hover</td><td>`--tab_color--hover`</td><td>—</td></tr>
+<tr><td>active</td><td>`--tab_color--active`</td><td>`--tab_border-color--active`</td></tr>
 </tbody>
 </table>
 
+Defaults: hover/active text resolves to `--bds-color_interactive_on-bg`; active border to `--bds-color_interactive`.
+
 
 ## Accessibility
 

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

@@ -18,16 +18,19 @@
     font-family: var(--bds-font_family--body);
     font-size: var(--bds-font_size--body);
     font-weight: var(--bds-font_weight--semibold);
-    color: var(--tab_color, var(--bds-color_on-bg));
-    border-block-end: 2px solid var(--tab_border-color, transparent);
+
+    /* Layered cascade: public overrides (--tab_color, --tab_border-color) win over
+       per-state defaults. Active/hover write to the inner --tab_*--state slot. */
+    color:            var(--tab_color, var(--tab_color--state, var(--bds-color_on-bg)));
+    border-block-end: 2px solid var(--tab_border-color, var(--tab_border-color--state, transparent));
     margin-block-end: -1px;
     cursor: pointer;
     transition: var(--bds-animation_transition);
   }
 
   .tab.--active {
-    --tab_color:        var(--tab_color--active, var(--bds-color_interactive_on-bg));
-    --tab_border-color: var(--tab_border-color--active, var(--bds-color_interactive));
+    --tab_color--state:        var(--tab_color--active, var(--bds-color_interactive_on-bg));
+    --tab_border-color--state: var(--tab_border-color--active, var(--bds-color_interactive));
   }
 
   .tab:disabled {
@@ -43,7 +46,7 @@
 
   @media (hover: hover) and (pointer: fine) {
     .tab:not(:disabled, .--active):hover {
-      --tab_color: var(--tab_color--hover, var(--bds-color_interactive_on-bg));
+      --tab_color--state: var(--tab_color--hover, var(--bds-color_interactive_on-bg));
     }
   }