@helixui/library 3.2.0 → 3.3.0-next.111

package/custom-elements.json

@@ -2826,21 +2826,25 @@
           "name": "HelixButton",
           "cssProperties": [
             {
-              "description": "Button background color.",
+              "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-primary-500)"
+              "default": "var(--hx-color-action-primary-bg)"
             },
             {
-              "description": "Hover background color override. When set, overrides the variant default hover background from outside the shadow DOM.",
+              "description": "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.",
               "name": "--hx-button-hover-bg"
             },
             {
-              "description": "Button text color.",
+              "description": "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.",
+              "name": "--hx-button-active-bg"
+            },
+            {
+              "description": "Button text color (variants route through text.on-{role} / text.on-{role}-strong).",
               "name": "--hx-button-color",
-              "default": "var(--hx-color-neutral-0)"
+              "default": "var(--hx-color-text-on-primary)"
             },
             {
-              "description": "Button border color.",
+              "description": "Button border color (secondary/outline variants route through action.secondary.border).",
               "name": "--hx-button-border-color",
               "default": "transparent"
             },
@@ -2865,187 +2869,129 @@
               "default": "var(--hx-focus-ring-color)"
             },
             {
-              "description": "Text color when inverted.",
+              "description": "Text color when inverted (resolves to neutral-0).",
               "name": "--hx-button-inverted-color",
-              "default": "#ffffff"
-            },
-            {
-              "description": "Ghost hover bg when inverted.",
-              "name": "--hx-button-inverted-ghost-hover-bg",
-              "default": "rgba(255,255,255,0.15)"
-            },
-            {
-              "description": "Focus ring color when inverted.",
-              "name": "--hx-button-inverted-focus-ring-color",
-              "default": "rgba(255,255,255,0.5)"
-            },
-            {
-              "description": "Opacity.",
-              "name": "--hx-opacity-disabled"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-2"
+              "default": "var(--hx-color-text-inverse)"
             },
             {
-              "description": "Width.",
-              "name": "--hx-border-width-thin"
+              "description": "Foreground override for inverted primary hover and pressed (combined :hover, :active rule). Defaults to text.on-primary (neutral-900, no dark-mode flip) so dark text rides the lifted primary-400 fill — text.inverse on light teal collapses to ~2.4:1 in light mode.",
+              "name": "--hx-button-inverted-primary-interactive-color",
+              "default": "var(--hx-color-text-on-primary)"
             },
             {
-              "description": "CSS custom property.",
-              "name": "--hx-border-radius-md"
+              "description": "Foreground override for inverted danger hover and pressed (combined :hover, :active rule). Defaults to text.on-error (neutral-900); same rationale as the primary override.",
+              "name": "--hx-button-inverted-danger-interactive-color",
+              "default": "var(--hx-color-text-on-error)"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-primary-500"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-0"
-            },
-            {
-              "description": "Font family.",
-              "name": "--hx-font-family-sans"
-            },
-            {
-              "description": "Font weight.",
-              "name": "--hx-font-weight-semibold"
-            },
-            {
-              "description": "Line height.",
-              "name": "--hx-line-height-tight"
+              "description": "Ghost hover bg when inverted (overlay-white-30 — translucent fill, not a border; contrast not applicable).",
+              "name": "--hx-button-inverted-ghost-hover-bg",
+              "default": "var(--hx-color-surface-on-dark-overlay-default)"
             },
             {
-              "description": "Transition timing.",
-              "name": "--hx-transition-fast"
+              "description": "Focus ring color when inverted (overlay-white-70 ≈ 5:1 vs neutral-900 — clears WCAG 1.4.11 3:1 floor for non-text UI).",
+              "name": "--hx-button-inverted-focus-ring-color",
+              "default": "var(--hx-color-border-on-dark-strong)"
             },
             {
-              "description": "Width.",
-              "name": "--hx-focus-ring-width"
+              "description": "Primary variant resting fill (3.2.1 semantic action layer).",
+              "name": "--hx-color-action-primary-bg"
             },
             {
-              "description": "Color.",
-              "name": "--hx-focus-ring-color"
+              "description": "Primary variant hover fill.",
+              "name": "--hx-color-action-primary-bg-hover"
             },
             {
-              "description": "CSS custom property.",
-              "name": "--hx-focus-ring-offset"
+              "description": "Primary variant active/pressed fill.",
+              "name": "--hx-color-action-primary-bg-active"
             },
             {
-              "description": "CSS filter.",
-              "name": "--hx-filter-brightness-hover"
+              "description": "Secondary/outline variant fg (resolves to primary-600 light, primary-400 dark). Consumed only by .button--secondary; the actual border/surface paint for outline currently routes through --hx-color-border-strong / --hx-color-surface-raised in styles, with this token reserved for the foreground.",
+              "name": "--hx-color-action-secondary-fg"
             },
             {
-              "description": "CSS filter.",
-              "name": "--hx-filter-brightness-active"
+              "description": "Secondary/outline variant border (3.2.1 semantic; outline still routes through --hx-color-border-strong by default).",
+              "name": "--hx-color-action-secondary-border"
             },
             {
-              "description": "Spacing token.",
-              "name": "--hx-space-1"
+              "description": "Secondary/outline variant hover fill (3.2.1 semantic; outline still routes through --hx-color-surface-raised by default).",
+              "name": "--hx-color-action-secondary-bg-hover"
             },
             {
-              "description": "Spacing token.",
-              "name": "--hx-space-3"
+              "description": "Ghost variant fg.",
+              "name": "--hx-color-action-ghost-fg"
             },
             {
-              "description": "Font size.",
-              "name": "--hx-font-size-sm"
+              "description": "Ghost variant hover fill.",
+              "name": "--hx-color-action-ghost-bg-hover"
             },
             {
-              "description": "Minimum touch target size.",
-              "name": "--hx-touch-target-min"
+              "description": "Danger variant resting fill.",
+              "name": "--hx-color-action-danger-bg"
             },
             {
-              "description": "Spacing token.",
-              "name": "--hx-space-4"
+              "description": "Danger variant hover fill.",
+              "name": "--hx-color-action-danger-bg-hover"
             },
             {
-              "description": "Font size.",
-              "name": "--hx-font-size-md"
+              "description": "Danger variant active fill.",
+              "name": "--hx-color-action-danger-bg-active"
             },
             {
-              "description": "Size token.",
-              "name": "--hx-size-10"
+              "description": "Primary variant hover/pressed fill on dark/inverted surface (resolves to primary-400, 7.27:1 on neutral-900).",
+              "name": "--hx-color-action-primary-bg-inverted-hover"
             },
             {
-              "description": "Spacing token.",
-              "name": "--hx-space-6"
+              "description": "Danger variant hover/pressed fill on dark/inverted surface (resolves to error-400, 6.58:1 on neutral-900).",
+              "name": "--hx-color-action-danger-bg-inverted-hover"
             },
             {
-              "description": "Font size.",
-              "name": "--hx-font-size-lg"
+              "description": "Foreground for primary fill (resolves to neutral-900 — AA-tuned for primary-500).",
+              "name": "--hx-color-text-on-primary"
             },
             {
-              "description": "Size token.",
-              "name": "--hx-size-12"
+              "description": "Foreground for primary-hover fill (resolves to neutral-0 across modes).",
+              "name": "--hx-color-text-on-primary-strong"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-primary-50"
+              "description": "Foreground for danger fill (resolves to neutral-900).",
+              "name": "--hx-color-text-on-error"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-neutral-100"
+              "description": "Foreground for danger-hover fill (resolves to neutral-0 across modes).",
+              "name": "--hx-color-text-on-error-strong"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-neutral-900"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-200"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-error-500"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-error-600"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-300"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-50"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-primary-600"
-            },
-            {
-              "description": "Animation duration.",
-              "name": "--hx-duration-spinner"
+              "description": "Foreground for tertiary variant on surface.sunken.",
+              "name": "--hx-color-text-primary"
             },
             {
-              "description": "Opacity.",
-              "name": "--hx-opacity-muted"
+              "description": "Tertiary variant resting fill.",
+              "name": "--hx-color-surface-sunken"
             },
             {
-              "description": "Overlay color.",
-              "name": "--hx-overlay-white-50"
+              "description": "Tertiary variant hover fill.",
+              "name": "--hx-color-surface-raised"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-primary-400"
+              "description": "Inverted-tertiary resting fill (overlay-white-10 — translucent fill, not a border).",
+              "name": "--hx-color-surface-on-dark-overlay-subtle"
             },
             {
-              "description": "Overlay color.",
-              "name": "--hx-overlay-white-70"
+              "description": "Inverted-tertiary hover fill + inverted-secondary/ghost/outline hover fill (overlay-white-30 — translucent fill, not a border).",
+              "name": "--hx-color-surface-on-dark-overlay-default"
             },
             {
-              "description": "Overlay color.",
-              "name": "--hx-overlay-white-15"
+              "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": "Overlay color.",
-              "name": "--hx-overlay-white-25"
+              "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": "Overlay color.",
-              "name": "--hx-overlay-white-20"
+              "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": [
@@ -3197,7 +3143,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When true, flips button colors for placement on dark or gradient backgrounds.\nForces text to white and adjusts hover/focus ring colors across all variants.",
+              "description": "When true, flips button colors for placement on dark or gradient backgrounds.\nForces text to white and adjusts hover/focus ring colors across all variants.\n\n**Mode scope:** `[inverted]` is validated for placement on a dark *region*\nwithin a light-mode-active page (hero banners, gradient sections, dark\ncards). It is NOT validated for use within a dark-mode-active root\ncontext: in dark mode, `surface.inverse` flips to a light surface\n(neutral-100), and the lifted `-400` hover/active fills lose UI-floor\ncontrast against it (primary 2.10:1, danger 2.32:1 vs WCAG 1.4.11's 3:1\nfloor). Mode-aware fill stops + foreground for the dark-mode-inverted\ncombination are tracked as a 3.2.x follow-up.",
               "attribute": "inverted",
               "reflects": true
             },
@@ -3355,7 +3301,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When true, flips button colors for placement on dark or gradient backgrounds.\nForces text to white and adjusts hover/focus ring colors across all variants.",
+              "description": "When true, flips button colors for placement on dark or gradient backgrounds.\nForces text to white and adjusts hover/focus ring colors across all variants.\n\n**Mode scope:** `[inverted]` is validated for placement on a dark *region*\nwithin a light-mode-active page (hero banners, gradient sections, dark\ncards). It is NOT validated for use within a dark-mode-active root\ncontext: in dark mode, `surface.inverse` flips to a light surface\n(neutral-100), and the lifted `-400` hover/active fills lose UI-floor\ncontrast against it (primary 2.10:1, danger 2.32:1 vs WCAG 1.4.11's 3:1\nfloor). Mode-aware fill stops + foreground for the dark-mode-inverted\ncombination are tracked as a 3.2.x follow-up.",
               "fieldName": "inverted",
               "attribute": "inverted"
             },
@@ -22810,7 +22756,7 @@
             {
               "description": "Item text color.",
               "name": "--hx-nav-item-color",
-              "default": "var(--hx-color-neutral-300)"
+              "default": "var(--hx-color-text-inverse)"
             },
             {
               "description": "Item hover background.",
@@ -22819,17 +22765,17 @@
             {
               "description": "Item hover text color.",
               "name": "--hx-nav-item-hover-color",
-              "default": "var(--hx-color-neutral-100)"
+              "default": "var(--hx-color-text-inverse)"
             },
             {
               "description": "Active item background.",
               "name": "--hx-nav-item-active-bg",
-              "default": "var(--hx-color-primary-600)"
+              "default": "var(--hx-color-action-primary-bg-hover)"
             },
             {
               "description": "Active item text color.",
               "name": "--hx-nav-item-active-color",
-              "default": "var(--hx-color-neutral-50)"
+              "default": "var(--hx-color-text-on-primary-strong)"
             },
             {
               "description": "Item padding.",
@@ -22838,7 +22784,17 @@
             {
               "description": "Component host background color.",
               "name": "--hx-nav-item-host-bg",
-              "default": "var(--hx-color-neutral-900)"
+              "default": "var(--hx-color-surface-inverse)"
+            },
+            {
+              "description": "Tooltip background color (collapsed-rail tooltip).",
+              "name": "--hx-nav-item-tooltip-bg",
+              "default": "var(--hx-color-surface-inverse)"
+            },
+            {
+              "description": "Tooltip text color (collapsed-rail tooltip).",
+              "name": "--hx-nav-item-tooltip-color",
+              "default": "var(--hx-color-text-inverse)"
             }
           ],
           "cssParts": [
@@ -23048,17 +23004,17 @@
             {
               "description": "Background color.",
               "name": "--hx-side-nav-bg",
-              "default": "var(--hx-color-neutral-900)"
+              "default": "var(--hx-color-surface-inverse)"
             },
             {
               "description": "Text color.",
               "name": "--hx-side-nav-color",
-              "default": "var(--hx-color-neutral-100)"
+              "default": "var(--hx-color-text-inverse)"
             },
             {
-              "description": "Border color.",
+              "description": "Border color (against the dark surface-inverse host bg).",
               "name": "--hx-side-nav-border-color",
-              "default": "var(--hx-color-neutral-700)"
+              "default": "var(--hx-color-border-on-dark-strong)"
             },
             {
               "description": "Header padding.",
@@ -23071,85 +23027,34 @@
               "default": "var(--hx-space-4)"
             },
             {
-              "description": "Toggle button icon color.",
+              "description": "Toggle button icon color (resting).",
               "name": "--hx-side-nav-toggle-color",
-              "default": "var(--hx-color-neutral-400)"
+              "default": "var(--hx-color-text-inverse)"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-neutral-900"
+              "description": "Toggle button icon color on hover.",
+              "name": "--hx-side-nav-toggle-hover-color",
+              "default": "var(--hx-color-text-inverse)"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-neutral-100"
+              "description": "Side-nav surface fill (resolves to neutral-900 light, near-black dark).",
+              "name": "--hx-color-surface-inverse"
             },
             {
-              "description": "Transition timing.",
-              "name": "--hx-transition-normal"
+              "description": "Side-nav text color (resolves to neutral-0).",
+              "name": "--hx-color-text-inverse"
             },
             {
-              "description": "Width.",
-              "name": "--hx-border-width-thin"
+              "description": "Container/header/footer divider border (overlay-white-70 light, overlay-black-50 dark — sized for visibility on the mode-flipped surface-inverse).",
+              "name": "--hx-color-border-on-dark-strong"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-neutral-700"
+              "description": "Toggle button hover surface (overlay-white-10 primitive — translucent fill, not a border).",
+              "name": "--hx-color-surface-on-dark-overlay-subtle"
             },
             {
-              "description": "Spacing token.",
-              "name": "--hx-space-4"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-14"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-3"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-2"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-8"
-            },
-            {
-              "description": "CSS custom property.",
-              "name": "--hx-border-radius-sm"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-400"
-            },
-            {
-              "description": "Transition timing.",
-              "name": "--hx-transition-fast"
-            },
-            {
-              "description": "Overlay color.",
-              "name": "--hx-overlay-white-10"
-            },
-            {
-              "description": "Width.",
-              "name": "--hx-focus-ring-width"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-focus-ring-color"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-primary-400"
-            },
-            {
-              "description": "CSS custom property.",
-              "name": "--hx-focus-ring-offset"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-5"
+              "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": [
@@ -24409,7 +24314,7 @@
             {
               "description": "Color of the divider between primary and trigger.",
               "name": "--hx-split-button-divider-color",
-              "default": "var(--hx-color-primary-400)"
+              "default": "var(--hx-color-primary-900)"
             },
             {
               "description": "Font family.",
@@ -29777,17 +29682,17 @@
             {
               "description": "Input background color.",
               "name": "--hx-input-bg",
-              "default": "var(--hx-color-neutral-0)"
+              "default": "var(--hx-color-surface-default)"
             },
             {
               "description": "Input text color.",
               "name": "--hx-input-color",
-              "default": "var(--hx-color-neutral-800)"
+              "default": "var(--hx-color-text-strong)"
             },
             {
               "description": "Input border color.",
               "name": "--hx-input-border-color",
-              "default": "var(--hx-color-neutral-300)"
+              "default": "var(--hx-color-border-strong)"
             },
             {
               "description": "Input border radius.",
@@ -29807,12 +29712,12 @@
             {
               "description": "Error state color.",
               "name": "--hx-input-error-color",
-              "default": "var(--hx-color-error-500)"
+              "default": "var(--hx-color-error-text)"
             },
             {
               "description": "Label text color.",
               "name": "--hx-input-label-color",
-              "default": "var(--hx-color-neutral-700)"
+              "default": "var(--hx-color-text-strong)"
             },
             {
               "description": "Font size for the sm size variant.",
@@ -29825,124 +29730,52 @@
               "default": "1.125rem"
             },
             {
-              "description": "Opacity.",
-              "name": "--hx-opacity-disabled"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-focus-ring-color"
+              "description": "Outer border-width override (canonical hx-{tag}-* prefix; sits above --hx-input-* aliases in the cascade).",
+              "name": "--hx-text-input-border-width",
+              "default": "var(--hx-border-width-thin)"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-primary-400"
+              "description": "Outer horizontal padding override.",
+              "name": "--hx-text-input-padding-x",
+              "default": "var(--hx-space-3)"
             },
             {
-              "description": "Width.",
-              "name": "--hx-focus-ring-width"
+              "description": "Outer vertical padding override.",
+              "name": "--hx-text-input-padding-y",
+              "default": "var(--hx-space-2)"
             },
             {
-              "description": "CSS custom property.",
-              "name": "--hx-focus-ring-opacity"
+              "description": "Outer font-size override.",
+              "name": "--hx-text-input-font-size",
+              "default": "var(--hx-font-size-md)"
             },
             {
-              "description": "Spacing token.",
-              "name": "--hx-space-1"
+              "description": "Outer sm-variant font-size override (falls through to --hx-input-sm-font-size).",
+              "name": "--hx-text-input-sm-font-size"
             },
             {
-              "description": "Font family.",
-              "name": "--hx-font-family-sans"
+              "description": "Outer lg-variant font-size override (falls through to --hx-input-lg-font-size).",
+              "name": "--hx-text-input-lg-font-size"
             },
             {
-              "description": "Font size.",
-              "name": "--hx-font-size-sm"
+              "description": "Resting field surface (semantic).",
+              "name": "--hx-color-surface-default"
             },
             {
-              "description": "Font weight.",
-              "name": "--hx-font-weight-medium"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-700"
+              "description": "Resting input text + label color (semantic).",
+              "name": "--hx-color-text-strong"
             },
             {
-              "description": "Line height.",
-              "name": "--hx-line-height-normal"
+              "description": "Resting border color (semantic).",
+              "name": "--hx-color-border-strong"
             },
             {
-              "description": "Color.",
+              "description": "Error state text + border color (semantic).",
               "name": "--hx-color-error-text"
             },
             {
-              "description": "Font weight.",
-              "name": "--hx-font-weight-bold"
-            },
-            {
-              "description": "Width.",
-              "name": "--hx-border-width-thin"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-300"
-            },
-            {
-              "description": "CSS custom property.",
-              "name": "--hx-border-radius-md"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-0"
-            },
-            {
-              "description": "Transition timing.",
-              "name": "--hx-transition-fast"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-error-500"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-500"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-3"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-2"
-            },
-            {
-              "description": "Font size.",
-              "name": "--hx-font-size-md"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-800"
-            },
-            {
-              "description": "Size token.",
-              "name": "--hx-size-10"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-400"
-            },
-            {
-              "description": "Size token.",
-              "name": "--hx-size-8"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-4"
-            },
-            {
-              "description": "Size token.",
-              "name": "--hx-size-12"
-            },
-            {
-              "description": "Font size.",
-              "name": "--hx-font-size-xs"
+              "description": "Error border primitive fallback inside the invalid-state cascade.",
+              "name": "--hx-color-error-600"
             }
           ],
           "cssParts": [
@@ -31199,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
             },
@@ -31229,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
             },
             {
@@ -31261,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"
             },
@@ -32060,12 +31893,12 @@
             {
               "description": "Toast background color.",
               "name": "--hx-toast-bg",
-              "default": "var(--hx-color-neutral-900)"
+              "default": "var(--hx-color-surface-inverse)"
             },
             {
               "description": "Toast text color.",
               "name": "--hx-toast-color",
-              "default": "var(--hx-color-neutral-0)"
+              "default": "var(--hx-color-text-inverse)"
             },
             {
               "description": "Toast border radius.",
@@ -32094,12 +31927,12 @@
               "name": "--hx-border-radius-md"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-neutral-900"
+              "description": "Default-variant background semantic (neutral-900 anchor; flipped per mode).",
+              "name": "--hx-color-surface-inverse"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-neutral-0"
+              "description": "Default-variant foreground semantic (neutral-0 anchor; flipped per mode).",
+              "name": "--hx-color-text-inverse"
             },
             {
               "description": "CSS custom property.",
@@ -32136,20 +31969,36 @@
               "name": "--hx-transition-normal"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-success-600"
+              "description": "Success-variant background semantic (3.2.1 cascade).",
+              "name": "--hx-color-surface-success-strong"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-warning-500"
+              "description": "Warning-variant background semantic (3.2.1 cascade).",
+              "name": "--hx-color-surface-warning-strong"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-error-600"
+              "description": "Danger-variant background semantic (3.2.1 cascade).",
+              "name": "--hx-color-surface-danger-strong"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-primary-600"
+              "description": "Info-variant background semantic (3.2.1 cascade).",
+              "name": "--hx-color-surface-info-strong"
+            },
+            {
+              "description": "Success-variant foreground semantic (neutral-0 across modes).",
+              "name": "--hx-color-text-on-success-strong"
+            },
+            {
+              "description": "Warning-variant foreground semantic (neutral-900; warning sits on lighter -500 fill).",
+              "name": "--hx-color-text-on-warning"
+            },
+            {
+              "description": "Danger-variant foreground semantic (neutral-0 across modes).",
+              "name": "--hx-color-text-on-error-strong"
+            },
+            {
+              "description": "Info-variant foreground semantic (neutral-0 across modes).",
+              "name": "--hx-color-text-on-primary-strong"
             },
             {
               "description": "Minimum touch target size.",