@boostdev/design-system-components 2.5.1 → 2.7.0

package/dist/web-components/{chunk-N3TN6WCH.js → chunk-GER5UJOF.js}

@@ -40,14 +40,20 @@ var BdsButton = class extends i2 {
       white-space: nowrap;
       line-height: 1;
 
+      /* Identity tokens — override --button_color + --button_on-color to re-theme */
       --button_color:        var(--bds-color_interactive);
       --button_on-color:     var(--bds-color_on-interactive);
+
+      /* Text-safe variant of --button_color for use on page background (outline text/border) */
       --button_color--on-bg: var(--bds-color_interactive_on-bg);
 
-      background-color: var(--button_bg, var(--button_color));
-      color: var(--button_text, var(--button_on-color));
-      border: var(--button_border, none);
-      --bdc_color: transparent;
+      /* Layered cascade: the consumer-facing overrides (--button_bg, --button_text,
+         --button_border) are read OUTERMOST so an ancestor-set value always wins
+         over variant + hover defaults. Variants and hover write to the inner
+         --button_*--variant slot, never to the public tokens. */
+      background-color: var(--button_bg, var(--button_bg--variant, var(--button_color)));
+      color:            var(--button_text, var(--button_text--variant, var(--button_on-color)));
+      --bdc_color:      var(--button_border, var(--button_border--variant, transparent));
 
       box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
       transition: var(--bds-animation_transition),
@@ -58,12 +64,13 @@ var BdsButton = class extends i2 {
       text-decoration: none;
     }
 
-    /* Variants */
+    /* Variants — outline-resting overrides (--button_bg--outline, --button_text--outline,
+       --button_border--outline) are honored if the consumer sets them. */
     .button.outline,
     .button.ghost /* deprecated — use variant="outline" */ {
-      --button_bg:   transparent;
-      --button_text: var(--button_color--on-bg);
-      --bdc_color:   var(--button_color--on-bg);
+      --button_bg--variant:     var(--button_bg--outline, transparent);
+      --button_text--variant:   var(--button_text--outline, var(--button_color--on-bg));
+      --button_border--variant: var(--button_border--outline, var(--button_color--on-bg));
     }
 
     /* Sizes */
@@ -149,18 +156,18 @@ var BdsButton = class extends i2 {
 
       /* Default hover */
       .button.default:hover {
-        --button_bg:          var(--bds-color_bg);
-        --button_text:        var(--bds-color_interactive);
-        --button_pulse-color: var(--bds-color_interactive);
-        --bdc_color:          currentcolor;
+        --button_bg--variant:     var(--button_bg--hover, var(--bds-color_bg));
+        --button_text--variant:   var(--button_text--hover, var(--bds-color_interactive));
+        --button_border--variant: var(--button_border--hover, currentcolor);
+        --button_pulse-color:     var(--button_pulse-color--hover, var(--bds-color_interactive));
       }
 
       /* Outline hover */
       .button.outline:hover,
       .button.ghost:hover {
-        --button_bg:   var(--button_color);
-        --button_text: var(--button_on-color);
-        --bdc_color:   transparent;
+        --button_bg--variant:     var(--button_bg--outline-hover, var(--button_color));
+        --button_text--variant:   var(--button_text--outline-hover, var(--button_on-color));
+        --button_border--variant: var(--button_border--outline-hover, transparent);
       }
     }
 

package/dist/web-components/chunk-QWPACK5L.js

@@ -0,0 +1,72 @@
+import {
+  T,
+  i,
+  i2
+} from "./chunk-LGEZYFUU.js";
+
+// src/web-components/ui/bds-badge.ts
+var BdsBadge = class extends i2 {
+  static styles = i`
+    :host {
+      display: inline-flex;
+    }
+
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: var(--bds-space_xxs) var(--bds-space_xs);
+      border-radius: var(--badge_radius, 2em);
+      font-size: var(--badge_font-size, var(--bds-font_size--body--s));
+      font-weight: var(--bds-font_weight--semibold);
+      line-height: 1;
+      white-space: nowrap;
+      /* 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)));
+    }
+
+    /* Per-variant resting overrides — consumers can theme per-variant via
+       --badge_bg--primary / --badge_bg--success / ... */
+    :host([variant='primary']) .badge {
+      --badge_bg--variant:   var(--badge_bg--primary, var(--bds-color_interactive));
+      --badge_text--variant: var(--badge_text--primary, var(--bds-color_on-interactive));
+    }
+
+    :host([variant='secondary']) .badge {
+      --badge_bg--variant:   var(--badge_bg--secondary, var(--bds-color_bg));
+      --badge_text--variant: var(--badge_text--secondary, var(--bds-color_on-bg));
+    }
+
+    :host([variant='success']) .badge {
+      --badge_bg--variant:   var(--badge_bg--success, var(--bds-color_success));
+      --badge_text--variant: var(--badge_text--success, var(--bds-color_on-success));
+    }
+
+    :host([variant='error']) .badge {
+      --badge_bg--variant:   var(--badge_bg--error, var(--bds-color_error));
+      --badge_text--variant: var(--badge_text--error, var(--bds-color_on-error));
+    }
+
+    :host([variant='warning']) .badge {
+      --badge_bg--variant:   var(--badge_bg--warning, var(--bds-color_warning));
+      --badge_text--variant: var(--badge_text--warning, var(--bds-color_on-warning));
+    }
+  `;
+  static properties = {
+    variant: { type: String, reflect: true }
+  };
+  constructor() {
+    super();
+    this.variant = "primary";
+  }
+  render() {
+    return T`<span class="badge"><slot></slot></span>`;
+  }
+};
+customElements.define("bds-badge", BdsBadge);
+
+export {
+  BdsBadge
+};

package/dist/web-components/{chunk-YRXCVKHV.js → chunk-RTOS7LLG.js}

@@ -25,12 +25,14 @@ var BdsCard = class extends i2 {
       border: none;
     }
 
-    .card.--default  { box-shadow: var(--bds-shadow_s); }
-    .card.--elevated { box-shadow: var(--bds-shadow_m); }
+    /* Resting shadows — consumers can override per-variant via
+       --card_shadow--default / --card_shadow--elevated / --card_shadow--outlined. */
+    .card.--default  { box-shadow: var(--card_shadow--default, var(--bds-shadow_s)); }
+    .card.--elevated { box-shadow: var(--card_shadow--elevated, var(--bds-shadow_m)); }
 
     .card.--outlined {
       --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.--padding-none   { padding: 0; }
@@ -60,12 +62,12 @@ var BdsCard = class extends i2 {
     @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); }
-      .card.--elevated:hover { box-shadow: var(--bds-shadow_2xl); }
-      .card.--outlined:hover { box-shadow: var(--bds-shadow_s); }
+      .card.--default:hover  { box-shadow: var(--card_shadow--default-hover, var(--bds-shadow_m)); }
+      .card.--elevated:hover { box-shadow: var(--card_shadow--elevated-hover, var(--bds-shadow_2xl)); }
+      .card.--outlined:hover { box-shadow: var(--card_shadow--outlined-hover, var(--bds-shadow_s)); }
     }
   `;
   static properties = {

package/dist/web-components/{chunk-BX3IPVOB.js → chunk-ZNKEZIYE.js}

@@ -18,36 +18,40 @@ var BdsAlert = class extends i2 {
       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);
     }
 
-    /* Variant colours */
+    /* Per-variant resting overrides — consumers can theme per-variant via
+       --alert_bg--info / --alert_bg--success / ... */
     :host([variant='info']) .alert {
-      --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));
     }
 
     :host([variant='success']) .alert {
-      --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));
     }
 
     :host([variant='warning']) .alert {
-      --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));
     }
 
     :host([variant='error']) .alert {
-      --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 slot wrapper — hidden unless slot has content */

package/dist/web-components/index.d.ts

@@ -426,6 +426,61 @@ declare global {
     }
 }
 
+type FieldGroupVariant = 'horizontal' | 'vertical';
+/**
+ * `<bds-field-group>` — framework-agnostic FieldGroup custom element.
+ *
+ * Semantically groups related form fields under a single `<fieldset>` and
+ * lays them out either horizontally (with a CSS container query that
+ * collapses to a vertical stack when the FieldGroup itself is too narrow)
+ * or vertically. Mirrors the React `FieldGroup` component.
+ *
+ * Attributes:
+ *   variant  — "horizontal" (default) | "vertical"
+ *   legend   — optional legend text rendered above the fields
+ *   disabled — boolean; forwarded to the inner <fieldset>
+ *
+ * Slots:
+ *   (default) — form fields (any element). The slotted-element count is
+ *     measured on each `slotchange` and surfaced via the
+ *     `--fieldGroup_field-count` custom property, which the auto-derived
+ *     collapse threshold reads.
+ *
+ * @example
+ * <bds-field-group variant="horizontal" legend="Contact details">
+ *   <bds-form-input label="First name" name="first"></bds-form-input>
+ *   <bds-form-input label="Last name"  name="last"></bds-form-input>
+ *   <bds-form-input label="Email"      name="email"></bds-form-input>
+ * </bds-field-group>
+ */
+declare class BdsFieldGroup extends LitElement {
+    static styles: lit.CSSResult;
+    static properties: {
+        variant: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        legend: {
+            type: StringConstructor;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+    };
+    variant: FieldGroupVariant;
+    legend: string;
+    disabled: boolean;
+    constructor();
+    private _onSlotChange;
+    render(): lit.TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'bds-field-group': BdsFieldGroup;
+    }
+}
+
 /**
  * `<bds-form-input>` — form-associated text input with label, hint, and error support.
  *
@@ -749,4 +804,4 @@ declare global {
     }
 }
 
-export { BdsButtonGroup, BdsCalendar, BdsCarousel, BdsCheckboxGroup, BdsDropdownMenu, BdsDropdownMenuItem, BdsFormInput, BdsGrid, BdsGridItem, BdsPagination, BdsRadioGroup, BdsTable };
+export { BdsButtonGroup, BdsCalendar, BdsCarousel, BdsCheckboxGroup, BdsDropdownMenu, BdsDropdownMenuItem, BdsFieldGroup, type FieldGroupVariant as BdsFieldGroupVariant, BdsFormInput, BdsGrid, BdsGridItem, BdsPagination, BdsRadioGroup, BdsTable };

package/dist/web-components/index.js

@@ -69,7 +69,7 @@ import {
 } from "./chunk-UFFCKVZE.js";
 import {
   BdsButton
-} from "./chunk-N3TN6WCH.js";
+} from "./chunk-GER5UJOF.js";
 import {
   BdsCollapsible
 } from "./chunk-6I2DBFQ7.js";
@@ -104,23 +104,24 @@ import "./chunk-QPOKHLMQ.js";
 import "./chunk-3S42DZ7W.js";
 import {
   BdsAlert
-} from "./chunk-BX3IPVOB.js";
+} from "./chunk-ZNKEZIYE.js";
 import {
   BdsAvatar
 } from "./chunk-57TRNCWQ.js";
 import {
   BdsBadge
-} from "./chunk-OHUTLSIQ.js";
+} from "./chunk-QWPACK5L.js";
 import {
   BdsBreadcrumb
 } from "./chunk-Q4T5BJT6.js";
 import {
   BdsCard
-} from "./chunk-YRXCVKHV.js";
+} from "./chunk-RTOS7LLG.js";
 import {
   BdsDescriptionList
 } from "./chunk-AGKJTMJI.js";
 import {
+  A,
   T,
   i,
   i2
@@ -881,6 +882,7 @@ var BdsCheckboxGroup = class extends i2 {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
   static properties = {
@@ -957,6 +959,7 @@ var BdsRadioGroup = class extends i2 {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
   static properties = {
@@ -1007,6 +1010,118 @@ var BdsRadioGroup = class extends i2 {
 };
 customElements.define("bds-radio-group", BdsRadioGroup);
 
+// src/web-components/interaction/form/bds-field-group.ts
+var BdsFieldGroup = class extends i2 {
+  static styles = i`
+    :host {
+      display: block;
+
+      /* Establish an inline-size containment context so the @container rule
+         queries the host's own width — independent of the viewport. */
+      container-type: inline-size;
+      container-name: field-group;
+
+      /* Auto-derived collapse threshold (mirror of the React component).
+         --fieldGroup_field-count is set inline by _onSlotChange; the other
+         tokens use foundation-default fallbacks so the calc rebuilds when
+         a consumer overrides --fieldGroup_min-field-width or _gap. */
+      --fieldGroup_collapse-threshold:
+        calc(
+          var(--fieldGroup_field-count, 1)
+          * var(--fieldGroup_min-field-width, 12rem)
+          + (var(--fieldGroup_field-count, 1) - 1)
+          * var(--fieldGroup_gap, var(--bds-space_m))
+        );
+    }
+
+    fieldset {
+      border: 0;
+      margin: 0;
+      padding: 0;
+      min-inline-size: 0;
+    }
+
+    .legend {
+      inline-size: 100%;
+      padding-inline: 0;
+
+      padding-block:
+        var(--fieldGroup_legend-padding-block, var(--bds-space_xs));
+      margin-block-end:
+        var(--fieldGroup_legend-gap, var(--bds-space_m));
+      border-block-end:
+        var(--fieldGroup_legend-border-block-end, 1px solid var(--bds-color_bg--subtle));
+
+      color:
+        var(--fieldGroup_legend-color, var(--bds-color_on-bg));
+      font-family: var(--bds-font_family--body);
+      font-size:
+        var(--fieldGroup_legend-font-size, var(--bds-font_size--heading-3));
+      font-weight:
+        var(--fieldGroup_legend-font-weight, var(--bds-font_weight--semibold));
+      line-height:
+        var(--fieldGroup_legend-line-height, var(--bds-font_line-height--heading));
+    }
+
+    .fields {
+      display: flex;
+      flex-direction: column;
+      gap: var(--fieldGroup_gap, var(--bds-space_m));
+    }
+
+    :host([variant='horizontal']) .fields {
+      flex-flow: row wrap;
+    }
+
+    :host([variant='horizontal']) .fields ::slotted(*) {
+      flex: 1 1 var(--fieldGroup_min-field-width, 12rem);
+      min-inline-size: 0;
+    }
+
+    /* Auto-collapse: when the host's inline-size can't fit a complete
+       horizontal row, switch to a single-column stack. Threshold scales
+       with the actual slotted-element count (see :host calc above). */
+    @container field-group (max-inline-size: var(--fieldGroup_collapse-threshold)) {
+      :host([variant='horizontal']) .fields {
+        flex-direction: column;
+      }
+
+      :host([variant='horizontal']) .fields ::slotted(*) {
+        flex: 1 1 auto;
+      }
+    }
+  `;
+  static properties = {
+    variant: { type: String, reflect: true },
+    legend: { type: String },
+    disabled: { type: Boolean, reflect: true }
+  };
+  constructor() {
+    super();
+    this.variant = "horizontal";
+    this.legend = "";
+    this.disabled = false;
+  }
+  // Arrow-bound for stable identity (unused here but matches the
+  // bds-popover / bds-button conventions for handlers attached in render).
+  _onSlotChange = (e) => {
+    const slot = e.target;
+    const count = slot.assignedElements().length;
+    this.style.setProperty("--fieldGroup_field-count", String(count));
+  };
+  render() {
+    return T`
+      <fieldset ?disabled=${this.disabled}>
+        ${this.legend ? T`<legend class="legend">${this.legend}</legend>` : A}
+        <div class="fields">
+          <slot @slotchange=${this._onSlotChange}></slot>
+        </div>
+      </fieldset>
+    `;
+  }
+};
+customElements.define("bds-field-group", BdsFieldGroup);
+
 // src/web-components/interaction/form/bds-form-input.ts
 var BdsFormInput = class extends i2 {
   static formAssociated = true;
@@ -1118,6 +1233,7 @@ var BdsFormInput = class extends i2 {
 
     .message--hint {
       color: var(--bds-color_on-bg--subtle);
+      font-style: italic;
     }
   `;
   static properties = {
@@ -2068,6 +2184,7 @@ export {
   BdsDrawer,
   BdsDropdownMenu,
   BdsDropdownMenuItem,
+  BdsFieldGroup,
   BdsFileInput,
   BdsFormInput,
   BdsGrid,

package/dist/web-components/interaction/bds-button.js

@@ -1,6 +1,6 @@
 import {
   BdsButton
-} from "../chunk-N3TN6WCH.js";
+} from "../chunk-GER5UJOF.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsButton

package/dist/web-components/ui/bds-alert.js

@@ -1,6 +1,6 @@
 import {
   BdsAlert
-} from "../chunk-BX3IPVOB.js";
+} from "../chunk-ZNKEZIYE.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsAlert

package/dist/web-components/ui/bds-badge.js

@@ -1,6 +1,6 @@
 import {
   BdsBadge
-} from "../chunk-OHUTLSIQ.js";
+} from "../chunk-QWPACK5L.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsBadge

package/dist/web-components/ui/bds-card.js

@@ -1,6 +1,6 @@
 import {
   BdsCard
-} from "../chunk-YRXCVKHV.js";
+} from "../chunk-RTOS7LLG.js";
 import "../chunk-LGEZYFUU.js";
 export {
   BdsCard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",
@@ -335,5 +335,6 @@
   ],
   "dependencies": {
     "@oddbird/css-anchor-positioning": "^0.9.0"
-  }
+  },
+  "packageManager": "pnpm@11.0.8"
 }

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

@@ -95,35 +95,109 @@ Provide `href` to render as an `<a>` with button styling. `disabled` on a link s
 
 ## CSS variables
 
+The override surface is **layered** — pick the level of specificity you need. Every public token cascades through any ancestor, so you can theme one button, a section, or the whole app from the same selector.
+
+### Quick theme — set two tokens
+
+For most re-themes, the **identity tokens** are all you need. They drive both variants at rest, plus outline-hover.
+
+```css
+.brand-buttons {
+  --button_color:    var(--color_viviq-green);
+  --button_on-color: var(--color_on-viviq-green);
+}
+```
+
+What that gets you, automatically:
+
+| State | Default variant | Outline variant |
+| --- | --- | --- |
+| Resting | bg = `--button_color`, text = `--button_on-color` | bg = transparent, text/border = `--button_color--on-bg` |
+| Hover | bg = page surface, text = `--bds-color_interactive_on-bg` | bg = `--button_color`, text = `--button_on-color` |
+
+Outline-resting still uses the **text-safe** `--button_color--on-bg` (a darker-on-light-bg variant) by default — so dark-on-light readability stays intact even when your identity colour is bright. To make the identity colour itself flow through outline-resting, set `--button_color--on-bg` too:
+
+```css
+.brand-buttons {
+  --button_color:        var(--color_viviq-green);
+  --button_on-color:     var(--color_on-viviq-green);
+  --button_color--on-bg: var(--color_viviq-green); /* outline-resting follows */
+}
+```
+
+### Full token surface
+
+Every public token below can be set on the button or any ancestor — the consumer-set value always wins over variant + state defaults. Tokens are grouped by **state × variant** so the symmetry is visible.
+
+#### Identity & geometry
+
 <table>
 <thead>
 <tr><th>Variable</th><th>Default</th><th>Description</th></tr>
 </thead>
 <tbody>
-<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_color`</td><td>`var(--bds-color_interactive)`</td><td>Identity colour. Fills default-resting; flows through outline-hover.</td></tr>
+<tr><td>`--button_on-color`</td><td>`var(--bds-color_on-interactive)`</td><td>Text/icon colour on default-resting. Flows through outline-hover.</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-resting text + border.</td></tr>
+<tr><td>`--button_pulse-color`</td><td>`var(--button_color)`</td><td>Halo colour for the pulse animation.</td></tr>
 <tr><td>`--button_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Button border radius.</td></tr>
 <tr><td>`--button_height`</td><td>`3em` (medium)</td><td>Button height. Also drives the width when `isIconOnly` is set.</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>
-<tr><td>`--button_pulse-color`</td><td>`var(--button_color)`</td><td>Halo colour for the pulse animation.</td></tr>
+<tr><td>`--button_font-size`</td><td>`inherit` (medium)</td><td>Button font size.</td></tr>
+</tbody>
+</table>
+
+#### Default variant
+
+<table>
+<thead>
+<tr><th>State</th><th>Variable</th><th>Default</th></tr>
+</thead>
+<tbody>
+<tr><td rowspan="3">Resting</td><td>`--button_bg`</td><td>`var(--button_color)`</td></tr>
+<tr><td>`--button_text`</td><td>`var(--button_on-color)`</td></tr>
+<tr><td>`--button_border`</td><td>`transparent`</td></tr>
+<tr><td rowspan="4">Hover</td><td>`--button_bg--hover`</td><td>`var(--bds-color_bg)`</td></tr>
+<tr><td>`--button_text--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td></tr>
+<tr><td>`--button_border--hover`</td><td>`currentcolor`</td></tr>
+<tr><td>`--button_pulse-color--hover`</td><td>`var(--bds-color_interactive_on-bg)`</td></tr>
 </tbody>
 </table>
 
-### Re-theming
+#### Outline variant
 
-Change the two identity custom properties to re-theme both variants at once:
+<table>
+<thead>
+<tr><th>State</th><th>Variable</th><th>Default</th></tr>
+</thead>
+<tbody>
+<tr><td rowspan="3">Resting</td><td>`--button_bg--outline`</td><td>`transparent`</td></tr>
+<tr><td>`--button_text--outline`</td><td>`var(--button_color--on-bg)`</td></tr>
+<tr><td>`--button_border--outline`</td><td>`var(--button_color--on-bg)`</td></tr>
+<tr><td rowspan="3">Hover</td><td>`--button_bg--outline-hover`</td><td>`var(--button_color)`</td></tr>
+<tr><td>`--button_text--outline-hover`</td><td>`var(--button_on-color)`</td></tr>
+<tr><td>`--button_border--outline-hover`</td><td>`transparent`</td></tr>
+</tbody>
+</table>
+
+### Worked example: brand re-theme with one fine-grained tweak
+
+Most consumers stop at the quick-theme. If you need to override one specific state — for example, you want default-hover to stay branded instead of fading to the page surface — drop a state-specific override alongside the identity tokens:
 
 ```css
-.danger-zone .button {
-  --button_color:    var(--bds-color_error);
-  --button_on-color: var(--bds-color_on-error);
+.brand-buttons {
+  /* Identity — themes both variants at rest, plus outline-hover */
+  --button_color:        var(--color_viviq-green);
+  --button_on-color:     var(--color_on-viviq-green);
+  --button_color--on-bg: var(--color_viviq-green);
+
+  /* One fine-grained override: keep default-hover on-brand instead of fading */
+  --button_bg--hover:    var(--color_viviq-green--dark);
+  --button_text--hover:  var(--color_on-viviq-green);
 }
 ```
 
+Outline-hover, default-resting, and outline-resting all derive from the identity tokens — you only spell out the override that diverges.
+
 ## Accessibility
 
 - Always provide children **or** `aria-label` — icon-only buttons without an accessible name are a WCAG failure.