@urbicon-ui/blocks 6.40.4 → 6.43.2

package/dist/primitives/Toggle/toggle.variants.js

@@ -8,7 +8,26 @@ export const toggleVariants = tv({
         // rectangle switch that reads as inline-toolbar control.
         track: [
             'relative inline-flex items-center',
-            'transition-[color,background-color,border-color,box-shadow] duration-[var(--blocks-duration-fast)] ease-out',
+            'transition-[color,background-color,border-color,box-shadow,scale] duration-[var(--blocks-duration-fast)] ease-out',
+            // Press feedback on the control surface — the same small-element press
+            // cue Checkbox took from Badge/Avatar (`scale-95`), with `group-active`
+            // so pressing the label squeezes the switch too. It rides the TRACK,
+            // not the thumb, for three reasons:
+            //   1. the track is the switch's control surface — Checkbox puts the
+            //      cue on `box`, and the whole subtree (thumb included) squeezes
+            //      with it, so one class covers the entire control;
+            //   2. the `dot` variant *hides* the thumb, so a thumb-mounted cue
+            //      would silently vanish exactly where the control is smallest;
+            //   3. the thumb already drives motion through `translate` (its
+            //      resting `-translate-y-1/2` plus the per-size `translate-x-*`).
+            //      Tailwind 4 compiles `scale-*` to the discrete `scale` property,
+            //      which CSS applies AFTER `translate` about the element's own
+            //      centre — so a thumb-mounted cue would shrink the knob in place
+            //      at whichever end of the track it sits, reading as a rendering
+            //      glitch rather than a press.
+            // `scale` is in the transition list above, and reduced motion collapses
+            // `--blocks-duration-fast` to 1ms.
+            'group-active:scale-95',
             'border border-transparent',
             'peer-focus-visible:ring-2 peer-focus-visible:ring-primary/50',
             'peer-focus-visible:ring-offset-2 peer-focus-visible:ring-offset-surface-base'
@@ -104,7 +123,20 @@ export const toggleVariants = tv({
             variant: 'default',
             checked: false,
             class: {
-                track: 'bg-surface-interactive',
+                // Off-state hover steps the boundary up to `border-emphasis` — the
+                // same destination Checkbox's unchecked `outlined` box reaches, on
+                // the border the track already reserves (`border border-transparent`
+                // in the slot base, so nothing shifts).
+                //
+                // A fill step is now possible — `surface-interactive-hover` (added
+                // 2026-07-25) is the rung the filled fields use, and it reads in both
+                // modes. The border step stays anyway, for a Toggle-specific reason:
+                // the `dot` variant hides the thumb, so the track IS the control, and a
+                // boundary change reads there where a fill wash does not. (The original
+                // reason was that no fill token worked at all — `surface-interactive`
+                // resolved to `surface-hover` in light and `surface-active` in dark.
+                // That is fixed; this is now a choice, not a constraint.)
+                track: 'bg-surface-interactive group-hover:border-border-emphasis',
                 thumb: 'translate-x-0'
             }
         },
@@ -113,7 +145,11 @@ export const toggleVariants = tv({
             variant: 'default',
             checked: false,
             withBorder: true,
-            class: { track: 'border-border-strong' }
+            // `border-strong` is the top of the border ladder, so the off-state
+            // hover above would *weaken* it (strong → emphasis). Pin the hover
+            // bucket to strong: an opt-in permanent boundary must not soften when
+            // the pointer arrives.
+            class: { track: 'border-border-strong group-hover:border-border-strong' }
         },
         {
             variant: 'default',
@@ -122,41 +158,58 @@ export const toggleVariants = tv({
             class: { track: 'ring-1 ring-inset ring-surface-base/40' }
         },
         // ── Checked track per intent (Switch-Pill only) ──
+        // Hover/active darken through the intent interaction-layer tokens — the
+        // same `bg-<intent>-hover` / `bg-<intent>-active` ladder Button and
+        // Checkbox use — via `group-*` so hovering/pressing the label counts too.
+        // The border stays on the base intent stop (as in Checkbox), leaving a
+        // hairline rim that makes the fill step legible.
         {
             variant: 'default',
             checked: true,
             intent: 'primary',
-            class: { track: 'bg-primary border-primary' }
+            class: {
+                track: 'bg-primary border-primary group-hover:bg-primary-hover group-active:bg-primary-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'secondary',
-            class: { track: 'bg-secondary border-secondary' }
+            class: {
+                track: 'bg-secondary border-secondary group-hover:bg-secondary-hover group-active:bg-secondary-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'success',
-            class: { track: 'bg-success border-success' }
+            class: {
+                track: 'bg-success border-success group-hover:bg-success-hover group-active:bg-success-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'warning',
-            class: { track: 'bg-warning border-warning' }
+            class: {
+                track: 'bg-warning border-warning group-hover:bg-warning-hover group-active:bg-warning-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'danger',
-            class: { track: 'bg-danger border-danger' }
+            class: {
+                track: 'bg-danger border-danger group-hover:bg-danger-hover group-active:bg-danger-active'
+            }
         },
         {
             variant: 'default',
             checked: true,
             intent: 'neutral',
-            class: { track: 'bg-neutral border-neutral' }
+            class: {
+                track: 'bg-neutral border-neutral group-hover:bg-neutral-hover group-active:bg-neutral-active'
+            }
         },
         // ── Error state: danger boundary on the unchecked track (Switch-Pill) ──
         // Mirrors Checkbox ("error overrides unchecked border"): the off state
@@ -165,11 +218,16 @@ export const toggleVariants = tv({
         // The dot-variant twin lives at the END of the compound list so it
         // folds over the dot-unchecked `border-border-default` (order is
         // semantic — later compounds win conflicting buckets).
+        // `group-hover:border-danger` pins the hover bucket as well — without it
+        // the off-state hover step above would repaint the error boundary neutral
+        // the moment the pointer arrives, which is exactly when the mark matters.
         {
             variant: 'default',
             error: true,
             checked: false,
-            class: { track: 'border-danger peer-focus-visible:ring-danger/40' }
+            class: {
+                track: 'border-danger group-hover:border-danger peer-focus-visible:ring-danger/40'
+            }
         },
         // ── Thumb translation per size when checked (Switch-Pill only) ──
         { variant: 'default', checked: true, size: 'xs', class: { thumb: 'translate-x-4' } },
@@ -193,50 +251,68 @@ export const toggleVariants = tv({
         {
             variant: 'dot',
             checked: false,
-            class: { track: 'border-border-default' }
+            // Off-state hover: `border-default` → `border-emphasis`, the exact
+            // ladder Checkbox's unchecked `outlined` box walks (the dot is
+            // outline-only, so its boundary is the whole control).
+            class: { track: 'border-border-default group-hover:border-border-emphasis' }
         },
+        // Same intent interaction layer as the Switch-Pill above — the dot is a
+        // filled intent surface too, just a 14px one.
         {
             variant: 'dot',
             checked: true,
             intent: 'primary',
-            class: { track: 'border-primary bg-primary' }
+            class: {
+                track: 'border-primary bg-primary group-hover:bg-primary-hover group-active:bg-primary-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'secondary',
-            class: { track: 'border-secondary bg-secondary' }
+            class: {
+                track: 'border-secondary bg-secondary group-hover:bg-secondary-hover group-active:bg-secondary-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'success',
-            class: { track: 'border-success bg-success' }
+            class: {
+                track: 'border-success bg-success group-hover:bg-success-hover group-active:bg-success-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'warning',
-            class: { track: 'border-warning bg-warning' }
+            class: {
+                track: 'border-warning bg-warning group-hover:bg-warning-hover group-active:bg-warning-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'danger',
-            class: { track: 'border-danger bg-danger' }
+            class: {
+                track: 'border-danger bg-danger group-hover:bg-danger-hover group-active:bg-danger-active'
+            }
         },
         {
             variant: 'dot',
             checked: true,
             intent: 'neutral',
-            class: { track: 'border-neutral bg-neutral' }
+            class: {
+                track: 'border-neutral bg-neutral group-hover:bg-neutral-hover group-active:bg-neutral-active'
+            }
         },
         // ── Error state, dot variant (must fold over dot-unchecked border) ──
+        // Pins the hover bucket too, for the same reason as the Switch-Pill twin.
         {
             variant: 'dot',
             error: true,
             checked: false,
-            class: { track: 'border-danger' }
+            class: { track: 'border-danger group-hover:border-danger' }
         }
     ],
     defaultVariants: {

package/dist/primitives/Tooltip/tooltip.variants.d.ts

@@ -1,19 +1,19 @@
 import { type SlotNames, type VariantProps } from '../../utils/variants.js';
 export declare const tooltipVariants: ((props?: {
     open?: boolean | undefined;
-    intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | "info" | undefined;
+    intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
     size?: "sm" | "md" | "lg" | undefined;
 } | undefined) => {
     base: (props?: ({
         open?: boolean | undefined;
-        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | "info" | undefined;
+        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
     }) | undefined) => string;
     arrow: (props?: ({
         open?: boolean | undefined;
-        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | "info" | undefined;
+        intent?: "primary" | "secondary" | "success" | "warning" | "danger" | "neutral" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
     } & {
         class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;

package/dist/primitives/Tooltip/tooltip.variants.js

@@ -48,10 +48,14 @@ export const tooltipVariants = tv({
             true: { base: 'opacity-100 starting:opacity-0' },
             false: { base: 'opacity-0' }
         },
+        // The standard six-value palette. `info` is deliberately absent: it belongs
+        // to the feedback family (Alert, Toast), where it means "informational, and
+        // stable under a rebrand" — a tooltip is a container, and `info` sat one
+        // hue-step from `primary` (220 vs 240), so the two were barely
+        // distinguishable while implying a distinction that wasn't there.
         intent: {
             primary: { base: 'bg-primary text-text-on-primary' },
             secondary: { base: 'bg-secondary text-text-on-primary' },
-            info: { base: 'bg-info text-text-on-primary' },
             success: { base: 'bg-success text-text-on-primary' },
             warning: { base: 'bg-warning text-text-on-warning' },
             danger: { base: 'bg-danger text-text-on-primary' },

package/dist/style/foundation.css

@@ -1,7 +1,7 @@
 @theme {
   --color-neutral-0: oklch(1 0 0);
-  --color-neutral-25: oklch(0.99 0.002 240);
-  --color-neutral-50: oklch(0.98 0.005 240);
+  --color-neutral-25: oklch(0.985 0.003 240);
+  --color-neutral-50: oklch(0.965 0.006 240);
   --color-neutral-100: oklch(0.95 0.008 240);
   --color-neutral-200: oklch(0.89 0.012 240);
   --color-neutral-300: oklch(0.83 0.014 240);
@@ -179,13 +179,23 @@
   --radius-commit: 9999px;
   --radius-modify: var(--radius-sm);
   --radius-contain: var(--radius-xs);
-  /* r-bridge — the "between" radius for adjacency cases: a floating
-     panel anchored to a commit-tier (pill) trigger reads disconnected
-     if the panel is r-contain (2 px) and over-sized if it mirrors the
-     pill at r-commit (9999 px). r-bridge sits at r-md (~6 px) to
-     visually pair pill triggers with their dropdown bodies (Menu panel
-     when its trigger Button is commit-tier). Use sparingly — most
-     surfaces should pick one of the three primary tiers above. */
+  /* r-bridge — the MIDDLE tier, at r-md (~6 px). Two cases earn it, both
+     of them "r-contain is too hard here, r-commit is too soft":
+
+       1. Adjacency. A floating panel anchored to a commit-tier (pill)
+          trigger reads disconnected at r-contain (2 px) and over-sized
+          if it mirrors the pill at r-commit. (Menu panel when its
+          trigger Button is commit-tier.)
+       2. Small tinted content surfaces. Optical radius scales with the
+          area it turns: 2 px on a 600 px Card reads as a precise edge,
+          the same 2 px on a ~200 px chat bubble reads as a rectangle.
+          A bubble is content, not architecture — it takes the middle
+          tier. (ChatMessage bubble.)
+
+     Still not a free-for-all: everything that IS a panel, dialog or
+     container belongs on one of the three primary tiers above. Reach
+     for bridge only when the surface is demonstrably too small for
+     r-contain to read as intentional. */
   --radius-bridge: var(--radius-md);
 
   /* Container Query Breakpoints */

package/dist/style/semantic.css

@@ -18,7 +18,25 @@
      above the one below — themes can differentiate them by color (e.g.
      cream → lighter cream → near-white → white) or rely on shadows
      alone when the palette ceiling is reached (as in the neutral default
-     where base and overlay are both white). */
+     where base and overlay are both white).
+
+     LIGHT-MODE SPREAD (2026-07). In light mode `base` sits at the white
+     ceiling, so every other rung has to differentiate DOWNWARD — and the
+     ramp gave it almost nothing to work with: quiet/elevated were ΔL 0.01
+     and 0.02 from base, against 0.03 and 0.08 in dark mode. A tinted
+     in-flow surface with no border and no shadow was therefore effectively
+     invisible in light mode, which is why components kept reaching for a
+     border just to make a surface visible at all (the chat bubble, the
+     table-cell progress track). Fixed at the ramp rather than per token —
+     `neutral-25` 0.99 → 0.985 and `neutral-50` 0.98 → 0.965 — so quiet,
+     elevated and subtle all gain spread without any semantic moving and
+     without a new token landing on an occupied value. All five themes share
+     those L values (only the hue differs), so the change reaches every
+     theme at once. Measured: text-tertiary on the new elevated is 11.32:1,
+     far above AA; style/contrast.test.ts is the gate. Guarded below by
+     style/semantic.test.ts, which asserts the reading surfaces stay
+     mutually distinct in BOTH modes — the failure mode here is silent, a
+     collapsed rung looks exactly like a working one in a screenshot. */
   /* L·1 — base: the page itself. Content, cards, and reading surfaces
      sit at this level. */
   --color-surface-base: light-dark(var(--color-neutral-0), var(--color-neutral-900));
@@ -31,7 +49,22 @@
   /* L·3 — overlay: highest surfaces (Dialog, Drawer, Sheet, Toast).
      Full shadow + backdrop dimming. */
   --color-surface-overlay: light-dark(var(--color-neutral-0), var(--color-neutral-850));
+  /* `surface-hover` / `-active` are the hover/press steps for elements resting
+     on a READING surface (base/quiet/elevated) — a menu item, a table row.
+     `surface-interactive` is a resting FILL one step in from the page (a filled
+     Input, a Slider track, the Tab list). Those two ladders start at different
+     rungs, so they need their own hover step: `surface-interactive` already sits
+     at neutral-100, which is exactly where `surface-hover` lands in light mode —
+     `bg-surface-interactive hover:bg-surface-hover` was a silent no-op, and in
+     dark mode `surface-active` collapses onto `surface-interactive` the same
+     way. `-interactive-hover` continues the fill's own ladder: one step further
+     from the page in light, one step toward the light in dark. Guarded by
+     style/semantic.test.ts so the pair can never collapse again. */
   --color-surface-interactive: light-dark(var(--color-neutral-100), var(--color-neutral-700));
+  --color-surface-interactive-hover: light-dark(
+    var(--color-neutral-200),
+    var(--color-neutral-650)
+  );
   --color-surface-hover: light-dark(var(--color-neutral-100), var(--color-neutral-750));
   --color-surface-active: light-dark(var(--color-neutral-200), var(--color-neutral-700));
   --color-surface-disabled: light-dark(var(--color-neutral-100), var(--color-neutral-800));
@@ -61,7 +94,21 @@
   --color-text-secondary: light-dark(var(--color-neutral-700), var(--color-neutral-300));
   --color-text-tertiary: light-dark(var(--color-neutral-600), var(--color-neutral-300));
   --color-text-quaternary: light-dark(var(--color-neutral-500), var(--color-neutral-400));
-  --color-text-disabled: light-dark(var(--color-neutral-300), var(--color-neutral-600));
+  /* Disabled text — the same stop in both modes. WCAG 1.4.3 exempts inactive
+     controls, so the old value was not a violation, but at neutral-300 / -600 it
+     measured roughly 1.5:1 in light and 2:1 in dark: a disabled field's label is
+     the one part that still has to say what the field IS, and it was effectively
+     invisible. Now held to the 3:1 UI floor by style/contrast.test.ts across
+     every theme × mode × reading surface plus the disabled fill — that test is
+     the number, not this comment.
+
+     Deliberately still the weakest rung of the text ramp, so "disabled" stays
+     legible without stopping being a signal. Two consequences, both accepted:
+     it shares its light-mode value with text-quaternary (two roles, not two
+     steps of one ladder — but see the Calendar entry in technical-debt, where
+     they meet), and the floor covers the token alone, not what a component
+     composes on top of it (an `opacity-*` wrapper can undo it). */
+  --color-text-disabled: light-dark(var(--color-neutral-500), var(--color-neutral-500));
   /* The on-colors below pair text with a *fill* rather than a surface.
      text-on-dark and text-on-primary answer fills that are dark in light
      mode and light in dark mode, so the label has to travel the opposite

package/dist/style/themes/forest.css

@@ -41,8 +41,8 @@
    * contrast stays unchanged. surface-*, text-* and border-* pick this up
    * automatically through semantic.css.
    */
-  --color-neutral-25: oklch(0.99 0.002 150);
-  --color-neutral-50: oklch(0.98 0.005 150);
+  --color-neutral-25: oklch(0.985 0.003 150);
+  --color-neutral-50: oklch(0.965 0.006 150);
   --color-neutral-100: oklch(0.95 0.008 150);
   --color-neutral-200: oklch(0.89 0.012 150);
   --color-neutral-300: oklch(0.83 0.014 150);

package/dist/style/themes/neutral.css

@@ -54,8 +54,8 @@
    * contrast stays unchanged. surface-*, text-* and border-* pick this up
    * automatically through semantic.css.
    */
-  --color-neutral-25: oklch(0.99 0 0);
-  --color-neutral-50: oklch(0.98 0 0);
+  --color-neutral-25: oklch(0.985 0 0);
+  --color-neutral-50: oklch(0.965 0 0);
   --color-neutral-100: oklch(0.95 0 0);
   --color-neutral-200: oklch(0.89 0 0);
   --color-neutral-300: oklch(0.83 0 0);

package/dist/style/themes/ocean.css

@@ -45,8 +45,8 @@
    * hue shifts — so WCAG contrast stays unchanged. surface-*, text-* and
    * border-* pick this up automatically through semantic.css.
    */
-  --color-neutral-25: oklch(0.99 0.002 220);
-  --color-neutral-50: oklch(0.98 0.005 220);
+  --color-neutral-25: oklch(0.985 0.003 220);
+  --color-neutral-50: oklch(0.965 0.006 220);
   --color-neutral-100: oklch(0.95 0.008 220);
   --color-neutral-200: oklch(0.89 0.012 220);
   --color-neutral-300: oklch(0.83 0.014 220);

package/dist/style/themes/rose.css

@@ -41,8 +41,8 @@
    * stays unchanged. surface-*, text-* and border-* pick this up
    * automatically through semantic.css.
    */
-  --color-neutral-25: oklch(0.99 0.002 350);
-  --color-neutral-50: oklch(0.98 0.005 350);
+  --color-neutral-25: oklch(0.985 0.003 350);
+  --color-neutral-50: oklch(0.965 0.006 350);
   --color-neutral-100: oklch(0.95 0.008 350);
   --color-neutral-200: oklch(0.89 0.012 350);
   --color-neutral-300: oklch(0.83 0.014 350);

package/dist/style/themes/sunset.css

@@ -41,8 +41,8 @@
    * contrast stays unchanged. surface-*, text-* and border-* pick this up
    * automatically through semantic.css; no per-token overrides needed.
    */
-  --color-neutral-25: oklch(0.99 0.002 50);
-  --color-neutral-50: oklch(0.98 0.005 50);
+  --color-neutral-25: oklch(0.985 0.003 50);
+  --color-neutral-50: oklch(0.965 0.006 50);
   --color-neutral-100: oklch(0.95 0.008 50);
   --color-neutral-200: oklch(0.89 0.012 50);
   --color-neutral-300: oklch(0.83 0.014 50);

package/dist/utils/figma-token-export.js

@@ -21,8 +21,8 @@
 const foundationColors = {
     neutral: {
         '0': 'oklch(1 0 0)',
-        '25': 'oklch(0.99 0.002 240)',
-        '50': 'oklch(0.98 0.005 240)',
+        '25': 'oklch(0.985 0.003 240)',
+        '50': 'oklch(0.965 0.006 240)',
         '100': 'oklch(0.95 0.008 240)',
         '200': 'oklch(0.89 0.012 240)',
         '300': 'oklch(0.83 0.014 240)',
@@ -139,6 +139,10 @@ const semanticTokens = {
         elevated: { value: '{color.neutral.50}', description: 'L2 — lifted surfaces (popover, menu)' },
         overlay: { value: '{color.neutral.0}', description: 'L3 — dialog/drawer/toast background' },
         interactive: { value: '{color.neutral.100}', description: 'Interactive control background' },
+        'interactive-hover': {
+            value: '{color.neutral.200}',
+            description: 'Hover step for an interactive control fill'
+        },
         hover: { value: '{color.neutral.100}', description: 'Hover state background' },
         active: { value: '{color.neutral.200}', description: 'Active/pressed state background' },
         disabled: { value: '{color.neutral.100}', description: 'Disabled surface' },
@@ -152,7 +156,7 @@ const semanticTokens = {
         secondary: { value: '{color.neutral.700}', description: 'Secondary text' },
         tertiary: { value: '{color.neutral.600}', description: 'Tertiary text (WCAG AA on base)' },
         quaternary: { value: '{color.neutral.500}', description: 'Quaternary text (lowest emphasis)' },
-        disabled: { value: '{color.neutral.300}', description: 'Disabled text' },
+        disabled: { value: '{color.neutral.500}', description: 'Disabled text' },
         'on-dark': { value: '{color.neutral.0}', description: 'Text on dark surfaces' },
         'on-primary': { value: '{color.neutral.0}', description: 'Text on primary color bg' },
         'on-warning': {

package/dist/utils/persistent-state.svelte.d.ts

@@ -13,15 +13,39 @@ export interface PersistentStateConfig<T> {
 /**
  * Create a persistent state that automatically syncs with storage
  * Uses Svelte 5 $state() for reactivity
+ *
+ * Besides `value`, the returned object exposes `hasStoredValue` — whether an
+ * entry for this key exists in storage. That is what lets a consumer tell a
+ * *stored empty* value (`[]`, `''`, `null` — the user cleared it) from *nothing
+ * stored at all*, so a cleared state can win over a default/seed instead of
+ * being re-applied on every load. Two rules keep that signal meaningful: a save
+ * that would not change the stored bytes is skipped, and an instance nobody
+ * wrote to never creates an entry for its own default (so `reset()` is not
+ * undone by the auto-save, and untouched state stays out of storage). Writing
+ * the default *back* — clearing — is a real write and does create the entry.
+ *
+ * Values must round-trip through the configured `serialize`/`deserialize`;
+ * `Set`/`Map` do not under the `JSON.stringify` default (they serialize to
+ * `{}`), so pass converting functions or store plain arrays/objects.
  */
 export declare function createPersistentState<T>(config: PersistentStateConfig<T>): {
     value: T;
+    /**
+     * Whether storage currently holds an entry for this key: `true` when
+     * construction (or `reload()`) found a parseable entry, and after a write
+     * actually reached storage; `false` when the key was absent or corrupt,
+     * after `reset()`, and always without a working storage (SSR, private
+     * mode). Use it to distinguish a stored empty value from an absent one.
+     */
+    readonly hasStoredValue: boolean;
     /**
      * Reset to default value and clear storage
      */
     reset(): void;
     /**
-     * Force immediate save (bypasses debounce)
+     * Force immediate save (bypasses debounce). A no-op when storage already
+     * holds exactly this value, and — like the auto-save — when the instance
+     * was never written to and still holds its default.
      */
     forceSave(): void;
     /**