@urbicon-ui/blocks 6.24.0 → 6.25.0

package/dist/primitives/Popover/popover.variants.js

@@ -1,9 +1,44 @@
 import { tv } from '../../utils/variants.js';
+/**
+ * CSS-native enter/exit motion for the floating panel (ACC-3 rest), keyed on
+ * the `data-state` attribute Popover always stamps. Kept as its own fragment
+ * because two call sites need exactly these classes: `popoverVariants.base`
+ * below, and Menu — which renders its inner Popover `unstyled` (to avoid a
+ * double surface) and re-applies the fragment via Popover's `class` prop.
+ *
+ * How the two halves work:
+ * - **Enter** — the panel un-hides via `showPopover()` (top layer) or a
+ *   `display` flip (in-place mode), so a plain transition has no before-state;
+ *   `starting:` (`@starting-style`) supplies it.
+ * - **Exit** — `hidePopover()` / a native light dismiss yank the panel to
+ *   `display: none` in the same style recalc that flips `data-state`;
+ *   `transition-discrete` (`transition-behavior: allow-discrete`) on
+ *   `display`/`overlay` keeps it painted (and in the top layer) until the
+ *   fade lands. Popover lags the children-teardown to match — see the
+ *   exit-motion block in Popover.svelte.
+ *
+ * Browsers without `@starting-style`/`allow-discrete` simply skip the motion
+ * and keep today's instant toggle. Duration/easing resolve through the
+ * `--blocks-popover-*` tokens (interaction.css), which reduced motion
+ * collapses to 1ms; `motion-reduce:duration-[1ms]` guards the inline
+ * per-instance override path, which can't see the media query.
+ */
+export const popoverMotion = [
+    'transition-[opacity,scale,display,overlay] transition-discrete',
+    'duration-[var(--blocks-popover-duration)] ease-[var(--blocks-popover-easing)]',
+    'motion-reduce:duration-[1ms]',
+    // pointer-events-none while closed: during the exit fade the children are
+    // still mounted and painted — without this, a quick click on the fading
+    // panel would fire consumer handlers from a visually dismissed surface.
+    'data-[state=closed]:opacity-0 data-[state=closed]:scale-[0.98] data-[state=closed]:pointer-events-none',
+    'starting:data-[state=open]:opacity-0 starting:data-[state=open]:scale-[0.98]'
+].join(' ');
 export const popoverVariants = tv({
     // tier: contain — floating panel surface.
     base: [
         'bg-surface-elevated border border-border-hairline rounded-contain',
         'shadow-[var(--blocks-shadow-md)] backdrop-blur-sm',
+        popoverMotion,
         // `calc(100dvh-4rem)` is the static design cap; Floating UI's `size`
         // middleware (via useFloatingPanel) narrows it to the room actually left
         // between the anchor and the visual viewport edge through

package/dist/primitives/Progress/progress.variants.js

@@ -35,7 +35,7 @@ export const progressVariants = tv({
             xs: {
                 track: 'h-1',
                 fill: 'h-1',
-                circularLabel: 'text-[10px]'
+                circularLabel: 'text-3xs'
             },
             sm: {
                 track: 'h-1.5',

package/dist/primitives/RadioGroup/radioGroup.variants.js

@@ -66,7 +66,7 @@ export const radioItemVariants = tv({
                 indicator: 'w-3.5 h-3.5 mt-px',
                 dot: 'w-1.5 h-1.5',
                 label: 'text-xs',
-                description: 'text-[10px]'
+                description: 'text-3xs'
             },
             sm: {
                 item: 'gap-2',

package/dist/primitives/Select/index.d.ts

@@ -256,7 +256,14 @@ interface SelectBaseProps<T extends SelectValue = string> extends Omit<SelectVar
      * and make the custom look reusable across the project.
      */
     preset?: string;
-    /** Explicit `id` for the component. Auto-generated if omitted. */
+    /**
+     * Explicit `id` for the component. Auto-generated if omitted.
+     *
+     * The id lands on the component's wrapper, which is not a labelable element.
+     * The focusable trigger is derived from it as `` `${id}-trigger` `` — that is
+     * the id an external `<label for>` has to address, since a `for` pointing at
+     * the wrapper focuses nothing.
+     */
     id?: string;
 }
 /**

package/dist/primitives/Slider/Slider.svelte

@@ -35,6 +35,7 @@
     slotClasses: slotClassesProp = {},
     preset,
     'aria-describedby': ariaDescribedby,
+    'aria-labelledby': ariaLabelledby,
     ...restProps
   }: SliderProps = $props();
 
@@ -53,6 +54,8 @@
     disabled
   }));
   const statusId = `${uid}-status`;
+  const minLabelId = `${uid}-min-label`;
+  const maxLabelId = `${uid}-max-label`;
 
   let trackRef = $state<HTMLDivElement>();
   let dragging = $state<'single' | 'start' | 'end' | null>(null);
@@ -251,6 +254,17 @@
       .join(' ') || undefined
   );
 
+  // `aria-labelledby` has the same reach problem as `aria-describedby` above:
+  // restProps land on the roleless wrapper div, so an external visible label
+  // would never name the focusable thumbs. On the range arm one external label
+  // would name both thumbs identically ("Padding" / "Padding"), so it is
+  // composed with a visually-hidden minimum/maximum qualifier —
+  // aria-labelledby concatenates its references in order, yielding
+  // "Padding Minimum" / "Padding Maximum" and preserving the distinction the
+  // `label`-prop arm gets for free.
+  const startLabelledBy = $derived(ariaLabelledby ? `${ariaLabelledby} ${minLabelId}` : undefined);
+  const endLabelledBy = $derived(ariaLabelledby ? `${ariaLabelledby} ${maxLabelId}` : undefined);
+
   $effect(() => {
     if (trackRef && mint && mint !== 'none' && !disabled) {
       return mintRegistry.apply(trackRef, mint);
@@ -429,13 +443,22 @@
     {/if}
 
     {#if range}
+      {#if ariaLabelledby}
+        <span id={minLabelId} class="sr-only">{bt('accessibility.minimum') || 'Minimum'}</span>
+        <span id={maxLabelId} class="sr-only">{bt('accessibility.maximum') || 'Maximum'}</span>
+      {/if}
       <div
         role="slider"
         tabindex={disabled ? -1 : 0}
         aria-valuemin={min}
         aria-valuemax={rangeValue[1]}
         aria-valuenow={rangeValue[0]}
-        aria-label={label ? `${label} minimum` : bt('accessibility.minimum') || 'Minimum'}
+        aria-labelledby={startLabelledBy}
+        aria-label={startLabelledBy
+          ? undefined
+          : label
+            ? `${label} minimum`
+            : bt('accessibility.minimum') || 'Minimum'}
         aria-describedby={describedBy}
         aria-disabled={disabled || undefined}
         class={unstyled ? (slotClasses?.thumb ?? '') : styles.thumb({ class: slotClasses?.thumb })}
@@ -449,7 +472,12 @@
         aria-valuemin={rangeValue[0]}
         aria-valuemax={max}
         aria-valuenow={rangeValue[1]}
-        aria-label={label ? `${label} maximum` : bt('accessibility.maximum') || 'Maximum'}
+        aria-labelledby={endLabelledBy}
+        aria-label={endLabelledBy
+          ? undefined
+          : label
+            ? `${label} maximum`
+            : bt('accessibility.maximum') || 'Maximum'}
         aria-describedby={describedBy}
         aria-disabled={disabled || undefined}
         class={unstyled ? (slotClasses?.thumb ?? '') : styles.thumb({ class: slotClasses?.thumb })}
@@ -464,7 +492,8 @@
         aria-valuemin={min}
         aria-valuemax={max}
         aria-valuenow={singleValue}
-        aria-label={label || bt('accessibility.slider') || 'Slider'}
+        aria-labelledby={ariaLabelledby}
+        aria-label={ariaLabelledby ? undefined : label || bt('accessibility.slider') || 'Slider'}
         aria-describedby={describedBy}
         aria-disabled={disabled || undefined}
         class={unstyled ? (slotClasses?.thumb ?? '') : styles.thumb({ class: slotClasses?.thumb })}

package/dist/primitives/Stepper/stepper.variants.js

@@ -68,7 +68,7 @@ export const stepperVariants = tv({
                 indicator: 'size-7 text-xs',
                 step: 'gap-2',
                 label: 'text-xs',
-                description: 'text-[11px]',
+                description: 'text-2xs',
                 content: 'text-sm',
                 indicatorColumn: 'w-7'
             },

package/dist/primitives/Textarea/Textarea.svelte

@@ -29,6 +29,7 @@
     slotClasses: slotClassesProp = {},
     preset,
     oninput: userOnInput,
+    id: idProp,
     'aria-describedby': ariaDescribedby,
     ...restProps
   }: TextareaProps = $props();
@@ -42,9 +43,12 @@
   let textareaRef = $state<HTMLTextAreaElement>();
 
   // ARIA wiring is shared with every form primitive — see XC-2.
+  // A consumer-supplied `id` wins over the generated one, so an external
+  // `<label for>` can address the `<textarea>` (mirrors the Input role model).
   const propsId = $props.id();
+  const fieldId = $derived(idProp ?? `textarea-${propsId}`);
   const ff = useFormField(() => ({
-    fieldId: `textarea-${propsId}`,
+    fieldId,
     helper,
     error,
     required,

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

@@ -26,7 +26,16 @@ export const tooltipVariants = tv({
             // guards the inline-override path (an inline duration bypasses the token that
             // reduced-motion collapses to 1ms). The default easing token resolves to
             // Tailwind's implicit transition curve, so the resting fade is unchanged.
-            'transition-opacity duration-[var(--blocks-tooltip-duration)] ease-[var(--blocks-tooltip-easing)]',
+            //
+            // display/overlay + `transition-discrete` and the `starting:` before-state
+            // are what make the fade actually PLAY in top-layer mode (same mechanism
+            // as popoverMotion): without them, showPopover() reveals the chip with no
+            // before-state (enter pops to opacity 1) and hidePopover() yanks it to
+            // display:none in the same recalc (exit never paints). Verified 2026-07-14
+            // — the original transition-opacity fade only ever ran in the rare
+            // in-dialog fallback, where visibility is purely opacity-driven.
+            'transition-[opacity,display,overlay] transition-discrete',
+            'duration-[var(--blocks-tooltip-duration)] ease-[var(--blocks-tooltip-easing)]',
             'motion-reduce:duration-[1ms]',
             'bg-surface-inverted text-text-inverted'
         ],
@@ -34,7 +43,9 @@ export const tooltipVariants = tv({
     },
     variants: {
         open: {
-            true: { base: 'opacity-100' },
+            // `starting:` supplies the @starting-style before-state for the frame
+            // showPopover() first renders the chip — the enter half of the fade.
+            true: { base: 'opacity-100 starting:opacity-0' },
             false: { base: 'opacity-0' }
         },
         intent: {

package/dist/style/foundation.css

@@ -53,10 +53,19 @@
   --color-warm-neutral-950: oklch(0.12 0.006 45);
 
   /* Darkened *-500 / *-600 / *-700 so text-on-primary (white) passes WCAG
-     AA (4.5:1) on the solid intent backgrounds. Previous values had
+     AA (4.5:1) on the solid intent backgrounds **in light mode**, where
+     --color-<intent> resolves to the -500/-600 shades. Previous values had
      L=0.65 which produced ~3:1 contrast — below AA. Warning keeps its
      yellow hue at L=0.75 because it pairs with text-on-surface (dark),
-     not white. */
+     not white.
+
+     Scope, measured (contrast.test.ts, 2026-07-14): this holds for light
+     mode only. In dark mode --color-<intent> resolves to the *lighter*
+     -400/-300/-200 shades while --color-text-on-primary stays white, so
+     every filled intent lands at 1.5–4.1:1. That is a semantic.css issue
+     (text-on-primary is not mode-aware), not something these ramps can fix
+     — see the KNOWN SHORTFALLS block in contrast.test.ts. Do not "fix" it
+     by lightening these ramps; that would break light mode instead. */
   --color-success-50: oklch(0.95 0.03 140);
   --color-success-100: oklch(0.9 0.05 140);
   --color-success-200: oklch(0.82 0.08 140);
@@ -101,13 +110,31 @@
   --color-info-200: oklch(0.84 0.075 220);
   --color-info-300: oklch(0.76 0.105 220);
   --color-info-400: oklch(0.66 0.13 220);
-  --color-info-500: oklch(0.55 0.14 220);
+  /* L=0.54, not 0.55: hue 220 is luminous enough that 0.55 measures 4.41:1
+     against text-on-primary (white) — below AA, despite the promise above.
+     0.54 is the smallest step that clears it (4.58:1) and keeps the ramp's
+     0.12 step down from info-400. Guarded by contrast.test.ts. */
+  --color-info-500: oklch(0.54 0.14 220);
   --color-info-600: oklch(0.48 0.13 220);
   --color-info-700: oklch(0.4 0.11 220);
   --color-info-800: oklch(0.32 0.09 220);
   --color-info-900: oklch(0.24 0.07 220);
   --color-info-950: oklch(0.16 0.05 220);
 
+  /* Sub-xs Type Scale — extends Tailwind's own `--text-*` namespace downwards.
+     Tailwind bottoms out at --text-xs (12px), but dense data marks (chart axis
+     labels, mini-calendar day cells, kbd hints) need 10–11px. Defining them here
+     rather than hardcoding `text-[11px]` at the call site is what makes those
+     sizes reachable by a consumer's own @theme override.
+
+     Deliberately size-only: NO paired `--text-*--line-height`. Tailwind emits
+     `line-height` for a scale entry only when the paired key exists, so adding
+     one would inject a line-height into every call site that today inherits it
+     from the cascade — a rendering change, not a refactor. Consumers who want
+     one can add the paired key in their own @theme; the utility picks it up. */
+  --text-2xs: 0.6875rem;
+  --text-3xs: 0.625rem;
+
   /* Border Radius Scale — physical sizes */
   --radius-xs: 0.125rem;
   --radius-sm: 0.25rem;

package/dist/style/interaction.css

@@ -98,8 +98,8 @@
      transitions, so they read these through the JS mirror in
      `utils/overlay-tokens.ts` (`getOverlayMotion`) — Svelte transitions need
      numeric input. Tooltip runs a deliberately faster CSS opacity fade off its
-     own `--blocks-tooltip-*` tokens below; Popover has no enter/exit motion yet
-     (ACC-3 follow-up).
+     own `--blocks-tooltip-*` tokens below; Popover (and Menu through it) runs a
+     CSS-native fade/scale off the `--blocks-popover-*` tokens below.
 
      Override globally with a `BlocksProvider` style block, or per instance via
      the component's `transitionDuration` / `transitionEasing` props.
@@ -130,6 +130,23 @@
   --blocks-tooltip-duration: var(--blocks-duration-fast);
   --blocks-tooltip-easing: var(--blocks-ease-confident);
 
+  /* === POPOVER MOTION TOKENS (ACC-3 rest) ===
+     The CSS-native enter/exit fade+scale for Popover (and Menu, which passes
+     the same motion fragment to its inner Popover). Anchored panels should
+     feel snappier than the 200ms modal overlays but calmer than an instant
+     toggle, so they share the tooltip's `fast`/`confident` pairing. Enter is
+     driven by `@starting-style` (the panel un-hides via `showPopover()`, so a
+     plain transition has no before-state); exit relies on
+     `transition-behavior: allow-discrete` on `display`/`overlay` to keep the
+     panel painted in the top layer while it fades. Both default through
+     `--blocks-duration-fast`, so `prefers-reduced-motion` below collapses them
+     to 1ms for free. Override globally here, or per instance via Popover's
+     `transitionDuration` / `transitionEasing` props (which set these inline +
+     carry a `motion-reduce` guard, since an inline duration can't see the
+     media query). */
+  --blocks-popover-duration: var(--blocks-duration-fast);
+  --blocks-popover-easing: var(--blocks-ease-confident);
+
   /* === COLLAPSE ANIMATION TOKENS (ACC-3) ===
      The CSS-driven grid-template-rows collapse shared by Accordion +
      Collapsible (and their chevron spin). Default to the normal/smooth

package/dist/style/semantic.css

@@ -54,8 +54,31 @@
   --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));
+  /* The two on-colors below pair text with a *fill* rather than a surface.
+     Their fills are dark in light mode and light in dark mode, so the label
+     has to travel the opposite way — white, then near-black. They are
+     deliberately NOT aliased to one another (`text-on-primary: var(
+     --color-text-on-dark)`), even though they carry the same value today —
+     they answer to different fills and must stay independently overridable:
+
+       - text-on-dark is the partner of the avatar identity palette, whose 12
+         slots hold ONE lightness per mode (0.45 / 0.72) by construction.
+       - text-on-primary is the partner of the intent fills, whose ramps every
+         theme re-tunes, and which move again on hover/active.
+
+     Aliasing would couple them asymmetrically: a consumer re-tuning the avatar
+     palette's on-color would silently repaint every filled Button/Badge label.
+     Their equality is a consequence of both fill families straddling the same
+     lightness midpoint — not a definition. */
   --color-text-on-dark: light-dark(var(--color-neutral-0), var(--color-neutral-900));
-  --color-text-on-primary: var(--color-neutral-0);
+  /* Dark mode pairs the *lighter* -400/-500 intent fills with dark text (the
+     Material-3 `onPrimary` pattern). White here was unconditional until
+     2026-07-14, which put 125 of the 126 dark-mode intent fills under WCAG AA
+     — down to 1.51:1, and getting *worse* on press. The mode-aware branch
+     clears all 108 fills this token governs; `warning` is not one of them (it
+     pairs with text-on-surface and is still under AA in dark mode — see the
+     KNOWN SHORTFALLS block in style/contrast.test.ts, which guards all of it). */
+  --color-text-on-primary: light-dark(var(--color-neutral-0), var(--color-neutral-900));
   --color-text-on-surface: light-dark(var(--color-neutral-900), var(--color-neutral-100));
 
   /* === PRIMARY INTENT ===
@@ -152,6 +175,54 @@
   --color-chart-5: light-dark(var(--color-info-500), var(--color-info-400));
   --color-chart-6: light-dark(var(--color-danger-500), var(--color-danger-400));
 
+  /* === AVATAR IDENTITY PALETTE ===
+     An *unordered* identity palette: Avatar's `randomColor` hashes a name to a
+     fixed slot, so the same person always keeps the same hue. Deliberately NOT
+     the chart palette and NOT the intent tokens:
+
+       - chart-* only has 6 slots and derives from the intent ramps, so a brand
+         that retunes `secondary` would silently reshuffle people's identities.
+         Its dark values are the *-400 tints (L≈0.66) — light enough that white
+         initials drop to ~2.6:1, below AA. Charts colour marks; avatars carry
+         text on top, which is a different contrast contract.
+       - intent tokens are semantic (a person is not "danger").
+
+     Construction: a single lightness per mode, 12 hues at an even 30° spacing.
+     Because OKLCH lightness is perceptual, holding L constant means every slot
+     shares one guaranteed contrast partner — `--color-text-on-dark`, which
+     flips white → neutral-900 with the mode exactly as these fills flip dark →
+     light. So legibility is a property of the construction, not 12 separate
+     checks. Even spacing also beats the 15 hardcoded hex values this replaced,
+     which clustered (red/orange/amber/yellow within ~20°) and blurred when
+     avatars sat side by side.
+
+     L=0.45 (light) / L=0.72 (dark) mirror the foundation ramps' *-700 / *-300
+     steps, so the palette reads as part of the same chassis. Rebrand by
+     overriding these 12 tokens; the text partner follows automatically. */
+  --color-avatar-1: light-dark(oklch(0.45 0.13 25), oklch(0.72 0.12 25));
+  --color-avatar-2: light-dark(oklch(0.45 0.13 55), oklch(0.72 0.12 55));
+  --color-avatar-3: light-dark(oklch(0.45 0.13 85), oklch(0.72 0.12 85));
+  --color-avatar-4: light-dark(oklch(0.45 0.13 115), oklch(0.72 0.12 115));
+  --color-avatar-5: light-dark(oklch(0.45 0.13 145), oklch(0.72 0.12 145));
+  --color-avatar-6: light-dark(oklch(0.45 0.13 175), oklch(0.72 0.12 175));
+  --color-avatar-7: light-dark(oklch(0.45 0.13 205), oklch(0.72 0.12 205));
+  --color-avatar-8: light-dark(oklch(0.45 0.13 235), oklch(0.72 0.12 235));
+  --color-avatar-9: light-dark(oklch(0.45 0.13 265), oklch(0.72 0.12 265));
+  --color-avatar-10: light-dark(oklch(0.45 0.13 295), oklch(0.72 0.12 295));
+  --color-avatar-11: light-dark(oklch(0.45 0.13 325), oklch(0.72 0.12 325));
+  --color-avatar-12: light-dark(oklch(0.45 0.13 355), oklch(0.72 0.12 355));
+
+  /* === LIVE / "NOW" ACCENT ===
+     Single-purpose accent for live/now markers — the Calendar current-time
+     line and dot, and future live/recording indicators. Red is the
+     convention (Google Calendar et al.), but the *purpose* is not `danger`:
+     a now-line states "you are here", not "something is wrong", and the two
+     must stay independently themeable. Defaults ride the danger foundation
+     ramp, so dark mode and per-theme danger re-tunes flow through
+     automatically; override `--color-live` alone to restyle live indicators
+     without touching error styling. */
+  --color-live: light-dark(var(--color-danger-500), var(--color-danger-400));
+
   /* === BORDERS ===
      border-hairline is the quietest tier — structural
      trennlinien (row dividers, Card header/footer separators, inline

package/dist/style/themes/neutral.css

@@ -17,7 +17,16 @@
   --color-primary-200: oklch(0.84 0.008 240);
   --color-primary-300: oklch(0.76 0.01 240);
   --color-primary-400: oklch(0.65 0.012 240);
-  --color-primary-500: oklch(0.53 0.012 240);
+  /* L 0.58, not the 0.53 this ramp's spacing would suggest: primary-500 is the
+     dark-mode `--color-primary` fill, and dark mode carries dark text on it
+     (`--color-text-on-primary`). At 0.53 this grey measured 3.74:1 against
+     neutral-900 — the one intent fill in the whole system that missed AA after
+     the on-color became mode-aware, because a desaturated mid-grey is the
+     hardest case: no lightness clears AA against BOTH white and neutral-900
+     (proved in style/contrast.test.ts). 0.58 is the lowest step on this
+     ramp's 0.01 grid that clears it (4.59:1; the true crossing is 0.574 =
+     4.50:1, i.e. no margin at all). Monotonicity holds (0.65 > 0.58 > 0.43). */
+  --color-primary-500: oklch(0.58 0.012 240);
   --color-primary-600: oklch(0.43 0.012 240);
   --color-primary-700: oklch(0.36 0.01 240);
   --color-primary-800: oklch(0.29 0.008 240);

package/dist/style/themes/ocean.css

@@ -26,7 +26,11 @@
   --color-secondary-200: oklch(0.82 0.08 190);
   --color-secondary-300: oklch(0.74 0.11 190);
   --color-secondary-400: oklch(0.66 0.13 190);
-  --color-secondary-500: oklch(0.55 0.12 190);
+  /* L=0.54, not the foundation ramp's 0.55: at hue 190 (teal) the same
+     lightness measures 4.39:1 against text-on-primary (white) — below AA.
+     Lightness is not contrast-neutral across hues in OKLCH. Guarded by
+     contrast.test.ts. */
+  --color-secondary-500: oklch(0.54 0.12 190);
   --color-secondary-600: oklch(0.48 0.12 190);
   --color-secondary-700: oklch(0.4 0.1 190);
   --color-secondary-800: oklch(0.32 0.08 190);

package/dist/utils/compose-handlers.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `composeHandlers` — run a component's own DOM event handler *and* a
+ * consumer-supplied one that arrived through `restProps`.
+ *
+ * ## Why this exists
+ *
+ * The library's `restProps` contract (see docs/COMPONENT-API-CONVENTIONS.md)
+ * spreads `{...restProps}` **first**, so the component's own attributes win: a
+ * consumer can't silently cancel state the component owns. Applied naively to
+ * event handlers that rule would go too far in the other direction — a
+ * `restProps`-first spread makes the component's `onkeydown` clobber the
+ * *consumer's*, which is just the original bug pointed the other way.
+ *
+ * Neither side should lose. Handlers are additive by nature (the DOM itself
+ * allows many listeners per event), so the component destructures the handler
+ * out of `restProps` and composes it: **internal first, consumer second**.
+ *
+ * ## Ordering: internal first
+ *
+ * 1. The component's behaviour is then unconditional — it cannot be skipped by
+ *    a consumer handler that throws, which is exactly what "internal wins"
+ *    has to mean for a dismiss/focus-trap path.
+ * 2. The consumer observes the event *after* the component reacted, so
+ *    `event.defaultPrevented` tells them whether the component claimed it
+ *    (e.g. Dialog preventDefaults `Escape` when it closes on it).
+ *
+ * ## `preventDefault` is deliberately NOT a veto
+ *
+ * The consumer's handler runs after the internal one, so calling
+ * `event.preventDefault()` there cannot suppress the component's behaviour —
+ * by design. Overloading `preventDefault` as "also disable this component's
+ * dismissal" would re-create the silent-disable bug through a different door:
+ * `preventDefault` has an established DOM meaning (suppress the *browser's*
+ * default action), and a consumer calling it for that reason would lose
+ * dismissal without ever asking to. Opting out of a behaviour is spelled with
+ * the named, discoverable prop that already exists for it — `closeOnEscape`,
+ * `closeOnBackdropClick` — not with a magic event side-effect.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   let { onkeydown: onkeydownProp, ...restProps }: Props = $props();
+ *   function handleKeydown(event: KeyboardEvent) { ... }
+ * </script>
+ *
+ * <dialog {...restProps} onkeydown={composeHandlers(handleKeydown, onkeydownProp)}>
+ * ```
+ */
+/**
+ * Structural mirror of svelte/elements' internal `EventHandler` type, which is
+ * declared there but not exported. Matching the shape keeps the composed result
+ * assignable to the `on*` props of `HTMLAttributes` (`MouseEventHandler<T>`,
+ * `KeyboardEventHandler<T>`, …).
+ */
+type DomEventHandler<TEvent extends Event, TElement extends EventTarget> = (event: TEvent & {
+    currentTarget: EventTarget & TElement;
+}) => unknown;
+/**
+ * Combine an internal handler with an optional consumer handler from `restProps`.
+ *
+ * The internal handler always runs first and always runs; the consumer handler
+ * runs afterwards when present. See the module doc for the ordering and
+ * `preventDefault` rationale.
+ *
+ * @param internal The component's own handler. Runs first, unconditionally.
+ * @param consumer The consumer's handler from `restProps`. May be `null`/`undefined`.
+ * @returns A handler assignable to the element's `on*` attribute.
+ */
+export declare function composeHandlers<TEvent extends Event, TElement extends EventTarget = Element>(internal: (event: TEvent & {
+    currentTarget: EventTarget & TElement;
+}) => unknown, consumer: DomEventHandler<TEvent, TElement> | null | undefined): DomEventHandler<TEvent, TElement>;
+export {};

package/dist/utils/compose-handlers.js

@@ -0,0 +1,65 @@
+/**
+ * `composeHandlers` — run a component's own DOM event handler *and* a
+ * consumer-supplied one that arrived through `restProps`.
+ *
+ * ## Why this exists
+ *
+ * The library's `restProps` contract (see docs/COMPONENT-API-CONVENTIONS.md)
+ * spreads `{...restProps}` **first**, so the component's own attributes win: a
+ * consumer can't silently cancel state the component owns. Applied naively to
+ * event handlers that rule would go too far in the other direction — a
+ * `restProps`-first spread makes the component's `onkeydown` clobber the
+ * *consumer's*, which is just the original bug pointed the other way.
+ *
+ * Neither side should lose. Handlers are additive by nature (the DOM itself
+ * allows many listeners per event), so the component destructures the handler
+ * out of `restProps` and composes it: **internal first, consumer second**.
+ *
+ * ## Ordering: internal first
+ *
+ * 1. The component's behaviour is then unconditional — it cannot be skipped by
+ *    a consumer handler that throws, which is exactly what "internal wins"
+ *    has to mean for a dismiss/focus-trap path.
+ * 2. The consumer observes the event *after* the component reacted, so
+ *    `event.defaultPrevented` tells them whether the component claimed it
+ *    (e.g. Dialog preventDefaults `Escape` when it closes on it).
+ *
+ * ## `preventDefault` is deliberately NOT a veto
+ *
+ * The consumer's handler runs after the internal one, so calling
+ * `event.preventDefault()` there cannot suppress the component's behaviour —
+ * by design. Overloading `preventDefault` as "also disable this component's
+ * dismissal" would re-create the silent-disable bug through a different door:
+ * `preventDefault` has an established DOM meaning (suppress the *browser's*
+ * default action), and a consumer calling it for that reason would lose
+ * dismissal without ever asking to. Opting out of a behaviour is spelled with
+ * the named, discoverable prop that already exists for it — `closeOnEscape`,
+ * `closeOnBackdropClick` — not with a magic event side-effect.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   let { onkeydown: onkeydownProp, ...restProps }: Props = $props();
+ *   function handleKeydown(event: KeyboardEvent) { ... }
+ * </script>
+ *
+ * <dialog {...restProps} onkeydown={composeHandlers(handleKeydown, onkeydownProp)}>
+ * ```
+ */
+/**
+ * Combine an internal handler with an optional consumer handler from `restProps`.
+ *
+ * The internal handler always runs first and always runs; the consumer handler
+ * runs afterwards when present. See the module doc for the ordering and
+ * `preventDefault` rationale.
+ *
+ * @param internal The component's own handler. Runs first, unconditionally.
+ * @param consumer The consumer's handler from `restProps`. May be `null`/`undefined`.
+ * @returns A handler assignable to the element's `on*` attribute.
+ */
+export function composeHandlers(internal, consumer) {
+    return (event) => {
+        internal(event);
+        consumer?.(event);
+    };
+}

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

@@ -123,7 +123,7 @@ const foundationColors = {
         '200': 'oklch(0.84 0.075 220)',
         '300': 'oklch(0.76 0.105 220)',
         '400': 'oklch(0.66 0.13 220)',
-        '500': 'oklch(0.55 0.14 220)',
+        '500': 'oklch(0.54 0.14 220)',
         '600': 'oklch(0.48 0.13 220)',
         '700': 'oklch(0.4 0.11 220)',
         '800': 'oklch(0.32 0.09 220)',