@urbicon-ui/blocks 6.24.0 → 6.25.0

package/README.md

@@ -32,6 +32,20 @@ All primitives and components support `unstyled` + `slotClasses` + `preset` for
 
 Components use a **custom `tv()` variant engine** (`src/lib/utils/variants.ts`, ~600 LoC, zero-dependency replacement for `tailwind-variants`). Design tokens live in `src/lib/style/` as a three-layer OKLCH system (foundation → semantic → interaction). See the [Architecture Overview](../../docs/ARCHITECTURE.md) for details.
 
+## Theming
+
+Import a shipped theme after the base styles — `neutral`, `ocean`, `forest`, `rose`, `sunset`:
+
+```css
+@import 'tailwindcss';
+@import '@urbicon-ui/blocks/style/index.css';
+@import '@urbicon-ui/blocks/style/themes/forest.css';
+```
+
+Rolling your own: **a brand colour alone is not a theme.** `surface-*`, `text-*` and `border-*` derive from the neutral chassis (`--color-neutral-*`), not from primary — so re-tint the chassis to your accent's temperature too, or the brand button ends up on cool blue-grey cards. Typography themes the same way (`--text-*`, `--font-*`) in the same `@theme` block.
+
+Full walkthrough: [/customization/themes](https://ui.urbicon.de/customization/themes) · canonical reference: `urbicon css-reference theming` (and `typography`).
+
 ## Mint System (Micro-Interactions)
 
 Opt-in micro-interactions. Call `registerDefaultMints()` at app startup, then use via prop:

package/dist/components/Calendar/CalendarTimeGrid.svelte

@@ -135,7 +135,8 @@
           <!-- Current time line -->
           {#if isToday && currentTimePercent !== null}
             <div class={slot('currentTimeLine')} style="top: {currentTimePercent}%;">
-              <div class="absolute -top-1 -left-1 size-2 rounded-full bg-red-500"></div>
+              <!-- Dot matches the line: the shared `live` ("now") accent, not danger. -->
+              <div class="absolute -top-1 -left-1 size-2 rounded-full bg-live"></div>
             </div>
           {/if}
         </div>

package/dist/components/Calendar/calendar.variants.js

@@ -114,7 +114,9 @@ export const calendarVariants = tv({
             'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50'
         ],
         allDayArea: ['border-b border-border-hairline'],
-        currentTimeLine: 'absolute left-0 right-0 z-10 pointer-events-none border-t-2 border-red-500',
+        // `live` is the dedicated "now" accent (red by convention, themes via
+        // --color-live) — deliberately not `danger`, which signals errors.
+        currentTimeLine: 'absolute left-0 right-0 z-10 pointer-events-none border-t-2 border-live',
         // Week time grid mode (replaces weekGrid when showTimeGrid)
         weekTimeLayout: ['w-full flex flex-col', 'border-t border-border-hairline'],
         // Event popover
@@ -191,7 +193,7 @@ export const calendarVariants = tv({
                 yearGrid: 'gap-1 p-1',
                 yearMonth: 'p-1 gap-0.5',
                 yearMonthTitle: 'text-xs mb-0.5',
-                yearMiniDay: 'text-[9px] size-3',
+                yearMiniDay: 'text-3xs size-3',
                 yearMiniDot: 'size-0.5',
                 weekGrid: 'gap-px',
                 weekColumn: 'min-h-16',
@@ -244,7 +246,7 @@ export const calendarVariants = tv({
                 yearGrid: 'gap-2 p-2',
                 yearMonth: 'p-2 gap-1',
                 yearMonthTitle: 'text-sm mb-1',
-                yearMiniDay: 'text-[10px] size-4',
+                yearMiniDay: 'text-3xs size-4',
                 yearMiniDot: 'size-1',
                 weekGrid: 'gap-px',
                 weekColumn: 'min-h-24',

package/dist/components/CommandPalette/CommandPalette.svelte

@@ -13,6 +13,7 @@
     emptyText: emptyTextProp,
     showFooter = true,
     open = $bindable(false),
+    query = $bindable(''),
     shortcut = 'mod+k',
     filter,
     onSelect,
@@ -32,7 +33,6 @@
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
 
-  let query = $state('');
   let selectedIndex = $state(0);
   let inputEl: HTMLInputElement | undefined = $state();
 
@@ -58,18 +58,25 @@
     return items.filter((item) => fn(item, query));
   });
 
+  /**
+   * Entries carry their index into `filtered` so the markup does not have to
+   * look it up per row — that was an `indexOf` per item, i.e. quadratic in the
+   * item count on every render.
+   */
+  type GroupEntry = { item: CommandPaletteItem; flatIdx: number };
+
   const grouped = $derived.by(() => {
-    const groups: { category: string; items: CommandPaletteItem[] }[] = [];
-    const seen: Record<string, CommandPaletteItem[]> = {};
-    for (const item of filtered) {
+    const groups: { category: string; entries: GroupEntry[] }[] = [];
+    const seen: Record<string, GroupEntry[]> = {};
+    filtered.forEach((item, flatIdx) => {
       const cat = item.category ?? '';
       if (!seen[cat]) {
-        const arr: CommandPaletteItem[] = [];
+        const arr: GroupEntry[] = [];
         seen[cat] = arr;
-        groups.push({ category: cat, items: arr });
+        groups.push({ category: cat, entries: arr });
       }
-      seen[cat].push(item);
-    }
+      seen[cat].push({ item, flatIdx });
+    });
     return groups;
   });
 
@@ -129,10 +136,6 @@
     }
   }
 
-  function getFlatIndex(item: CommandPaletteItem): number {
-    return filtered.indexOf(item);
-  }
-
   export function toggle() {
     setOpen(!open);
   }
@@ -251,8 +254,7 @@
               {group.category}
             </div>
           {/if}
-          {#each group.items as item (item.id ?? item.label)}
-            {@const flatIdx = getFlatIndex(item)}
+          {#each group.entries as { item, flatIdx } (item.id ?? item.label)}
             {@const isHighlighted = flatIdx === selectedIndex}
             {@const isDisabled = item.disabled ?? false}
             {#if customItem}
@@ -312,9 +314,23 @@
                 {/if}
                 <span
                   class={unstyled
-                    ? (slotClasses?.itemLabel ?? '')
-                    : styles.itemLabel({ class: slotClasses?.itemLabel })}>{item.label}</span
+                    ? (slotClasses?.itemText ?? '')
+                    : styles.itemText({ class: slotClasses?.itemText })}
                 >
+                  <span
+                    class={unstyled
+                      ? (slotClasses?.itemLabel ?? '')
+                      : styles.itemLabel({ class: slotClasses?.itemLabel })}>{item.label}</span
+                  >
+                  {#if item.excerpt}
+                    <span
+                      class={unstyled
+                        ? (slotClasses?.itemExcerpt ?? '')
+                        : styles.itemExcerpt({ class: slotClasses?.itemExcerpt })}
+                      >{item.excerpt}</span
+                    >
+                  {/if}
+                </span>
                 {#if item.shortcut}
                   <kbd
                     class={unstyled

package/dist/components/CommandPalette/CommandPalette.svelte.d.ts

@@ -3,6 +3,6 @@ declare const CommandPalette: import("svelte").Component<CommandPaletteProps, {
     toggle: () => void;
     show: () => void;
     hide: () => void;
-}, "open">;
+}, "open" | "query">;
 type CommandPalette = ReturnType<typeof CommandPalette>;
 export default CommandPalette;

package/dist/components/CommandPalette/commandPalette.variants.d.ts

@@ -62,11 +62,21 @@ export declare const commandPaletteVariants: ((props?: {
     } & {
         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;
+    itemText: (props?: ({
+        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;
     itemLabel: (props?: ({
         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;
+    itemExcerpt: (props?: ({
+        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;
     itemShortcut: (props?: ({
         size?: "sm" | "md" | "lg" | undefined;
     } & {

package/dist/components/CommandPalette/commandPalette.variants.js

@@ -16,9 +16,7 @@ export const commandPaletteVariants = tv({
         inputIcon: 'h-4 w-4 shrink-0 text-text-tertiary',
         clearButton: 'text-text-quaternary hover:text-text-secondary',
         list: 'max-h-72 overflow-y-auto p-1.5',
-        groupLabel: [
-            'px-2 py-1.5 text-[11px] font-semibold uppercase tracking-wide text-text-quaternary'
-        ],
+        groupLabel: ['px-2 py-1.5 text-2xs font-semibold uppercase tracking-wide text-text-quaternary'],
         // tier: modify — palette items are selectable actions.
         item: [
             'flex w-full items-center gap-3 rounded-modify px-3 py-2 text-sm',
@@ -28,20 +26,24 @@ export const commandPaletteVariants = tv({
         itemDefault: 'text-text-secondary hover:bg-surface-hover',
         itemDisabled: 'text-text-quaternary cursor-not-allowed opacity-50',
         itemIcon: 'h-4 w-4 shrink-0',
-        itemLabel: 'flex-1 text-left',
+        itemText: 'flex min-w-0 flex-1 flex-col items-start gap-0.5',
+        itemLabel: 'text-left',
+        // One line only: excerpts are prose around a search match and would
+        // otherwise reflow every row to a different height.
+        itemExcerpt: 'w-full truncate text-left text-2xs text-text-tertiary',
         itemShortcut: [
             'rounded border border-border-subtle bg-surface-subtle',
-            'px-1.5 py-0.5 font-mono text-[10px] text-text-quaternary'
+            'px-1.5 py-0.5 font-mono text-3xs text-text-quaternary'
         ],
         empty: 'py-8 text-center text-sm text-text-tertiary',
         footer: [
             'flex items-center gap-4 border-t border-border-hairline',
-            'px-4 py-2 text-[11px] text-text-quaternary'
+            'px-4 py-2 text-2xs text-text-quaternary'
         ],
         footerHint: 'flex items-center gap-1',
         kbd: [
             'rounded border border-border-subtle bg-surface-subtle',
-            'px-1 py-0.5 font-mono text-[10px]'
+            'px-1 py-0.5 font-mono text-3xs'
         ],
         separator: 'my-1'
     },

package/dist/components/CommandPalette/index.d.ts

@@ -18,6 +18,12 @@ export interface CommandPaletteItem {
     id?: string;
     /** Display text shown in the list. */
     label: string;
+    /**
+     * Secondary line rendered under the label, truncated to one line. Use it for
+     * context the label cannot carry — a description, or an excerpt around a
+     * search match.
+     */
+    excerpt?: string;
     /** Group header this item belongs to. Items with the same category are grouped together. */
     category?: string;
     /** Optional keyboard shortcut displayed on the right side. */
@@ -38,6 +44,8 @@ export interface CommandPaletteItem {
  *
  * @tag action
  * @related Dialog
+ * @related Menu
+ * @related Combobox
  *
  * @example
  * ```svelte
@@ -76,6 +84,17 @@ export interface CommandPaletteProps {
     showFooter?: boolean;
     /** Controls visibility. Supports `bind:open`. @default false */
     open?: boolean;
+    /**
+     * Current search text. Supports `bind:query`. Reset to `''` whenever the
+     * palette opens.
+     *
+     * Bind it to source `items` asynchronously — derive your results from the
+     * query and pass them back in via `items`, with `filter={() => true}` so the
+     * built-in label match does not filter them a second time.
+     *
+     * @default ''
+     */
+    query?: string;
     /**
      * Register a global keyboard shortcut that toggles the palette.
      * Set to `false` to disable. @default 'mod+k' (Cmd+K / Ctrl+K)

package/dist/components/CompositionBar/CompositionBar.svelte

@@ -318,7 +318,7 @@
               <span
                 aria-hidden="true"
                 class={[
-                  'pointer-events-none truncate px-1.5 text-[10px] font-medium tabular-nums',
+                  'pointer-events-none truncate px-1.5 text-3xs font-medium tabular-nums',
                   !unstyled && getOnColorClass(item)
                 ]
                   .filter(Boolean)

package/dist/components/CompositionBar/composition-bar.variants.js

@@ -71,7 +71,7 @@ export const compositionBarVariants = tv({
             sm: {
                 legendItem: 'text-xs',
                 legendDot: 'h-2 w-2',
-                tooltip: 'text-[11px]'
+                tooltip: 'text-2xs'
             },
             md: {
                 legendItem: 'text-sm',

package/dist/components/Planner/planner.variants.js

@@ -67,7 +67,7 @@ export const plannerVariants = tv({
                 headerTitle: 'text-sm',
                 navButton: 'h-7 w-7',
                 weekday: 'text-xs',
-                weekNumber: 'text-[0.65rem]',
+                weekNumber: 'text-3xs',
                 cellDate: 'text-xs h-5 min-w-5',
                 cellWeekday: 'text-xs',
                 cellItems: 'text-xs',

package/dist/components/Sankey/sankey.variants.js

@@ -14,7 +14,7 @@ export const sankeyVariants = tv({
             'fill-text-primary text-xs font-medium',
             'transition-[opacity] duration-[var(--blocks-duration-fast)]'
         ],
-        nodeValue: ['pointer-events-none select-none', 'fill-text-tertiary text-[10px] tabular-nums'],
+        nodeValue: ['pointer-events-none select-none', 'fill-text-tertiary text-3xs tabular-nums'],
         link: [
             'cursor-default fill-none',
             'transition-[opacity,stroke-opacity,stroke-width] duration-[var(--blocks-duration-fast)]',

package/dist/internal/charts/variants.js

@@ -17,7 +17,7 @@ export const chartVariants = tv({
         /** Tick marks. */
         axisTick: ['stroke-border-subtle'],
         /** Tick + category labels. */
-        axisLabel: ['fill-text-tertiary text-[10px] tabular-nums'],
+        axisLabel: ['fill-text-tertiary text-3xs tabular-nums'],
         /** Background gridlines. */
         grid: ['stroke-border-hairline'],
         /** Generic data mark (line path, area, point). */
@@ -29,7 +29,7 @@ export const chartVariants = tv({
         /** Donut center primary label. */
         centerLabel: ['fill-text-primary text-sm font-medium tabular-nums'],
         /** Donut center secondary label. */
-        centerSubLabel: ['fill-text-tertiary text-[10px]'],
+        centerSubLabel: ['fill-text-tertiary text-3xs'],
         /** Legend container (HTML). */
         legend: ['mt-2 flex flex-wrap items-center gap-x-4 gap-y-1.5', 'text-text-secondary text-xs'],
         /** One legend entry. */

package/dist/internal/date-grid/DateGridScaffold.svelte

@@ -142,8 +142,15 @@
   style="position: relative; overflow: hidden;"
   onmouseleave={() => ctx.setHoveredDate(null)}
   {@attach swipeable({
-    onSwipeLeft: () => ctx.navigate(1),
-    onSwipeRight: () => ctx.navigate(-1),
+    // Direction-gated like the header arrows: a swipe at the bound should be
+    // inert (no navDirection flip, no clamped no-op emit), matching the
+    // disabled arrow button for the same direction.
+    onSwipeLeft: () => {
+      if (ctx.canGoForward) ctx.navigate(1);
+    },
+    onSwipeRight: () => {
+      if (ctx.canGoBack) ctx.navigate(-1);
+    },
     enabled: swipeEnabled && !ctx.disabled
   })}
 >

package/dist/internal/date-grid/date-grid.svelte.d.ts

@@ -106,8 +106,10 @@ export declare class DateGridController {
     isRangeEnd(date: Date): boolean;
     isInSelectedRange(date: Date): boolean;
     isInPreviewRange(date: Date): boolean;
-    /** Step the view by `delta` units (months / weeks / days; range shifts by its
-     * own span in weeks). Emits the next reference date and visible range. */
+    /** Step the view by `delta` units (months / weeks / days; range slides its
+     * window by its own span in days). Every path clamps to [minDate, maxDate];
+     * the range window clamps span-preserving. Emits the next reference date and
+     * range (visible cell range, or the shifted window for `range`). */
     navigate(delta: number): void;
     /** Jump to today and focus it. Clamped to `[minDate, maxDate]`: the header Today
      * button gates itself on {@link canGoToToday} (a clamped "today" is not today, so

package/dist/internal/date-grid/date-grid.svelte.js

@@ -116,7 +116,18 @@ export class DateGridController {
             const { canGoBack, canGoForward } = clampMonth(referenceDate.getMonth(), referenceDate.getFullYear(), minDate, maxDate);
             return { canGoBack, canGoForward };
         }
-        // week/day/range: day-granular bounds against the visible edges.
+        if (view === 'range') {
+            // Range navigation slides the *explicit* window (partial shifts allowed —
+            // see the span-preserving clamp in navigate()), so gate on the window
+            // edges, not the week-padded visible cells: the padding may spill past a
+            // bound while the window itself can still move.
+            const { start, end } = this.#orderedRange(referenceDate);
+            return {
+                canGoBack: !minDate || start.getTime() > stripTime(minDate).getTime(),
+                canGoForward: !maxDate || end.getTime() < stripTime(maxDate).getTime()
+            };
+        }
+        // week/day: day-granular bounds against the visible edges.
         const canGoBack = !minDate || stripTime(this.rangeStart) > stripTime(minDate);
         const canGoForward = !maxDate || stripTime(this.rangeEnd) < stripTime(maxDate);
         return { canGoBack, canGoForward };
@@ -232,24 +243,38 @@ export class DateGridController {
         return isInRange(date, range.start, this.hoveredDate) && !isSameDay(date, range.start);
     }
     // ─── Actions ─────────────────────────────────────────────────────────────
-    /** Step the view by `delta` units (months / weeks / days; range shifts by its
-     * own span in weeks). Emits the next reference date and visible range. */
+    /** Step the view by `delta` units (months / weeks / days; range slides its
+     * window by its own span in days). Every path clamps to [minDate, maxDate];
+     * the range window clamps span-preserving. Emits the next reference date and
+     * range (visible cell range, or the shifted window for `range`). */
     navigate(delta) {
         if (delta === 0)
             return;
         const { view, referenceDate, minDate, maxDate } = this.#opts;
-        this.navDirection = delta > 0 ? 'forward' : 'backward';
         if (view === 'range') {
             // The range geometry follows the explicit rangeStart/rangeEnd inputs, not
             // referenceDate, so navigation shifts that window by its own span and emits
-            // the shifted range — the wrapper rebinds rangeStart/rangeEnd from it.
+            // the shifted range — the wrapper rebinds rangeStart/rangeEnd from it. It
+            // deliberately bypasses #emitNavigate: that would emit the week-padded
+            // *visible* range, and a wrapper rebinding rangeStart/rangeEnd from it
+            // would silently grow a mid-week window to full weeks on every step.
+            // The shift is clamped span-preserving (see #clampWindowStart), so a swipe
+            // — not gated by canGoBack/canGoForward the way the header arrows are —
+            // cannot push the window past [minDate, maxDate]. A shift that cannot move
+            // at all (already at the bound) emits nothing: unlike week/day, a no-op
+            // emit here would rebind rangeStart/rangeEnd to fresh Date objects and
+            // fire the consumer's onNavigate with an unchanged window.
             const { start, end } = this.#orderedRange(referenceDate);
             const spanDays = daysBetween(start, end) + 1;
-            const shiftedStart = addDays(start, delta * spanDays);
-            const shiftedEnd = addDays(end, delta * spanDays);
+            const shiftedStart = this.#clampWindowStart(addDays(start, delta * spanDays), spanDays);
+            if (shiftedStart.getTime() === start.getTime())
+                return;
+            this.navDirection = shiftedStart.getTime() > start.getTime() ? 'forward' : 'backward';
+            const shiftedEnd = addDays(shiftedStart, spanDays - 1);
             this.#opts.onNavigate?.(shiftedStart, { start: shiftedStart, end: shiftedEnd });
             return;
         }
+        this.navDirection = delta > 0 ? 'forward' : 'backward';
         let next;
         switch (view) {
             case 'month': {
@@ -368,6 +393,37 @@ export class DateGridController {
         const re = stripTime(this.#opts.rangeEnd ?? reference);
         return rs.getTime() <= re.getTime() ? { start: rs, end: re } : { start: re, end: rs };
     }
+    /** Span-preserving sliding-window clamp for range navigation. A window of
+     * `spanDays` days starting at `idealStart` must lie inside [minDate, maxDate]
+     * as a whole: the earliest allowed start is minDate, the latest is
+     * `maxDate − (spanDays − 1)` (inclusive bounds — the window's last day is
+     * `start + spanDays − 1` and must not pass maxDate). Clamping only the start
+     * against maxDate would collapse the span; this keeps it exact, allowing
+     * partial shifts up to the bound. Degenerate case — the span is longer than
+     * the navigable interval, so no start satisfies both bounds — pins the window
+     * to minDate (its tail spills past maxDate; matches clampDate's minDate-wins
+     * ordering) and warns in DEV instead of crashing, mirroring the inverted-
+     * bounds warning in the constructor. */
+    #clampWindowStart(idealStart, spanDays) {
+        const { minDate, maxDate } = this.#opts;
+        const earliest = minDate ? stripTime(minDate) : undefined;
+        const latest = maxDate ? addDays(stripTime(maxDate), -(spanDays - 1)) : undefined;
+        if (earliest && latest && earliest.getTime() > latest.getTime()) {
+            if (import.meta.env?.DEV) {
+                console.warn(`[DateGrid] a ${spanDays}-day range window cannot fit between minDate ` +
+                    `(${minDate?.toLocaleDateString()}) and maxDate (${maxDate?.toLocaleDateString()}) ` +
+                    `— pinning the window to minDate; its tail spills past maxDate. ` +
+                    `Widen the bounds or shorten the window.`);
+            }
+            return earliest;
+        }
+        let next = idealStart;
+        if (latest && next.getTime() > latest.getTime())
+            next = latest;
+        if (earliest && next.getTime() < earliest.getTime())
+            next = earliest;
+        return next;
+    }
     /** Pure cell geometry for an arbitrary reference date (no side effects). */
     #cellsFor(reference) {
         const wso = this.#opts.weekStartsOn;

package/dist/primitives/Avatar/Avatar.svelte

@@ -42,35 +42,42 @@
 
   const isInteractive = $derived(clickable || interactive || !!onclick);
 
-  function getRandomColor(name?: string): string {
-    if (!name) return '#4b5563'; // gray-600
+  // The identity palette lives in `style/semantic.css` (--color-avatar-1..12),
+  // so a brand rethemes it without touching this component and dark mode
+  // resolves through light-dark() like every other token. Spelled out one
+  // `var()` per slot rather than built from a template string: Tailwind's
+  // scanner only keeps @theme variables it can see referenced in the source,
+  // and a computed `--color-avatar-${n}` is invisible to it — the same reason
+  // `internal/charts/utils.ts` enumerates its chart palette literally.
+  const identityPalette = [
+    'var(--color-avatar-1)',
+    'var(--color-avatar-2)',
+    'var(--color-avatar-3)',
+    'var(--color-avatar-4)',
+    'var(--color-avatar-5)',
+    'var(--color-avatar-6)',
+    'var(--color-avatar-7)',
+    'var(--color-avatar-8)',
+    'var(--color-avatar-9)',
+    'var(--color-avatar-10)',
+    'var(--color-avatar-11)',
+    'var(--color-avatar-12)'
+  ];
 
-    // Tailwind *-700 shades — dark enough that white text hits WCAG AA 4.5:1
-    // on every hue. Lighter shades (*-500) used before produced ~3:1 contrast.
-    const colors = [
-      '#b91c1c', // red-700
-      '#c2410c', // orange-700
-      '#b45309', // amber-700
-      '#a16207', // yellow-700
-      '#4d7c0f', // lime-700
-      '#15803d', // green-700
-      '#047857', // emerald-700
-      '#0e7490', // cyan-700
-      '#0369a1', // sky-700
-      '#1d4ed8', // blue-700
-      '#4338ca', // indigo-700
-      '#6d28d9', // violet-700
-      '#7e22ce', // purple-700
-      '#a21caf', // fuchsia-700
-      '#be185d' // pink-700
-    ];
+  // Deterministic name → slot. The same name must always land on the same hue,
+  // so this stays a pure function of `name` with no randomness despite the
+  // `randomColor` prop name.
+  function getIdentityColor(name?: string): string | undefined {
+    // No name means no identity to encode — fall through to the `frame` slot's
+    // neutral surface tokens instead of inventing a grey.
+    if (!name) return undefined;
 
     let hash = 0;
     for (let i = 0; i < name.length; i++) {
       hash = name.charCodeAt(i) + ((hash << 5) - hash);
     }
 
-    return colors[Math.abs(hash) % colors.length];
+    return identityPalette[Math.abs(hash) % identityPalette.length];
   }
 
   function getInitials(name?: string): string {
@@ -83,7 +90,7 @@
       .slice(0, 2);
   }
 
-  const randomBg = $derived(randomColor ? getRandomColor(name) : undefined);
+  const randomBg = $derived(randomColor ? getIdentityColor(name) : undefined);
 
   const variantProps: AvatarVariants = $derived({
     size,
@@ -107,8 +114,15 @@
   // Inline property names stay kebab-case — a previous camelCase
   // `backgroundColor` was silently ignored by browsers, dropping the avatar back
   // to surface-interactive + white text.
+  //
+  // The initials take `--color-text-on-dark`, the palette's contrast partner: it
+  // flips white → neutral-900 in step with the fills going dark → light, so the
+  // initials stay legible in both modes. A literal `white` (the previous value)
+  // only worked because the old fills were frozen dark in dark mode too.
   const frameStyle = $derived(
-    randomColor && randomBg ? `background-color: ${randomBg}; color: white` : undefined
+    randomColor && randomBg
+      ? `background-color: ${randomBg}; color: var(--color-text-on-dark)`
+      : undefined
   );
 
   // `ringColor` recolours the ring on the outer `base`. The ring is a

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

@@ -34,7 +34,7 @@ export interface AvatarProps extends AvatarVariants, Omit<HTMLAttributes<HTMLDiv
     children?: Snippet;
     /** Custom ring color (CSS value). Overrides `ringIntent` when set. */
     ringColor?: string;
-    /** Derive a deterministic background color from `name`. The same name always produces the same color, making it easy to visually distinguish users without images. Overrides `intent`. */
+    /** Derive a deterministic background color from `name`. The same name always produces the same color, making it easy to visually distinguish users without images. Overrides `intent`. Picks from the 12-slot identity palette (`--color-avatar-1` … `--color-avatar-12`), which resolves light/dark automatically — override those tokens to rebrand it. Without a `name` there is no identity to encode, so the avatar keeps its neutral surface. */
     randomColor?: boolean;
     /** Mark the avatar as clickable (adds hover/focus styles and keyboard support). Alias for the `interactive` variant. */
     clickable?: boolean;

package/dist/primitives/Button/Button.svelte

@@ -153,25 +153,15 @@
      `blocks-intent-{name}` class on the button root scopes the glow color
      via `mint/styles.css`. */
 
-  :global(.blocks-button .blocks-ripple) {
-    position: absolute;
-    border-radius: 50%;
-    background: rgba(255, 255, 255, 0.4);
-    pointer-events: none;
-    animation: ripple var(--blocks-duration-slow) var(--blocks-ease-confident);
-    z-index: 1;
-  }
-
-  @keyframes ripple {
-    0% {
-      transform: scale(0);
-      opacity: 1;
-    }
-    100% {
-      transform: scale(1);
-      opacity: 0;
-    }
-  }
+  /* The ripple mint owns the ripple end-to-end: `mint/ripple.ts` appends a
+     `<span class="blocks-mint-ripple">` on click and drives it with the Web
+     Animations API, tinted `currentColor` so it resolves per variant/intent —
+     white on a filled button, the intent hue on outlined/ghost. Button used to
+     carry a competing `.blocks-ripple` rule here (a hardcoded
+     `rgba(255,255,255,0.4)` plus its own @keyframes) that no element ever
+     matched — nothing has emitted that class since the initial commit, and it
+     would have been invisible on light variants had it matched. Removed rather
+     than tokenised; see the same note in `mint/styles.css` (XC-12/PAG-1). */
 
   :global(.sr-only) {
     position: absolute;
@@ -185,10 +175,7 @@
     border-width: 0;
   }
 
-  @media (prefers-reduced-motion: reduce) {
-    :global(.blocks-button .blocks-ripple) {
-      animation: none !important;
-      opacity: 0 !important;
-    }
-  }
+  /* No reduced-motion rule for the ripple here either: `mint/ripple.ts` bails at
+     click time on `prefers-reduced-motion`, and `mint/styles.css` hides
+     `.blocks-mint-ripple` outright — both on the class that actually exists. */
 </style>