@helixui/library 3.2.0-next.102 → 3.2.0-next.110

package/custom-elements.json

@@ -2826,7 +2826,7 @@
           "name": "HelixButton",
           "cssProperties": [
             {
-              "description": "Button background color (3.2.1 cascade — variant rules route through action.{primary,secondary,ghost,danger}.bg).",
+              "description": "Button background color. **Variant-shadowed**: every `.button--{variant}` rule rebinds this property at descendant scope, so a host-level override (`style=\"--hx-button-bg: …\"` or `:host`-targeting CSS) does not reach paint for primary/secondary/tertiary/danger/ghost/outline buttons. To recolor a variant fill, override the upstream semantic instead — e.g. `--hx-color-action-primary-bg` (light primary), `--hx-color-action-primary-bg-inverted-rest` (inverted primary), `--hx-color-action-danger-bg` (danger), or the inverted overlay tokens for tertiary/secondary/ghost/outline. The `--hx-button-bg` hook still works for the rare case of an unstyled base button without a `variant` class, and is internally rebound by the variant rules to participate in the active/hover override chain.",
               "name": "--hx-button-bg",
               "default": "var(--hx-color-action-primary-bg)"
             },
@@ -2984,6 +2984,14 @@
             {
               "description": "Inverted-secondary/outline border + inverted focus-visible outline (overlay-white-70 ≈ 5:1 — clears WCAG 1.4.11 3:1 floor).",
               "name": "--hx-color-border-on-dark-strong"
+            },
+            {
+              "description": "DEPRECATED 3.2.2; renamed to --hx-color-surface-on-dark-overlay-subtle (the value paints a translucent fill, not a border). Consume sites read both names via deprecated-first fallback so existing overrides keep working until removal in 4.0.0.",
+              "name": "--hx-color-border-on-dark-subtle"
+            },
+            {
+              "description": "DEPRECATED 3.2.2; renamed to --hx-color-surface-on-dark-overlay-default (the value paints a translucent fill, not a border). Consume sites read both names via deprecated-first fallback so existing overrides keep working until removal in 4.0.0.",
+              "name": "--hx-color-border-on-dark-default"
             }
           ],
           "cssParts": [
@@ -23043,6 +23051,10 @@
             {
               "description": "Toggle button hover surface (overlay-white-10 primitive — translucent fill, not a border).",
               "name": "--hx-color-surface-on-dark-overlay-subtle"
+            },
+            {
+              "description": "DEPRECATED 3.2.2; renamed to --hx-color-surface-on-dark-overlay-subtle (the value paints a translucent fill, not a border). Toggle-hover rule reads both names via deprecated-first fallback so existing overrides keep working until removal in 4.0.0.",
+              "name": "--hx-color-border-on-dark-subtle"
             }
           ],
           "cssParts": [
@@ -31020,7 +31032,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "The registered brand name to apply on top of the base theme.\nWhen set, brand-specific CSS custom property overrides are merged\nafter the base theme tokens in the adopted stylesheet, enabling\nhospital system white-label implementations.\n\nThe brand must first be registered via `HelixBrandRegistry.register()`.\nIf the brand name is non-empty but not registered, a warning is logged\nand the base theme is applied without brand overrides.",
+              "description": "The registered brand name to apply on top of the base theme.\nWhen set, brand-specific CSS custom property overrides are merged\nafter the base theme tokens in the adopted stylesheet, enabling\nhospital system white-label implementations.\n\nThe brand must first be registered via `HelixBrandRegistry.register()`.\nIf the brand name is non-empty but not registered, a warning is logged\nand the base theme is applied without brand overrides.\n\n**High-contrast suppression:** When `theme=\"high-contrast\"`, the brand\nmerge is intentionally skipped to preserve the WCAG 1.4.6 Enhanced\nContrast (7:1+) guarantee that the HC token set is tuned for. A\nregistered brand applied under HC emits a `console.info` to surface\nthe suppression in development. Brand merging on `light` and `dark`\nis unaffected. See `BRAND_THEMING.md`.",
               "attribute": "brand",
               "reflects": true
             },
@@ -31050,9 +31062,9 @@
               "kind": "field",
               "name": "effectiveTheme",
               "type": {
-                "text": "'light' | 'dark' | 'high-contrast' | 'auto'"
+                "text": "'light' | 'dark' | 'high-contrast'"
               },
-              "description": "Returns the currently active theme name.\nWhen `system=true` or `theme=\"auto\"`, reflects the OS preference (`\"light\"` or `\"dark\"`).\nOtherwise returns the `theme` property value.",
+              "description": "Returns the currently active theme name.\nWhen `theme=\"auto\"`, reflects the OS preference (`\"light\"` or `\"dark\"`).\nOtherwise returns the `theme` property value.",
               "readonly": true
             },
             {
@@ -31082,7 +31094,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "The registered brand name to apply on top of the base theme.\nWhen set, brand-specific CSS custom property overrides are merged\nafter the base theme tokens in the adopted stylesheet, enabling\nhospital system white-label implementations.\n\nThe brand must first be registered via `HelixBrandRegistry.register()`.\nIf the brand name is non-empty but not registered, a warning is logged\nand the base theme is applied without brand overrides.",
+              "description": "The registered brand name to apply on top of the base theme.\nWhen set, brand-specific CSS custom property overrides are merged\nafter the base theme tokens in the adopted stylesheet, enabling\nhospital system white-label implementations.\n\nThe brand must first be registered via `HelixBrandRegistry.register()`.\nIf the brand name is non-empty but not registered, a warning is logged\nand the base theme is applied without brand overrides.\n\n**High-contrast suppression:** When `theme=\"high-contrast\"`, the brand\nmerge is intentionally skipped to preserve the WCAG 1.4.6 Enhanced\nContrast (7:1+) guarantee that the HC token set is tuned for. A\nregistered brand applied under HC emits a `console.info` to surface\nthe suppression in development. Brand merging on `light` and `dark`\nis unaffected. See `BRAND_THEMING.md`.",
               "fieldName": "brand",
               "attribute": "brand"
             },

package/dist/components/hx-button/hx-button.d.ts

@@ -27,7 +27,7 @@ declare const HelixButton_base: typeof HelixElement;
  * @csspart suffix - The suffix slot container span.
  * @csspart spinner - The loading spinner SVG element.
  *
- * @cssprop [--hx-button-bg=var(--hx-color-action-primary-bg)] - Button background color (3.2.1 cascade — variant rules route through action.{primary,secondary,ghost,danger}.bg).
+ * @cssprop [--hx-button-bg=var(--hx-color-action-primary-bg)] - Button background color. **Variant-shadowed**: every `.button--{variant}` rule rebinds this property at descendant scope, so a host-level override (`style="--hx-button-bg: …"` or `:host`-targeting CSS) does not reach paint for primary/secondary/tertiary/danger/ghost/outline buttons. To recolor a variant fill, override the upstream semantic instead — e.g. `--hx-color-action-primary-bg` (light primary), `--hx-color-action-primary-bg-inverted-rest` (inverted primary), `--hx-color-action-danger-bg` (danger), or the inverted overlay tokens for tertiary/secondary/ghost/outline. The `--hx-button-bg` hook still works for the rare case of an unstyled base button without a `variant` class, and is internally rebound by the variant rules to participate in the active/hover override chain.
  * @cssprop [--hx-button-hover-bg] - Hover background override (primary and danger variants only). Other variants (secondary/outline, ghost) keep their hover fills routed through their semantic action.* tokens and do not consume this hook. Under [inverted] for primary/danger, hover and active share a paint (combined :hover, :active rule), so this override applies to both states unless --hx-button-active-bg also takes precedence.
  * @cssprop [--hx-button-active-bg] - Pressed/active background override (primary and danger variants only, including their inverted modes). Takes precedence over --hx-button-hover-bg in the fallback chain. Standard-mode primary/danger default to action.{primary,danger}.bg-active (with filter:none) for AA-pinned pressed contrast. Inverted-mode primary/danger reuse action.{primary,danger}.bg-inverted-hover (combined :hover, :active rule); setting --hx-button-active-bg under [inverted] therefore overrides the lifted hover fill as well as the pressed fill — the two share a paint in inverted mode. Other variants do not consume this hook.
  * @cssprop [--hx-button-color=var(--hx-color-text-on-primary)] - Button text color (variants route through text.on-{role} / text.on-{role}-strong).
@@ -66,6 +66,8 @@ declare const HelixButton_base: typeof HelixElement;
  * @cssprop [--hx-color-surface-on-dark-overlay-subtle] - Inverted-tertiary resting fill (overlay-white-10 — translucent fill, not a border).
  * @cssprop [--hx-color-surface-on-dark-overlay-default] - Inverted-tertiary hover fill + inverted-secondary/ghost/outline hover fill (overlay-white-30 — translucent fill, not a border).
  * @cssprop [--hx-color-border-on-dark-strong] - Inverted-secondary/outline border + inverted focus-visible outline (overlay-white-70 ≈ 5:1 — clears WCAG 1.4.11 3:1 floor).
+ * @cssprop [--hx-color-border-on-dark-subtle] - DEPRECATED 3.2.2; renamed to --hx-color-surface-on-dark-overlay-subtle (the value paints a translucent fill, not a border). Consume sites read both names via deprecated-first fallback so existing overrides keep working until removal in 4.0.0.
+ * @cssprop [--hx-color-border-on-dark-default] - DEPRECATED 3.2.2; renamed to --hx-color-surface-on-dark-overlay-default (the value paints a translucent fill, not a border). Consume sites read both names via deprecated-first fallback so existing overrides keep working until removal in 4.0.0.
  */
 export declare class HelixButton extends HelixButton_base {
     static styles: import('lit').CSSResult[];

package/dist/components/hx-button/hx-button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-button.d.ts","sourceRoot":"","sources":["../../../src/components/hx-button/hx-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAC9E,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,UAAU,CAAC;CAC3B;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBACa,WAAY,SAAQ,gBAAgC;IAM/D,OAAgB,MAAM,4BAAuB;IAI7C,gBAAgB;IAChB,OAAgB,cAAc,UAAQ;IAItC;;;OAGG;IAEH,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAa;IAE3F;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;;OAIG;IAEH,OAAO,UAAS;IAEhB;;;OAGG;IAEH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE/C;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAa;IAEvC;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAEtC;;;;OAIG;IAEH,IAAI,UAAS;IAEb;;;;;;;;;;;;;;OAcG;IAEH,QAAQ,UAAS;IAEjB;;;;;;;;OAQG;IAEH,eAAe,EAAE,MAAM,CAAM;IAE7B;;;;OAIG;IACH,OAAO,KAAK,eAAe,GAE1B;cAIkB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAM3D,gBAAgB;IAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAO5B;IAGX,OAAO,CAAC,qBAAqB,CAAS;IAE7B,YAAY,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAe3D,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAgB/D,gBAAgB;IAChB,OAAO,CAAC,wBAAwB;IAoBhC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAgCpB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA6BtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAiBX,MAAM;CAyChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,WAAW,CAAC;KAC1B;IACD,UAAU,mBAAmB;QAC3B,UAAU,EAAE,WAAW,CAAC;YAAE,aAAa,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC;KACxD;CACF"}
+{"version":3,"file":"hx-button.d.ts","sourceRoot":"","sources":["../../../src/components/hx-button/hx-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAC9E,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,UAAU,CAAC;CAC3B;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,qBACa,WAAY,SAAQ,gBAAgC;IAM/D,OAAgB,MAAM,4BAAuB;IAI7C,gBAAgB;IAChB,OAAgB,cAAc,UAAQ;IAItC;;;OAGG;IAEH,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAa;IAE3F;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;;OAIG;IAEH,OAAO,UAAS;IAEhB;;;OAGG;IAEH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE/C;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAa;IAEvC;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAEtC;;;;OAIG;IAEH,IAAI,UAAS;IAEb;;;;;;;;;;;;;;OAcG;IAEH,QAAQ,UAAS;IAEjB;;;;;;;;OAQG;IAEH,eAAe,EAAE,MAAM,CAAM;IAE7B;;;;OAIG;IACH,OAAO,KAAK,eAAe,GAE1B;cAIkB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAM3D,gBAAgB;IAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAO5B;IAGX,OAAO,CAAC,qBAAqB,CAAS;IAE7B,YAAY,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAe3D,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAgB/D,gBAAgB;IAChB,OAAO,CAAC,wBAAwB;IAoBhC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAgCpB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA6BtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAiBX,MAAM;CAyChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,WAAW,CAAC;KAC1B;IACD,UAAU,mBAAmB;QAC3B,UAAU,EAAE,WAAW,CAAC;YAAE,aAAa,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC;KACxD;CACF"}

package/dist/components/hx-button/hx-button.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-button.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-button/hx-button.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,yBAqa7B,CAAC"}
+{"version":3,"file":"hx-button.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-button/hx-button.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,yBAic7B,CAAC"}

package/dist/components/hx-button/index.js

@@ -1,4 +1,4 @@
-import { H as e } from "../../shared/hx-button-CHlkRQTe.js";
+import { H as e } from "../../shared/hx-button-DPY6SPVT.js";
 export {
   e as HelixButton
 };

package/dist/components/hx-side-nav/hx-side-nav.d.ts

@@ -34,6 +34,7 @@ import { HelixElement } from '../../base/index.js';
  * @cssprop [--hx-color-text-inverse] - Side-nav text color (resolves to neutral-0).
  * @cssprop [--hx-color-border-on-dark-strong] - Container/header/footer divider border (overlay-white-70 light, overlay-black-50 dark — sized for visibility on the mode-flipped surface-inverse).
  * @cssprop [--hx-color-surface-on-dark-overlay-subtle] - Toggle button hover surface (overlay-white-10 primitive — translucent fill, not a border).
+ * @cssprop [--hx-color-border-on-dark-subtle] - DEPRECATED 3.2.2; renamed to --hx-color-surface-on-dark-overlay-subtle (the value paints a translucent fill, not a border). Toggle-hover rule reads both names via deprecated-first fallback so existing overrides keep working until removal in 4.0.0.
  */
 export declare class HelixSideNav extends HelixElement {
     static styles: import('lit').CSSResult[];

package/dist/components/hx-side-nav/hx-side-nav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-side-nav.d.ts","sourceRoot":"","sources":["../../../src/components/hx-side-nav/hx-side-nav.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAChD,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBACa,YAAa,SAAQ,YAAY;IAI5C,OAAgB,MAAM,4BAAwB;IAI9C;;;OAGG;IAEH,SAAS,UAAS;IAElB;;;OAGG;IAEH,KAAK,SAAqB;IAIjB,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAS/D;;;;OAIG;IACH,gBAAgB;IAChB,OAAO,CAAC,6BAA6B;IAkBrC;;;OAGG;IACH,gBAAgB;IAChB,OAAO,CAAC,oBAAoB;IAM5B;;;;;OAKG;IACH,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAgItB,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAgCrB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAQhB,MAAM;CA0BhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,aAAa,EAAE,YAAY,CAAC;KAC7B;CACF;AAED,YAAY,EAAE,YAAY,IAAI,SAAS,EAAE,CAAC"}
+{"version":3,"file":"hx-side-nav.d.ts","sourceRoot":"","sources":["../../../src/components/hx-side-nav/hx-side-nav.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAChD,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBACa,YAAa,SAAQ,YAAY;IAI5C,OAAgB,MAAM,4BAAwB;IAI9C;;;OAGG;IAEH,SAAS,UAAS;IAElB;;;OAGG;IAEH,KAAK,SAAqB;IAIjB,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAS/D;;;;OAIG;IACH,gBAAgB;IAChB,OAAO,CAAC,6BAA6B;IAkBrC;;;OAGG;IACH,gBAAgB;IAChB,OAAO,CAAC,oBAAoB;IAM5B;;;;;OAKG;IACH,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAgItB,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAgCrB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAQhB,MAAM;CA0BhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,aAAa,EAAE,YAAY,CAAC;KAC7B;CACF;AAED,YAAY,EAAE,YAAY,IAAI,SAAS,EAAE,CAAC"}

package/dist/components/hx-side-nav/hx-side-nav.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-side-nav.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-side-nav/hx-side-nav.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB,yBAgM9B,CAAC"}
+{"version":3,"file":"hx-side-nav.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-side-nav/hx-side-nav.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB,yBA4M9B,CAAC"}

package/dist/components/hx-side-nav/index.js

@@ -1,4 +1,4 @@
-import { H as i, a as x } from "../../shared/hx-nav-item-Dap3DYgB.js";
+import { H as i, a as x } from "../../shared/hx-nav-item-xqRPOCWX.js";
 export {
   i as HelixNavItem,
   x as HelixSideNav

package/dist/components/hx-theme/hx-theme.d.ts

@@ -101,6 +101,13 @@ export declare class HelixTheme extends HelixElement {
      * If the brand name is non-empty but not registered, a warning is logged
      * and the base theme is applied without brand overrides.
      *
+     * **High-contrast suppression:** When `theme="high-contrast"`, the brand
+     * merge is intentionally skipped to preserve the WCAG 1.4.6 Enhanced
+     * Contrast (7:1+) guarantee that the HC token set is tuned for. A
+     * registered brand applied under HC emits a `console.info` to surface
+     * the suppression in development. Brand merging on `light` and `dark`
+     * is unaffected. See `BRAND_THEMING.md`.
+     *
      * @attr brand
      * @example
      * ```html
@@ -143,15 +150,20 @@ export declare class HelixTheme extends HelixElement {
     private _motionQuery;
     /** @internal */
     private _motionHandler;
+    /** @internal — last `${brand}|${effectiveTheme}|${kind}` for which a brand
+     * suppression info / unregistered warn was emitted. `_applyEffectiveTheme()`
+     * runs on every relevant property change, so without this guard the message
+     * fires once per `update()` tick rather than once per applied state. */
+    private _lastBrandAdvisoryKey;
     firstUpdated(changed: PropertyValues<this>): void;
     updated(changed: PropertyValues<this>): void;
     disconnectedCallback(): void;
     /**
      * Returns the currently active theme name.
-     * When `system=true` or `theme="auto"`, reflects the OS preference (`"light"` or `"dark"`).
+     * When `theme="auto"`, reflects the OS preference (`"light"` or `"dark"`).
      * Otherwise returns the `theme` property value.
      */
-    get effectiveTheme(): 'light' | 'dark' | 'high-contrast' | 'auto';
+    get effectiveTheme(): 'light' | 'dark' | 'high-contrast';
     /**
      * Returns the resolved motion level after considering the `motion` attribute and OS preference.
      * When `motion="full"` and the OS reports `prefers-reduced-motion: reduce`, returns `"reduced"`.

package/dist/components/hx-theme/hx-theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-theme.d.ts","sourceRoot":"","sources":["../../../src/components/hx-theme/hx-theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAChD,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,eAAe,GAAG,MAAM,CAAC;AAqLpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBACa,UAAW,SAAQ,YAAY;IAC1C,OAAgB,MAAM,4BAAsB;IAE5C;;;;;;;OAOG;IAEH,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,eAAe,GAAG,MAAM,CAAW;IAK7D;;;;;;;;;;;;;;;;;OAiBG;IAEH,KAAK,SAAM;IAEX;;;;;;;;;;;OAWG;IAEH,MAAM,EAAE,UAAU,CAAU;IAE5B;;;;;;OAMG;IAEH,OAAO,EAAE,WAAW,CAAiB;IAErC,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAA+B;IAClD,gBAAgB;IAChB,OAAO,CAAC,aAAa,CAA6B;IAClD,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAA8B;IACjD,gBAAgB;IAChB,OAAO,CAAC,aAAa,CAA8B;IACnD,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAA+B;IACnD,gBAAgB;IAChB,OAAO,CAAC,cAAc,CAA6B;IAE1C,YAAY,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAWjD,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IA2B5C,oBAAoB,IAAI,IAAI;IAMrC;;;;OAIG;IACH,IAAI,cAAc,IAAI,OAAO,GAAG,MAAM,GAAG,eAAe,GAAG,MAAM,CAMhE;IAED;;;;OAIG;IACH,IAAI,eAAe,IAAI,MAAM,GAAG,SAAS,CASxC;IAED,gBAAgB;IAChB,OAAO,CAAC,eAAe;IAcvB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAUzB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAQzB,+EAA+E;IAC/E,OAAO,CAAC,kBAAkB;IAS1B,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAQ1B,+EAA+E;IAC/E,OAAO,CAAC,oBAAoB;IAO5B,gBAAgB;IAChB,OAAO,CAAC,oBAAoB;IAyB5B,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAcZ,MAAM;CAQhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,UAAU,CAAC;KACxB;CACF;AAED,6FAA6F;AAC7F,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC"}
+{"version":3,"file":"hx-theme.d.ts","sourceRoot":"","sources":["../../../src/components/hx-theme/hx-theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAChD,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAUnD,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,eAAe,GAAG,MAAM,CAAC;AA+HpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBACa,UAAW,SAAQ,YAAY;IAC1C,OAAgB,MAAM,4BAAsB;IAE5C;;;;;;;OAOG;IAEH,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,eAAe,GAAG,MAAM,CAAW;IAK7D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IAEH,KAAK,SAAM;IAEX;;;;;;;;;;;OAWG;IAEH,MAAM,EAAE,UAAU,CAAU;IAE5B;;;;;;OAMG;IAEH,OAAO,EAAE,WAAW,CAAiB;IAErC,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAA+B;IAClD,gBAAgB;IAChB,OAAO,CAAC,aAAa,CAA6B;IAClD,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAA8B;IACjD,gBAAgB;IAChB,OAAO,CAAC,aAAa,CAA8B;IACnD,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAA+B;IACnD,gBAAgB;IAChB,OAAO,CAAC,cAAc,CAA6B;IACnD;;;4EAGwE;IACxE,OAAO,CAAC,qBAAqB,CAAuB;IAE3C,YAAY,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAWjD,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IA2B5C,oBAAoB,IAAI,IAAI;IAMrC;;;;OAIG;IACH,IAAI,cAAc,IAAI,OAAO,GAAG,MAAM,GAAG,eAAe,CAMvD;IAED;;;;OAIG;IACH,IAAI,eAAe,IAAI,MAAM,GAAG,SAAS,CASxC;IAED,gBAAgB;IAChB,OAAO,CAAC,eAAe;IAcvB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAUzB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAQzB,+EAA+E;IAC/E,OAAO,CAAC,kBAAkB;IAS1B,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAQ1B,+EAA+E;IAC/E,OAAO,CAAC,oBAAoB;IAO5B,gBAAgB;IAChB,OAAO,CAAC,oBAAoB;IAgE5B,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAcZ,MAAM;CAQhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,UAAU,CAAC;KACxB;CACF;AAED,6FAA6F;AAC7F,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC"}

package/dist/components/hx-theme/index.js

@@ -1,4 +1,4 @@
-import { H as o } from "../../shared/hx-theme-BiyQ7UUK.js";
+import { H as o } from "../../shared/hx-theme-BsefFWTO.js";
 export {
   o as HelixTheme
 };

package/dist/css/helix-all.css

@@ -1289,8 +1289,16 @@
      so dark mode can flip the fill to primary-600. surface.inverse becomes light
      (#EBEEE9) in dark mode; primary-500 on #EBEEE9 = 2.94:1 (sub-3:1 UI floor
      fail for the inverted-button boundary). primary-600 on #EBEEE9 = 4.97:1
-     (AA pass). Light mode tracks action.primary.bg (primary-500, 5.20:1 on
-     dark surface.inverse). */
+     (AA pass). Light mode tracks action.primary.bg-inverted-rest's base value
+     (primary-500, 5.20:1 on dark surface.inverse).
+
+     Override path note (codex round-11): this binds --hx-button-bg directly,
+     matching the cascade convention every other .button--{variant} rule uses
+     (light primary at line 89, danger at 120, secondary, tertiary, ghost). The
+     consumer override path for inverted-primary rest is
+     --hx-color-action-primary-bg-inverted-rest, NOT --hx-button-bg — the same
+     pattern as light primary (consumers override --hx-color-action-primary-bg).
+     Pinned by dark-mode-resolution.test.ts:185-197 across both modes. */
   :host([inverted]) .button--primary {
     --hx-button-bg: var(--hx-color-action-primary-bg-inverted-rest, #429797);
   }
@@ -1342,20 +1350,34 @@
     --hx-button-border-color: var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7));
   }
 
+  /* Inverted overlay fills read both names so consumer overrides reach paint
+     regardless of which token they target: the deprecated --hx-color-border-on-dark-*
+     names (3.2.0/3.2.1 public API, scheduled for removal in 4.0.0) and the canonical
+     --hx-color-surface-on-dark-overlay-* names (round-8 rename). Deprecated name
+     wins when set; otherwise resolves through the canonical alias chain. */
   :host([inverted]) .button--secondary:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* Tertiary inverted — resting at the subtle overlay (10%) lifts to the default
      overlay (30%) on hover so the runtime hover delta is visually distinct, not
      collapsed onto a single token. */
   :host([inverted]) .button--tertiary {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-subtle,
+      var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1))
+    );
     --hx-button-border-color: transparent;
   }
 
   :host([inverted]) .button--tertiary:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* Ghost inverted — transparent base, translucent hover bg */
@@ -1367,7 +1389,10 @@
   :host([inverted]) .button--ghost:hover {
     --hx-button-bg: var(
       --hx-button-inverted-ghost-hover-bg,
-      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+      var(
+        --hx-color-border-on-dark-default,
+        var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+      )
     );
   }
 
@@ -1377,7 +1402,10 @@
   }
 
   :host([inverted]) .button--outline:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* ─── Prefix / Suffix / Label ─── */
@@ -8740,16 +8768,28 @@ export const helixGridItemStyles = css`
   }
 
   .side-nav__toggle:hover {
+    /* Read both deprecated --hx-color-border-on-dark-subtle (3.2.0/3.2.1 API)
+       and canonical --hx-color-surface-on-dark-overlay-subtle so consumer
+       overrides on either name reach paint. Deprecated removal: 4.0.0.
+       Hex fallback for browsers without color-mix(). */
     background-color: var(
-      --hx-color-surface-on-dark-overlay-subtle,
-      rgba(255, 255, 255, 0.1)
-    ); /* fallback for browsers without color-mix() */
+      --hx-color-border-on-dark-subtle,
+      var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1))
+    );
     color: var(--hx-side-nav-toggle-hover-color, var(--hx-color-text-inverse, #ffffff));
   }
 
   @supports (color: color-mix(in srgb, red 50%, blue)) {
+    /* Fold color-mix() into the same deprecated-first chain so consumer
+       overrides on either token reach paint on the modern path too. */
     .side-nav__toggle:hover {
-      background-color: color-mix(in srgb, currentColor 15%, transparent);
+      background-color: var(
+        --hx-color-border-on-dark-subtle,
+        var(
+          --hx-color-surface-on-dark-overlay-subtle,
+          color-mix(in srgb, currentColor 15%, transparent)
+        )
+      );
     }
   }
 

package/dist/css/helix-core.css

@@ -621,8 +621,16 @@
      so dark mode can flip the fill to primary-600. surface.inverse becomes light
      (#EBEEE9) in dark mode; primary-500 on #EBEEE9 = 2.94:1 (sub-3:1 UI floor
      fail for the inverted-button boundary). primary-600 on #EBEEE9 = 4.97:1
-     (AA pass). Light mode tracks action.primary.bg (primary-500, 5.20:1 on
-     dark surface.inverse). */
+     (AA pass). Light mode tracks action.primary.bg-inverted-rest's base value
+     (primary-500, 5.20:1 on dark surface.inverse).
+
+     Override path note (codex round-11): this binds --hx-button-bg directly,
+     matching the cascade convention every other .button--{variant} rule uses
+     (light primary at line 89, danger at 120, secondary, tertiary, ghost). The
+     consumer override path for inverted-primary rest is
+     --hx-color-action-primary-bg-inverted-rest, NOT --hx-button-bg — the same
+     pattern as light primary (consumers override --hx-color-action-primary-bg).
+     Pinned by dark-mode-resolution.test.ts:185-197 across both modes. */
   :host([inverted]) .button--primary {
     --hx-button-bg: var(--hx-color-action-primary-bg-inverted-rest, #429797);
   }
@@ -674,20 +682,34 @@
     --hx-button-border-color: var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7));
   }
 
+  /* Inverted overlay fills read both names so consumer overrides reach paint
+     regardless of which token they target: the deprecated --hx-color-border-on-dark-*
+     names (3.2.0/3.2.1 public API, scheduled for removal in 4.0.0) and the canonical
+     --hx-color-surface-on-dark-overlay-* names (round-8 rename). Deprecated name
+     wins when set; otherwise resolves through the canonical alias chain. */
   :host([inverted]) .button--secondary:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* Tertiary inverted — resting at the subtle overlay (10%) lifts to the default
      overlay (30%) on hover so the runtime hover delta is visually distinct, not
      collapsed onto a single token. */
   :host([inverted]) .button--tertiary {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-subtle,
+      var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1))
+    );
     --hx-button-border-color: transparent;
   }
 
   :host([inverted]) .button--tertiary:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* Ghost inverted — transparent base, translucent hover bg */
@@ -699,7 +721,10 @@
   :host([inverted]) .button--ghost:hover {
     --hx-button-bg: var(
       --hx-button-inverted-ghost-hover-bg,
-      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+      var(
+        --hx-color-border-on-dark-default,
+        var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+      )
     );
   }
 
@@ -709,7 +734,10 @@
   }
 
   :host([inverted]) .button--outline:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* ─── Prefix / Suffix / Label ─── */

package/dist/css/helix-navigation.css

@@ -825,16 +825,28 @@
   }
 
   .side-nav__toggle:hover {
+    /* Read both deprecated --hx-color-border-on-dark-subtle (3.2.0/3.2.1 API)
+       and canonical --hx-color-surface-on-dark-overlay-subtle so consumer
+       overrides on either name reach paint. Deprecated removal: 4.0.0.
+       Hex fallback for browsers without color-mix(). */
     background-color: var(
-      --hx-color-surface-on-dark-overlay-subtle,
-      rgba(255, 255, 255, 0.1)
-    ); /* fallback for browsers without color-mix() */
+      --hx-color-border-on-dark-subtle,
+      var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1))
+    );
     color: var(--hx-side-nav-toggle-hover-color, var(--hx-color-text-inverse, #ffffff));
   }
 
   @supports (color: color-mix(in srgb, red 50%, blue)) {
+    /* Fold color-mix() into the same deprecated-first chain so consumer
+       overrides on either token reach paint on the modern path too. */
     .side-nav__toggle:hover {
-      background-color: color-mix(in srgb, currentColor 15%, transparent);
+      background-color: var(
+        --hx-color-border-on-dark-subtle,
+        var(
+          --hx-color-surface-on-dark-overlay-subtle,
+          color-mix(in srgb, currentColor 15%, transparent)
+        )
+      );
     }
   }
 

package/dist/css/hx-button.css

@@ -272,8 +272,16 @@
      so dark mode can flip the fill to primary-600. surface.inverse becomes light
      (#EBEEE9) in dark mode; primary-500 on #EBEEE9 = 2.94:1 (sub-3:1 UI floor
      fail for the inverted-button boundary). primary-600 on #EBEEE9 = 4.97:1
-     (AA pass). Light mode tracks action.primary.bg (primary-500, 5.20:1 on
-     dark surface.inverse). */
+     (AA pass). Light mode tracks action.primary.bg-inverted-rest's base value
+     (primary-500, 5.20:1 on dark surface.inverse).
+
+     Override path note (codex round-11): this binds --hx-button-bg directly,
+     matching the cascade convention every other .button--{variant} rule uses
+     (light primary at line 89, danger at 120, secondary, tertiary, ghost). The
+     consumer override path for inverted-primary rest is
+     --hx-color-action-primary-bg-inverted-rest, NOT --hx-button-bg — the same
+     pattern as light primary (consumers override --hx-color-action-primary-bg).
+     Pinned by dark-mode-resolution.test.ts:185-197 across both modes. */
   :host([inverted]) .button--primary {
     --hx-button-bg: var(--hx-color-action-primary-bg-inverted-rest, #429797);
   }
@@ -325,20 +333,34 @@
     --hx-button-border-color: var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7));
   }
 
+  /* Inverted overlay fills read both names so consumer overrides reach paint
+     regardless of which token they target: the deprecated --hx-color-border-on-dark-*
+     names (3.2.0/3.2.1 public API, scheduled for removal in 4.0.0) and the canonical
+     --hx-color-surface-on-dark-overlay-* names (round-8 rename). Deprecated name
+     wins when set; otherwise resolves through the canonical alias chain. */
   :host([inverted]) .button--secondary:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* Tertiary inverted — resting at the subtle overlay (10%) lifts to the default
      overlay (30%) on hover so the runtime hover delta is visually distinct, not
      collapsed onto a single token. */
   :host([inverted]) .button--tertiary {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-subtle,
+      var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1))
+    );
     --hx-button-border-color: transparent;
   }
 
   :host([inverted]) .button--tertiary:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* Ghost inverted — transparent base, translucent hover bg */
@@ -350,7 +372,10 @@
   :host([inverted]) .button--ghost:hover {
     --hx-button-bg: var(
       --hx-button-inverted-ghost-hover-bg,
-      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+      var(
+        --hx-color-border-on-dark-default,
+        var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+      )
     );
   }
 
@@ -360,7 +385,10 @@
   }
 
   :host([inverted]) .button--outline:hover {
-    --hx-button-bg: var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3));
+    --hx-button-bg: var(
+      --hx-color-border-on-dark-default,
+      var(--hx-color-surface-on-dark-overlay-default, rgba(255, 255, 255, 0.3))
+    );
   }
 
   /* ─── Prefix / Suffix / Label ─── */

package/dist/css/hx-side-nav.css

@@ -112,16 +112,28 @@
   }
 
   .side-nav__toggle:hover {
+    /* Read both deprecated --hx-color-border-on-dark-subtle (3.2.0/3.2.1 API)
+       and canonical --hx-color-surface-on-dark-overlay-subtle so consumer
+       overrides on either name reach paint. Deprecated removal: 4.0.0.
+       Hex fallback for browsers without color-mix(). */
     background-color: var(
-      --hx-color-surface-on-dark-overlay-subtle,
-      rgba(255, 255, 255, 0.1)
-    ); /* fallback for browsers without color-mix() */
+      --hx-color-border-on-dark-subtle,
+      var(--hx-color-surface-on-dark-overlay-subtle, rgba(255, 255, 255, 0.1))
+    );
     color: var(--hx-side-nav-toggle-hover-color, var(--hx-color-text-inverse, #ffffff));
   }
 
   @supports (color: color-mix(in srgb, red 50%, blue)) {
+    /* Fold color-mix() into the same deprecated-first chain so consumer
+       overrides on either token reach paint on the modern path too. */
     .side-nav__toggle:hover {
-      background-color: color-mix(in srgb, currentColor 15%, transparent);
+      background-color: var(
+        --hx-color-border-on-dark-subtle,
+        var(
+          --hx-color-surface-on-dark-overlay-subtle,
+          color-mix(in srgb, currentColor 15%, transparent)
+        )
+      );
     }
   }
 

package/dist/css/index.css

@@ -1,4 +1,4 @@
-/* index.css — generated 2026-04-26T14:24:50.891Z */
+/* index.css — generated 2026-04-27T02:39:11.228Z */
 /* Imports all per-component CSS files for Drupal asset pipeline */
 
 @import './hx-accordion.css';

package/dist/css/manifest.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-04-26T14:24:50.890Z",
+  "generated": "2026-04-27T02:39:11.227Z",
   "components": [
     {
       "name": "hx-accordion",
@@ -1771,6 +1771,7 @@
         "--hx-border-width-thin",
         "--hx-color-border-on-dark-strong",
         "--hx-color-surface-inverse",
+        "--hx-color-surface-on-dark-overlay-subtle",
         "--hx-color-text-inverse",
         "--hx-focus-ring-color",
         "--hx-focus-ring-offset",

package/dist/index.js

@@ -6,7 +6,7 @@ import { H as v } from "./shared/hx-avatar-C9hOmlAb.js";
 import { H as E } from "./shared/hx-badge-CQXgOXJM.js";
 import { H as k } from "./shared/hx-banner-D3DzpfcP.js";
 import { H as B, a as P } from "./shared/hx-breadcrumb-item-3tKppF9h.js";
-import { H as M } from "./shared/hx-button-CHlkRQTe.js";
+import { H as M } from "./shared/hx-button-DPY6SPVT.js";
 import { H as N } from "./shared/hx-button-group-BI-QBqmO.js";
 import { H as A } from "./shared/hx-card-qNAM2QNV.js";
 import { H as G, a as U } from "./shared/hx-carousel-item-z1Lc24op.js";
@@ -53,7 +53,7 @@ import { H as So } from "./shared/hx-prose-BThYcASV.js";
 import { H as To, a as bo } from "./shared/hx-radio-CJvNU2yP.js";
 import { H as go } from "./shared/hx-rating-C3QP53k9.js";
 import { H as vo } from "./shared/hx-select-C8fEHQhC.js";
-import { H as Eo, a as Do } from "./shared/hx-nav-item-Dap3DYgB.js";
+import { H as Eo, a as Do } from "./shared/hx-nav-item-xqRPOCWX.js";
 import { H as wo } from "./shared/hx-skeleton-Cnieh5Uc.js";
 import { H as Po } from "./shared/hx-slider-Blmv_rwS.js";
 import { H as Mo } from "./shared/hx-spinner-DL5AYr16.js";
@@ -72,7 +72,7 @@ import { H as ct } from "./shared/hx-tag-CNSmdyaK.js";
 import { H as ht } from "./shared/hx-text-Bz_9fJ3J.js";
 import { F as St, H as yt } from "./shared/hx-text-input-D6FlOZM-.js";
 import { H as bt } from "./shared/hx-textarea-CNG590KY.js";
-import { H as gt } from "./shared/hx-theme-BiyQ7UUK.js";
+import { H as gt } from "./shared/hx-theme-BsefFWTO.js";
 import { H as vt } from "./shared/hx-time-picker-BoEIZwzv.js";
 import { H as Et, a as Dt, t as kt } from "./shared/toast-factory-YSznocIV.js";
 import { H as Bt } from "./shared/hx-toggle-button-iLiYrMbD.js";