@helixui/library 3.2.0-next.98 → 3.3.0

package/dist/css/helix-data.css

@@ -80,7 +80,8 @@
     min-width: var(--hx-touch-target-min, 2.75rem);
     min-height: var(--hx-touch-target-min, 2.75rem);
     padding: var(--hx-space-1, 0.25rem) var(--hx-space-2, 0.5rem);
-    border: var(--hx-border-width-thin, 1px) solid var(--hx-color-border-strong, #66787b);
+    border: var(--hx-border-width-thin, 1px) solid
+      var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7));
     border-radius: var(--hx-border-radius-sm, 0.25rem);
     /* Copy button sits on the always-dark block snippet surface; uses inverse family for contrast on the terminal background. */
     background-color: var(--hx-color-surface-inverse, #0d1825);
@@ -105,8 +106,14 @@
   }
 
   .code-snippet__copy-button:focus-visible {
-    outline: var(--hx-focus-ring-width, 2px) solid
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078));
+    /* Always-dark terminal surface — uses primary-400 (#6AB1B1, 7.27:1 on #0d1825)
+       instead of the light-mode --hx-focus-ring-color (primary-600, 3.07:1 — razor
+       above the 3:1 UI floor with no headroom). Deliberate primitive-tier consumption:
+       there is no semantic focus-ring-on-dark alias today — the dark.color.focus-ring
+       override at tokens.json only fires under theme=dark, but this surface is dark in
+       every theme. Tracked for promotion to a semantic alias in a future token-cascade
+       follow-up. */
+    outline: var(--hx-focus-ring-width, 2px) solid var(--hx-color-primary-400, #6ab1b1);
     outline-offset: var(--hx-focus-ring-offset, 2px);
   }
 
@@ -125,7 +132,8 @@
     min-height: var(--hx-touch-target-min, 2.75rem);
     padding: var(--hx-space-2, 0.5rem) var(--hx-space-4, 1rem);
     border: none;
-    border-top: var(--hx-border-width-thin, 1px) solid var(--hx-color-border-strong, #66787b);
+    border-top: var(--hx-border-width-thin, 1px) solid
+      var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7));
     /* Expand button is attached to the always-dark block snippet — inverse family maintains the terminal aesthetic. */
     background-color: var(--hx-color-surface-inverse, #0d1825);
     color: var(--hx-color-text-inverse, #ffffff);
@@ -146,8 +154,14 @@
   }
 
   .code-snippet__expand-button:focus-visible {
-    outline: var(--hx-focus-ring-width, 2px) solid
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078));
+    /* Always-dark terminal surface — uses primary-400 (#6AB1B1, 7.27:1 on #0d1825)
+       instead of the light-mode --hx-focus-ring-color (primary-600, 3.07:1 — razor
+       above the 3:1 UI floor with no headroom). Deliberate primitive-tier consumption:
+       there is no semantic focus-ring-on-dark alias today — the dark.color.focus-ring
+       override at tokens.json only fires under theme=dark, but this surface is dark in
+       every theme. Tracked for promotion to a semantic alias in a future token-cascade
+       follow-up. */
+    outline: var(--hx-focus-ring-width, 2px) solid var(--hx-color-primary-400, #6ab1b1);
     outline-offset: var(--hx-focus-ring-offset, 2px);
   }
 

package/dist/css/helix-feedback.css

@@ -160,10 +160,7 @@
 
   .alert__close-button:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-alert-close-btn-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-alert-close-btn-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     opacity: 1;
   }
@@ -336,10 +333,7 @@
 
   .banner__action:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-banner-action-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-banner-action-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     border-radius: var(--hx-border-radius-sm, 0.25rem);
   }
@@ -380,10 +374,7 @@
 
   .banner__close-button:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-banner-close-btn-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-banner-close-btn-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     opacity: 1;
   }

package/dist/css/helix-forms.css

@@ -74,10 +74,7 @@
 
   .checkbox__input:focus-visible ~ .checkbox__box {
     outline: var(--hx-checkbox-focus-ring-width, var(--hx-focus-ring-width, 2px)) solid
-      var(
-        --hx-checkbox-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-checkbox-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-checkbox-focus-ring-offset, var(--hx-focus-ring-offset, 2px));
   }
 
@@ -722,17 +719,11 @@
       box-shadow var(--hx-transition-fast, 150ms ease);
   }
   .field__input-wrapper:focus-within {
-    border-color: var(
-      --hx-combobox-focus-ring-color,
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-    );
+    border-color: var(--hx-combobox-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     box-shadow: 0 0 0 var(--hx-focus-ring-width, 2px)
       color-mix(
         in srgb,
-        var(
-            --hx-combobox-focus-ring-color,
-            var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-          )
+        var(--hx-combobox-focus-ring-color, var(--hx-focus-ring-color, #0f7078))
           calc(var(--hx-focus-ring-opacity, 0.25) * 100%),
         transparent
       );
@@ -1138,17 +1129,11 @@
   }
 
   .field__input-wrapper:focus-within {
-    border-color: var(
-      --hx-date-picker-focus-ring-color,
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-    );
+    border-color: var(--hx-date-picker-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     box-shadow: 0 0 0 var(--hx-focus-ring-width, 2px)
       color-mix(
         in srgb,
-        var(
-            --hx-date-picker-focus-ring-color,
-            var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-          )
+        var(--hx-date-picker-focus-ring-color, var(--hx-focus-ring-color, #0f7078))
           calc(var(--hx-focus-ring-opacity, 0.25) * 100%),
         transparent
       );
@@ -1217,17 +1202,10 @@
   }
 
   .field__trigger:focus-visible {
-    color: var(
-      --hx-date-picker-focus-ring-color,
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-    );
+    color: var(--hx-date-picker-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     background-color: color-mix(
       in srgb,
-      var(
-          --hx-date-picker-focus-ring-color,
-          var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-        )
-        8%,
+      var(--hx-date-picker-focus-ring-color, var(--hx-focus-ring-color, #0f7078)) 8%,
       transparent
     );
   }
@@ -1324,10 +1302,7 @@
 
   :is(.calendar__nav-btn, .calendar__day):focus-visible {
     box-shadow: 0 0 0 var(--hx-focus-ring-width, 2px)
-      var(
-        --hx-date-picker-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-date-picker-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     z-index: 1;
   }
 
@@ -2543,8 +2518,7 @@
   }
 
   .symbol:focus-visible {
-    outline: var(--hx-focus-ring-width, 2px) solid
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078));
+    outline: var(--hx-focus-ring-width, 2px) solid var(--hx-focus-ring-color, #0f7078);
     outline-offset: var(--hx-focus-ring-offset, 2px);
     border-radius: var(--hx-border-radius-sm, 0.25rem);
   }
@@ -2658,10 +2632,7 @@
     --_border-radius: var(--hx-select-border-radius, var(--hx-border-radius-md, 0.375rem));
 
     /* Focus ring */
-    --_focus-ring-color: var(
-      --hx-select-focus-ring-color,
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-    );
+    --_focus-ring-color: var(--hx-select-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
 
     /* Error */
     --_error-color: var(--hx-select-error-color, var(--hx-color-error-500, #e5493e));
@@ -3215,10 +3186,7 @@
   .slider__input:focus-visible ~ .slider__thumb-visual {
     box-shadow:
       0 0 0 var(--hx-focus-ring-width, 2px)
-        var(
-          --hx-slider-focus-ring-color,
-          var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-        ),
+        var(--hx-slider-focus-ring-color, var(--hx-focus-ring-color, #0f7078)),
       var(--hx-slider-thumb-shadow, var(--hx-shadow-sm, 0 1px 2px 0 rgb(0 0 0 / 0.05)));
   }
 
@@ -3362,10 +3330,7 @@
 
   .switch__track:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-switch-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-switch-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
   }
 
@@ -3579,10 +3544,7 @@
     );
     --_text-input-border-color-focus: var(
       --hx-text-input-border-color-focus,
-      var(
-        --hx-input-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      )
+      var(--hx-input-focus-ring-color, var(--hx-focus-ring-color, #0f7078))
     );
     --_text-input-border-color-invalid: var(
       --hx-text-input-border-color-invalid,
@@ -3608,10 +3570,7 @@
     /* Focus ring */
     --_text-input-focus-ring-color: var(
       --hx-text-input-focus-ring-color,
-      var(
-        --hx-input-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      )
+      var(--hx-input-focus-ring-color, var(--hx-focus-ring-color, #0f7078))
     );
     --_text-input-focus-ring-width: var(
       --hx-text-input-focus-ring-width,
@@ -3921,10 +3880,7 @@
     );
     --_textarea-border-color-focus: var(
       --hx-textarea-border-color-focus,
-      var(
-        --hx-input-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      )
+      var(--hx-input-focus-ring-color, var(--hx-focus-ring-color, #0f7078))
     );
     --_textarea-border-color-invalid: var(
       --hx-textarea-border-color-invalid,
@@ -4446,10 +4402,7 @@
 
   .button:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-toggle-button-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-toggle-button-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
   }
 

package/dist/css/helix-navigation.css

@@ -740,7 +740,10 @@
     transition: width var(--hx-transition-normal, 300ms) ease;
     overflow: hidden;
     border-inline-end: var(--hx-border-width-thin, 1px) solid
-      var(--hx-side-nav-border-color, var(--hx-color-border-strong, #66787b));
+      var(
+        --hx-side-nav-border-color,
+        var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7))
+      );
   }
 
   /* ─── Collapsed State ─── */
@@ -758,7 +761,10 @@
     flex-shrink: 0;
     min-height: var(--hx-space-14, 3.5rem);
     border-bottom: var(--hx-border-width-thin, 1px) solid
-      var(--hx-side-nav-border-color, var(--hx-color-border-strong, #66787b));
+      var(
+        --hx-side-nav-border-color,
+        var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7))
+      );
     overflow: hidden;
   }
 
@@ -785,7 +791,10 @@
     flex-shrink: 0;
     min-height: var(--hx-space-14, 3.5rem);
     border-top: var(--hx-border-width-thin, 1px) solid
-      var(--hx-side-nav-border-color, var(--hx-color-border-strong, #66787b));
+      var(
+        --hx-side-nav-border-color,
+        var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7))
+      );
     overflow: hidden;
   }
 
@@ -816,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-border-on-dark-subtle,
-      rgba(255, 255, 255, 0.1)
-    ); /* fallback for browsers without color-mix() */
+      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)
+        )
+      );
     }
   }
 
@@ -1287,8 +1308,7 @@
   }
 
   .tree:focus-visible {
-    outline: var(--hx-focus-ring-width, 2px) solid
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078));
+    outline: var(--hx-focus-ring-width, 2px) solid var(--hx-focus-ring-color, #0f7078);
     outline-offset: var(--hx-focus-ring-offset, 2px);
     border-radius: var(--hx-border-radius-sm, 0.25rem);
   }

package/dist/css/helix-tokens.css

@@ -119,13 +119,13 @@
   --hx-color-surface-warning-strong: var(--hx-color-warning-500);
   --hx-color-surface-danger-strong: var(--hx-color-error-600);
   --hx-color-surface-info-strong: var(--hx-color-primary-600);
+  --hx-color-surface-on-dark-overlay-default: var(--hx-overlay-white-30);
+  --hx-color-surface-on-dark-overlay-subtle: var(--hx-overlay-white-10);
   --hx-color-border-default: var(--hx-color-neutral-200);
   --hx-color-border-subtle: var(--hx-color-neutral-100);
   --hx-color-border-strong: var(--hx-color-neutral-500);
   --hx-color-border-focus: var(--hx-color-primary-500);
   --hx-color-border-on-dark-strong: var(--hx-overlay-white-70);
-  --hx-color-border-on-dark-default: var(--hx-overlay-white-30);
-  --hx-color-border-on-dark-subtle: var(--hx-overlay-white-10);
   --hx-color-focus-ring: var(--hx-color-primary-600);
   --hx-color-selection-bg: var(--hx-color-primary-200);
   --hx-color-selection-color: var(--hx-color-neutral-900);
@@ -368,13 +368,13 @@
     --hx-color-surface-sunken: var(--hx-color-neutral-950);
     --hx-color-surface-inverse: var(--hx-color-neutral-100);
     --hx-color-surface-overlay: rgba(0, 0, 0, 0.85);
+    --hx-color-surface-on-dark-overlay-default: var(--hx-overlay-black-30);
+    --hx-color-surface-on-dark-overlay-subtle: var(--hx-overlay-black-10);
     --hx-color-border-default: var(--hx-color-neutral-700);
     --hx-color-border-subtle: var(--hx-color-neutral-800);
     --hx-color-border-strong: var(--hx-color-neutral-400);
     --hx-color-border-focus: var(--hx-color-primary-400);
     --hx-color-border-on-dark-strong: var(--hx-overlay-black-50);
-    --hx-color-border-on-dark-default: var(--hx-overlay-black-30);
-    --hx-color-border-on-dark-subtle: var(--hx-overlay-black-10);
     --hx-color-focus-ring: var(--hx-color-primary-400);
     --hx-color-selection-bg: var(--hx-color-primary-800);
     --hx-color-selection-color: var(--hx-color-neutral-100);
@@ -414,13 +414,13 @@
   --hx-color-surface-sunken: var(--hx-color-neutral-950);
   --hx-color-surface-inverse: var(--hx-color-neutral-100);
   --hx-color-surface-overlay: rgba(0, 0, 0, 0.85);
+  --hx-color-surface-on-dark-overlay-default: var(--hx-overlay-black-30);
+  --hx-color-surface-on-dark-overlay-subtle: var(--hx-overlay-black-10);
   --hx-color-border-default: var(--hx-color-neutral-700);
   --hx-color-border-subtle: var(--hx-color-neutral-800);
   --hx-color-border-strong: var(--hx-color-neutral-400);
   --hx-color-border-focus: var(--hx-color-primary-400);
   --hx-color-border-on-dark-strong: var(--hx-overlay-black-50);
-  --hx-color-border-on-dark-default: var(--hx-overlay-black-30);
-  --hx-color-border-on-dark-subtle: var(--hx-overlay-black-10);
   --hx-color-focus-ring: var(--hx-color-primary-400);
   --hx-color-selection-bg: var(--hx-color-primary-800);
   --hx-color-selection-color: var(--hx-color-neutral-100);
@@ -486,13 +486,13 @@
     --hx-color-surface-warning-strong: var(--hx-color-warning-500);
     --hx-color-surface-danger-strong: var(--hx-color-error-500);
     --hx-color-surface-info-strong: var(--hx-color-primary-500);
+    --hx-color-surface-on-dark-overlay-default: #FFFFFF;
+    --hx-color-surface-on-dark-overlay-subtle: #C0C0C0;
     --hx-color-border-default: #FFFFFF;
     --hx-color-border-subtle: #C0C0C0;
     --hx-color-border-strong: #FFFFFF;
     --hx-color-border-focus: #FFFF00;
     --hx-color-border-on-dark-strong: #FFFFFF;
-    --hx-color-border-on-dark-default: #FFFFFF;
-    --hx-color-border-on-dark-subtle: #C0C0C0;
     --hx-color-focus-ring: #FFFF00;
     --hx-color-selection-bg: #1AEBFF;
     --hx-color-selection-color: #000000;

package/dist/css/helix-utility.css

@@ -415,10 +415,7 @@
 
   .split-button__primary:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-split-button-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-split-button-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     z-index: 1;
     position: relative;
@@ -460,10 +457,7 @@
 
   .split-button__trigger:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-split-button-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-split-button-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     z-index: 1;
     position: relative;

package/dist/css/hx-alert.css

@@ -158,10 +158,7 @@
 
   .alert__close-button:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-alert-close-btn-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-alert-close-btn-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     opacity: 1;
   }

package/dist/css/hx-banner.css

@@ -96,10 +96,7 @@
 
   .banner__action:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-banner-action-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-banner-action-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     border-radius: var(--hx-border-radius-sm, 0.25rem);
   }
@@ -140,10 +137,7 @@
 
   .banner__close-button:focus-visible {
     outline: var(--hx-focus-ring-width, 2px) solid
-      var(
-        --hx-banner-close-btn-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-banner-close-btn-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-focus-ring-offset, 2px);
     opacity: 1;
   }

package/dist/css/hx-button.css

@@ -229,15 +229,16 @@
 
   /* ─── Inverted Mode ─── */
 
-  /* Inline-fallback contract for --hx-color-border-on-dark-* in this section:
+  /* Inline-fallback contract for the on-dark-* tokens in this section:
      the literal rgba(255, 255, 255, 0.X) arms are a LIGHT-MODE-only last
      resort (cold-start, CSS-not-loaded). At runtime, hx-theme injects
-     dark.color.border.on-dark-* as overlay-black-* so dark-mode inverted
-     buttons stay visible on the now-light surface.inverse (#EBEEE9). The
-     inline white overlays would render invisible (≈1.1:1) on a light surface,
-     but they never paint when the theme is mounted. If a future change moves
-     these into a context where hx-theme is not guaranteed, replace with
-     mode-aware tokens. */
+     the dark.* override (overlay-black-* for the strong border and the
+     surface.on-dark-overlay-* fills) so dark-mode inverted buttons stay
+     visible on the now-light surface.inverse (#EBEEE9). The inline white
+     overlays would render invisible (≈1.1:1) on a light surface, but
+     they never paint when the theme is mounted. If a future change
+     moves these into a context where hx-theme is not guaranteed,
+     replace with mode-aware tokens. */
 
   /* Override text color and filter-based hover/active for all variants */
   :host([inverted]) .button {
@@ -255,8 +256,12 @@
 
   :host([inverted]) .button:focus-visible {
     /* WCAG 1.4.11: focus indicator needs ≥3:1 against adjacent colors.
-       border-on-dark-default (overlay-white-30) ≈ 2.7:1 on neutral-900 — fails.
-       border-on-dark-strong (overlay-white-70) ≈ 5:1 — passes. */
+       border-on-dark-strong (overlay-white-70) ≈ 5:1 on neutral-900 — passes.
+       The lower-alpha siblings used to live in border.* but were sub-3:1
+       against any plausible surface and could not honour a border contract;
+       they're now surface.on-dark-overlay-{default,subtle} (translucent
+       fills, not borders) and used elsewhere in this file. See
+       tokens.json color.surface.on-dark-overlay-* for canonical ratios. */
     outline-color: var(
       --hx-button-inverted-focus-ring-color,
       var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7))
@@ -267,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);
   }
@@ -320,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-border-on-dark-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 subtle (10%) lifts to default (30%) on hover
-     so the runtime hover delta is visually distinct, not collapsed onto a
-     single token. */
+  /* 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-border-on-dark-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-border-on-dark-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 */
@@ -345,7 +372,10 @@
   :host([inverted]) .button--ghost:hover {
     --hx-button-bg: var(
       --hx-button-inverted-ghost-hover-bg,
-      var(--hx-color-border-on-dark-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))
+      )
     );
   }
 
@@ -355,7 +385,10 @@
   }
 
   :host([inverted]) .button--outline:hover {
-    --hx-button-bg: var(--hx-color-border-on-dark-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-checkbox.css

@@ -72,10 +72,7 @@
 
   .checkbox__input:focus-visible ~ .checkbox__box {
     outline: var(--hx-checkbox-focus-ring-width, var(--hx-focus-ring-width, 2px)) solid
-      var(
-        --hx-checkbox-focus-ring-color,
-        var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078))
-      );
+      var(--hx-checkbox-focus-ring-color, var(--hx-focus-ring-color, #0f7078));
     outline-offset: var(--hx-checkbox-focus-ring-offset, var(--hx-focus-ring-offset, 2px));
   }
 

package/dist/css/hx-code-snippet.css

@@ -78,7 +78,8 @@
     min-width: var(--hx-touch-target-min, 2.75rem);
     min-height: var(--hx-touch-target-min, 2.75rem);
     padding: var(--hx-space-1, 0.25rem) var(--hx-space-2, 0.5rem);
-    border: var(--hx-border-width-thin, 1px) solid var(--hx-color-border-strong, #66787b);
+    border: var(--hx-border-width-thin, 1px) solid
+      var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7));
     border-radius: var(--hx-border-radius-sm, 0.25rem);
     /* Copy button sits on the always-dark block snippet surface; uses inverse family for contrast on the terminal background. */
     background-color: var(--hx-color-surface-inverse, #0d1825);
@@ -103,8 +104,14 @@
   }
 
   .code-snippet__copy-button:focus-visible {
-    outline: var(--hx-focus-ring-width, 2px) solid
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078));
+    /* Always-dark terminal surface — uses primary-400 (#6AB1B1, 7.27:1 on #0d1825)
+       instead of the light-mode --hx-focus-ring-color (primary-600, 3.07:1 — razor
+       above the 3:1 UI floor with no headroom). Deliberate primitive-tier consumption:
+       there is no semantic focus-ring-on-dark alias today — the dark.color.focus-ring
+       override at tokens.json only fires under theme=dark, but this surface is dark in
+       every theme. Tracked for promotion to a semantic alias in a future token-cascade
+       follow-up. */
+    outline: var(--hx-focus-ring-width, 2px) solid var(--hx-color-primary-400, #6ab1b1);
     outline-offset: var(--hx-focus-ring-offset, 2px);
   }
 
@@ -123,7 +130,8 @@
     min-height: var(--hx-touch-target-min, 2.75rem);
     padding: var(--hx-space-2, 0.5rem) var(--hx-space-4, 1rem);
     border: none;
-    border-top: var(--hx-border-width-thin, 1px) solid var(--hx-color-border-strong, #66787b);
+    border-top: var(--hx-border-width-thin, 1px) solid
+      var(--hx-color-border-on-dark-strong, rgba(255, 255, 255, 0.7));
     /* Expand button is attached to the always-dark block snippet — inverse family maintains the terminal aesthetic. */
     background-color: var(--hx-color-surface-inverse, #0d1825);
     color: var(--hx-color-text-inverse, #ffffff);
@@ -144,8 +152,14 @@
   }
 
   .code-snippet__expand-button:focus-visible {
-    outline: var(--hx-focus-ring-width, 2px) solid
-      var(--hx-focus-ring-color, var(--hx-color-primary-600, #0f7078));
+    /* Always-dark terminal surface — uses primary-400 (#6AB1B1, 7.27:1 on #0d1825)
+       instead of the light-mode --hx-focus-ring-color (primary-600, 3.07:1 — razor
+       above the 3:1 UI floor with no headroom). Deliberate primitive-tier consumption:
+       there is no semantic focus-ring-on-dark alias today — the dark.color.focus-ring
+       override at tokens.json only fires under theme=dark, but this surface is dark in
+       every theme. Tracked for promotion to a semantic alias in a future token-cascade
+       follow-up. */
+    outline: var(--hx-focus-ring-width, 2px) solid var(--hx-color-primary-400, #6ab1b1);
     outline-offset: var(--hx-focus-ring-offset, 2px);
   }