@pienter/ui 0.2.0 → 0.5.0

package/{utils/controllers/popover.ts → composables/usePopover.ts}

@@ -1,11 +1,18 @@
+import {
+    type MaybeRefOrGetter,
+    type Ref,
+    onBeforeUnmount,
+    onMounted,
+    toValue,
+    watch,
+} from 'vue';
+
 /**
- * Popover controller — shared by Popover, Tooltip, DropdownMenu,
- * Combobox listbox, and HoverCard per the locked controller-sharing
- * mapping in `CONVENTIONS.md`.
+ * Popover behavior — shared by Popover, Tooltip, DropdownMenu, and the
+ * Combobox listbox per the sharing mapping in `CONVENTIONS.md`.
  *
- * The v1 popover family is built on top of the **native HTML Popover
- * API** per the locked "Use native APIs where applicable" rule. The
- * browser already handles:
+ * Built on the **native HTML Popover API** per the locked "Use native
+ * APIs where applicable" rule. The browser already handles:
  *
  * - Top-layer rendering (popover escapes any ancestor stacking
  *   context / `overflow: hidden`)
@@ -14,37 +21,27 @@
  * - The `:popover-open` CSS pseudo-class for open-state styling
  * - The `toggle` event (fires on every open/close transition with
  *   `event.newState === 'open' | 'closed'`)
- * - Focus management (the popover is rendered in the top-layer; the
- *   browser does NOT auto-trap focus, but light-dismiss closes the
- *   popover when focus moves outside in `auto` mode)
  *
- * What the browser does NOT provide and we layer on top:
+ * What the browser does NOT provide and the composable layers on top:
  *
  * - **Anchor positioning** — CSS anchor positioning (`anchor-name`
  *   + `position-anchor`) is the modern declarative approach but
- *   Firefox support is incomplete in 2026. We compute position in
+ *   Firefox support is incomplete in 2026. Position is computed in
  *   JS from the anchor's `getBoundingClientRect()` + popover
  *   dimensions, applied via inline `style.left` / `style.top`. This
  *   keeps the support floor at Chrome 114+ / Safari 17+ / Firefox
  *   125+ (the Popover API floor itself).
  * - **Placement-flip on viewport collision** — if `bottom-start`
- *   overflows the bottom edge, we flip to `top-start`. Cross-axis
+ *   overflows the bottom edge, flip to `top-start`. Cross-axis
  *   overflow is handled by shifting along that axis to keep the
  *   popover inside the viewport.
  * - **Reposition-on-scroll/resize** — while the popover is open,
  *   `scroll` (capture) and `resize` listeners recompute the
  *   position so the popover tracks its anchor.
- * - A **callback** so framework code can reflect open/close state
- *   back into reactive state (`update:open`).
  * - **Anchor auto-detection** — if the consumer wires a trigger
- *   button declaratively via `popovertarget="<id>"`, the controller
- *   finds it via `document.querySelector('[popovertarget="<id>"]')`
- *   on mount. An explicit anchor element overrides the lookup.
- *
- * Mount on:
- * - The popover element itself (the element that carries the
- *   `popover` attribute). The controller reads / sets the attribute
- *   based on `config.modal`.
+ *   button declaratively via `popovertarget="<id>"`, the composable
+ *   finds it via `document.querySelector('[popovertarget="<id>"]')`.
+ *   An explicit `anchor` option overrides the lookup.
  */
 
 /**
@@ -78,14 +75,13 @@ export type Placement =
     | 'left-end';
 
 /**
- * Imperative control surface returned by `mountPopover`. The
- * controller owns the popover's runtime state (open/closed,
- * positioning listeners) and lets the native Popover API handle
- * top-layer rendering and light-dismiss. Frameworks call
- * `show()` / `hide()` and watch incoming prop changes; they never
- * own state directly.
+ * Handle returned by `usePopover`. The composable owns the popover's
+ * runtime side-effects (positioning, listeners) and lets the native
+ * Popover API handle top-layer rendering and light-dismiss. The
+ * component's reactive prop stays the source of truth for the
+ * open/closed boolean.
  */
-export interface PopoverControl {
+export interface PopoverHandle {
     /** Open the popover and position it against its anchor. */
     show(): void;
     /** Close the popover and tear down positioning listeners. */
@@ -96,33 +92,32 @@ export interface PopoverControl {
     isOpen(): boolean;
     /** Recompute position. Called automatically on scroll / resize while open. */
     reposition(): void;
-    /** Release listeners and reset attributes. */
-    teardown(): void;
 }
 
-export interface PopoverConfig {
+export interface UsePopoverOptions {
     /**
      * The element that anchors positioning (typically the trigger
-     * button). When `null`, the controller looks for a trigger via
+     * button). Resolved lazily on every reposition, so a getter may
+     * return `null` until the trigger exists. When absent, the
+     * composable looks for a trigger via
      * `document.querySelector('[popovertarget="<el.id>"]')`. If
      * neither is available the popover still opens but is positioned
-     * at the viewport origin (0,0) — caller is responsible for
-     * supplying an anchor before `show()` is meaningful.
+     * at the viewport origin (0,0).
      */
-    anchor?: HTMLElement | null;
+    anchor?: MaybeRefOrGetter<HTMLElement | null>;
     /**
-     * Initial placement. The controller flips to the opposite side
+     * Initial placement. The composable flips to the opposite side
      * automatically on viewport collision and shifts along the
      * cross-axis to keep the popover inside the viewport.
      * Default: `'bottom-start'`.
      */
-    placement?: Placement;
+    placement?: MaybeRefOrGetter<Placement>;
     /**
      * Offset from the anchor edge in pixels. The popover is pushed
      * away from the anchor by this many pixels along the placement
      * axis. Default: `8`.
      */
-    offset?: number;
+    offset?: MaybeRefOrGetter<number>;
     /**
      * When `true`, the popover uses `popover="manual"` — the user
      * cannot dismiss via outside click / focus loss / Escape; the
@@ -131,27 +126,27 @@ export interface PopoverConfig {
      * provides browser-native light-dismiss.
      */
     modal?: boolean;
+    /**
+     * Controlled open state. When the getter yields a boolean, the
+     * popover follows it: `true` shows, `false` hides, `undefined` is
+     * ignored. The initial value is applied on mount.
+     */
+    open?: () => boolean | undefined;
     /**
      * Called after the browser fires the `toggle` event with
-     * `newState === 'open'`. The framework reflects this into
+     * `newState === 'open'`. The component reflects this into
      * reactive state (e.g. `emit('update:open', true)`).
      */
     onOpen?: () => void;
     /**
      * Called after the browser fires the `toggle` event with
      * `newState === 'closed'` — including light-dismiss closures
-     * the controller did not initiate. The framework reflects this
+     * the composable did not initiate. The component reflects this
      * into reactive state (e.g. `emit('update:open', false)`).
      */
     onClose?: () => void;
 }
 
-/**
- * The DOM CSSStyleDeclaration assignment shape we use for
- * positioning. Inline styles win over the popover's own CSS for
- * `left` / `top`, which is what we want — the CSS supplies the
- * surface look, the controller supplies the position.
- */
 interface ComputedPosition {
     left: number;
     top: number;
@@ -283,60 +278,31 @@ function computePosition(
 }
 
 /**
- * Mount the popover controller on `el`, which is the popover
- * element itself (the element carrying the `popover` attribute).
- * The native Popover API provides top-layer rendering, light
- * dismiss, Escape handling, and the `:popover-open` pseudo-class;
- * this controller layers on anchor positioning, placement flip on
- * viewport collision, scroll/resize tracking, and `data-state`
- * reflection so the existing CSS conventions keep working.
- *
- * Lifecycle:
- * 1. On mount: set the `popover` attribute (`'auto'` for light
- *    dismiss; `'manual'` for explicit-close-only). Wire the
- *    `toggle` event so the framework hears about open/close
- *    transitions. Resolve the anchor (explicit `config.anchor`,
- *    else `document.querySelector('[popovertarget="<el.id>"]')`).
- * 2. `show()`: call `el.showPopover()` (native top-layer + light
- *    dismiss). Compute position via `computePosition` and apply
- *    inline `style.left` / `style.top`. Wire scroll (capture) and
- *    resize listeners that call `reposition()`.
- * 3. `hide()`: call `el.hidePopover()` (native focus restoration
- *    if focus was inside the popover). Remove scroll/resize
- *    listeners.
- * 4. `teardown()`: ensures hide ran, removes the `toggle`
- *    listener.
+ * Popover behavior for the element carrying the `popover` attribute,
+ * rendered by the calling component. Wires itself on mount and cleans
+ * up before unmount.
  *
- * The controller does NOT decide when to close — `onOpen` /
- * `onClose` are invoked when the browser fires the native `toggle`
- * event. The caller is responsible for reflecting that into
- * framework state. The framework's reactive prop is the source of
- * truth for the open/closed boolean; the controller is the source
- * of truth for runtime side-effects (positioning, listeners).
+ * The composable does NOT decide when to close — `onOpen` / `onClose`
+ * are invoked when the browser fires the native `toggle` event, which
+ * catches both composable-initiated transitions (show/hide) and
+ * browser-initiated ones (light-dismiss, declarative `popovertarget`
+ * button click). The component's reactive prop is the source of truth
+ * for the open/closed boolean; the composable is the source of truth
+ * for runtime side-effects (positioning, listeners).
  */
-export function mountPopover(
-    el: HTMLElement,
-    config: PopoverConfig = {},
-): PopoverControl {
-    const placement: Placement = config.placement ?? 'bottom-start';
-    const offset = config.offset ?? 8;
-    const modal = config.modal ?? false;
-
-    // `popover="auto"` opts into native light-dismiss: outside click,
-    // focus loss, and Escape all close the popover. `popover="manual"`
-    // means the popover stays until explicitly hidden via JS — used
-    // for non-dismissable surfaces (e.g., a modal-style popover that
-    // requires a button click to close).
-    el.setAttribute('popover', modal ? 'manual' : 'auto');
-    el.setAttribute('data-state', 'closed');
-
-    // Anchor resolution. Explicit `config.anchor` wins; otherwise
+export function usePopover(
+    elRef: Ref<HTMLElement | null>,
+    options: UsePopoverOptions = {},
+): PopoverHandle {
+    // Anchor resolution. An explicit `anchor` option wins; otherwise
     // look up the trigger via the native `popovertarget` attribute.
-    // Resolved lazily on each show() so the consumer can swap the
-    // trigger between mount and first open without re-mounting.
+    // Resolved lazily on every reposition so the consumer can supply
+    // the trigger after mount without re-wiring.
     function resolveAnchor(): HTMLElement | null {
-        if (config.anchor) return config.anchor;
-        if (!el.id) return null;
+        const el = elRef.value;
+        const anchor = toValue(options.anchor);
+        if (anchor) return anchor;
+        if (!el?.id) return null;
         return document.querySelector<HTMLElement>(
             `[popovertarget="${CSS.escape(el.id)}"]`,
         );
@@ -345,13 +311,14 @@ export function mountPopover(
     let scrollListenersWired = false;
 
     function reposition(): void {
+        const el = elRef.value;
         const anchor = resolveAnchor();
-        if (!anchor) return;
+        if (!el || !anchor) return;
         const { left, top, resolvedPlacement } = computePosition(
             anchor,
             el,
-            placement,
-            offset,
+            toValue(options.placement) ?? 'bottom-start',
+            toValue(options.offset) ?? 8,
         );
         el.style.left = `${left}px`;
         el.style.top = `${top}px`;
@@ -379,56 +346,76 @@ export function mountPopover(
     }
 
     // Native `toggle` event fires on every open/close transition
-    // with `event.newState` set to `'open'` or `'closed'`. We use it
-    // as the single source of truth for `data-state` reflection and
-    // for invoking the framework callbacks — this catches both
-    // controller-initiated transitions (show/hide) and
-    // browser-initiated ones (light-dismiss, declarative
-    // `popovertarget` button click).
+    // with `event.newState` set to `'open'` or `'closed'`. It is the
+    // single source of truth for `data-state` reflection and for
+    // invoking the component callbacks.
     function handleToggle(event: Event): void {
+        const el = elRef.value;
+        if (!el) return;
         const evt = event as ToggleEvent;
         if (evt.newState === 'open') {
             el.setAttribute('data-state', 'open');
             // First reposition runs after the popover has been laid out
             // by the browser (toggle fires after layout). Wire the
-            // scroll/resize listeners now so subsequent movement
-            // tracks.
+            // scroll/resize listeners now so subsequent movement tracks.
             reposition();
             wireScrollListeners();
-            config.onOpen?.();
+            options.onOpen?.();
         } else {
             el.setAttribute('data-state', 'closed');
             unwireScrollListeners();
-            config.onClose?.();
+            options.onClose?.();
         }
     }
 
-    el.addEventListener('toggle', handleToggle);
-
     function show(): void {
-        if (el.matches(':popover-open')) return; // idempotent
+        const el = elRef.value;
+        if (!el || el.matches(':popover-open')) return; // idempotent
         el.showPopover();
     }
 
     function hide(): void {
-        if (!el.matches(':popover-open')) return; // idempotent
+        const el = elRef.value;
+        if (!el || !el.matches(':popover-open')) return; // idempotent
         el.hidePopover();
     }
 
     function toggle(): void {
-        if (el.matches(':popover-open')) hide();
+        if (isOpen()) hide();
         else show();
     }
 
     function isOpen(): boolean {
-        return el.matches(':popover-open');
+        return elRef.value?.matches(':popover-open') ?? false;
     }
 
-    function teardown(): void {
-        if (isOpen()) hide();
+    onMounted(() => {
+        const el = elRef.value;
+        if (!el) return;
+        // `popover="auto"` opts into native light-dismiss: outside click,
+        // focus loss, and Escape all close the popover. `popover="manual"`
+        // means the popover stays until explicitly hidden via JS.
+        el.setAttribute('popover', options.modal ? 'manual' : 'auto');
+        el.setAttribute('data-state', 'closed');
+        el.addEventListener('toggle', handleToggle);
+        if (options.open && toValue(options.open)) show();
+    });
+
+    if (options.open) {
+        watch(options.open, (value) => {
+            if (!elRef.value || value === undefined) return;
+            if (value) show();
+            else hide();
+        });
+    }
+
+    onBeforeUnmount(() => {
+        const el = elRef.value;
+        if (!el) return;
+        if (el.matches(':popover-open')) el.hidePopover();
         unwireScrollListeners();
         el.removeEventListener('toggle', handleToggle);
-    }
+    });
 
-    return { show, hide, toggle, isOpen, reposition, teardown };
+    return { show, hide, toggle, isOpen, reposition };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pienter/ui",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Shared Pienter UI components, styles, icons, and browser utilities.",
   "type": "module",
   "license": "MIT",
@@ -27,90 +27,62 @@
       "default": "./styles/main.css"
     },
     "./styles/*": "./styles/*",
-    "./components/Button.astro": "./components/action/button/Button.astro",
     "./components/Button.vue": "./components/action/button/Button.vue",
-    "./components/IconButton.astro": "./components/action/button/IconButton.astro",
     "./components/IconButton.vue": "./components/action/button/IconButton.vue",
     "./components/Toggle.vue": "./components/action/toggle/Toggle.vue",
     "./components/ToggleGroup.vue": "./components/action/toggle-group/ToggleGroup.vue",
-    "./components/Avatar.astro": "./components/display/avatar/Avatar.astro",
     "./components/Avatar.vue": "./components/display/avatar/Avatar.vue",
-    "./components/AvatarStack.astro": "./components/display/avatar/AvatarStack.astro",
     "./components/AvatarStack.vue": "./components/display/avatar/AvatarStack.vue",
-    "./components/Badge.astro": "./components/display/badge/Badge.astro",
     "./components/Badge.vue": "./components/display/badge/Badge.vue",
-    "./components/Empty.astro": "./components/display/empty/Empty.astro",
     "./components/Empty.vue": "./components/display/empty/Empty.vue",
-    "./components/Icon.astro": "./components/display/icon/Icon.astro",
     "./components/Icon.vue": "./components/display/icon/Icon.vue",
-    "./components/Alert.astro": "./components/feedback/alert/Alert.astro",
     "./components/Alert.vue": "./components/feedback/alert/Alert.vue",
-    "./components/Progress.astro": "./components/feedback/progress/Progress.astro",
     "./components/Progress.vue": "./components/feedback/progress/Progress.vue",
-    "./components/Skeleton.astro": "./components/feedback/skeleton/Skeleton.astro",
     "./components/Skeleton.vue": "./components/feedback/skeleton/Skeleton.vue",
-    "./components/Spinner.astro": "./components/feedback/spinner/Spinner.astro",
     "./components/Spinner.vue": "./components/feedback/spinner/Spinner.vue",
-    "./components/Toast.astro": "./components/feedback/toast/Toast.astro",
     "./components/Toast.vue": "./components/feedback/toast/Toast.vue",
-    "./components/Checkbox.astro": "./components/form/checkbox/Checkbox.astro",
     "./components/Checkbox.vue": "./components/form/checkbox/Checkbox.vue",
     "./components/Combobox.vue": "./components/form/combobox/Combobox.vue",
-    "./components/DateInput.astro": "./components/form/date-input/DateInput.astro",
     "./components/DateInput.vue": "./components/form/date-input/DateInput.vue",
-    "./components/Form.astro": "./components/form/form/Form.astro",
     "./components/Form.vue": "./components/form/form/Form.vue",
-    "./components/InputOTP.astro": "./components/form/input-otp/InputOTP.astro",
     "./components/InputOTP.vue": "./components/form/input-otp/InputOTP.vue",
-    "./components/Label.astro": "./components/form/label/Label.astro",
     "./components/Label.vue": "./components/form/label/Label.vue",
-    "./components/NumberField.astro": "./components/form/number-field/NumberField.astro",
     "./components/NumberField.vue": "./components/form/number-field/NumberField.vue",
-    "./components/RadioGroup.astro": "./components/form/radio-group/RadioGroup.astro",
     "./components/RadioGroup.vue": "./components/form/radio-group/RadioGroup.vue",
     "./components/RadioGroup.types": "./components/form/radio-group/types.ts",
     "./components/Segmented.vue": "./components/form/select/Segmented.vue",
-    "./components/Select.astro": "./components/form/select/Select.astro",
     "./components/Select.vue": "./components/form/select/Select.vue",
-    "./components/Slider.astro": "./components/form/slider/Slider.astro",
     "./components/Slider.vue": "./components/form/slider/Slider.vue",
-    "./components/Switch.astro": "./components/form/switch/Switch.astro",
     "./components/Switch.vue": "./components/form/switch/Switch.vue",
-    "./components/TagsInput.astro": "./components/form/tags-input/TagsInput.astro",
     "./components/TagsInput.vue": "./components/form/tags-input/TagsInput.vue",
-    "./components/TextInput.astro": "./components/form/text-input/TextInput.astro",
     "./components/TextInput.vue": "./components/form/text-input/TextInput.vue",
-    "./components/Textarea.astro": "./components/form/textarea/Textarea.astro",
     "./components/Textarea.vue": "./components/form/textarea/Textarea.vue",
     "./components/Accordion.vue": "./components/layout/accordion/Accordion.vue",
-    "./components/Card.astro": "./components/layout/card/Card.astro",
     "./components/Card.vue": "./components/layout/card/Card.vue",
     "./components/Collapsible.vue": "./components/layout/collapsible/Collapsible.vue",
-    "./components/Separator.astro": "./components/layout/separator/Separator.astro",
     "./components/Separator.vue": "./components/layout/separator/Separator.vue",
-    "./components/Table.astro": "./components/layout/table/Table.astro",
     "./components/Table.vue": "./components/layout/table/Table.vue",
     "./components/TableRow.vue": "./components/layout/table/TableRow.vue",
     "./components/DataTable.vue": "./components/layout/table/DataTable.vue",
     "./components/Table.types": "./components/layout/table/types.ts",
-    "./components/Breadcrumb.astro": "./components/navigation/breadcrumb/Breadcrumb.astro",
     "./components/Breadcrumb.vue": "./components/navigation/breadcrumb/Breadcrumb.vue",
-    "./components/Navbar.astro": "./components/navigation/navbar/Navbar.astro",
     "./components/Navbar.vue": "./components/navigation/navbar/Navbar.vue",
     "./components/Pagination.vue": "./components/navigation/pagination/Pagination.vue",
-    "./components/Sidebar.astro": "./components/navigation/sidebar/Sidebar.astro",
+    "./components/PaginationFooter.vue": "./components/navigation/pagination/PaginationFooter.vue",
     "./components/Sidebar.vue": "./components/navigation/sidebar/Sidebar.vue",
     "./components/Sidebar.types": "./components/navigation/sidebar/types.ts",
     "./components/Tabs.vue": "./components/navigation/tabs/Tabs.vue",
-    "./components/AlertDialog.astro": "./components/overlay/alert-dialog/AlertDialog.astro",
     "./components/AlertDialog.vue": "./components/overlay/alert-dialog/AlertDialog.vue",
     "./components/Command.vue": "./components/overlay/command/Command.vue",
     "./components/DropdownMenu.vue": "./components/overlay/dropdown-menu/DropdownMenu.vue",
-    "./components/Modal.astro": "./components/overlay/modal/Modal.astro",
     "./components/Modal.vue": "./components/overlay/modal/Modal.vue",
     "./components/Popover.vue": "./components/overlay/popover/Popover.vue",
     "./components/Sheet.vue": "./components/overlay/sheet/Sheet.vue",
     "./components/Tooltip.vue": "./components/overlay/tooltip/Tooltip.vue",
+    "./composables/useDialog": "./composables/useDialog.ts",
+    "./composables/useDisclosure": "./composables/useDisclosure.ts",
+    "./composables/useMenu": "./composables/useMenu.ts",
+    "./composables/usePopover": "./composables/usePopover.ts",
     "./composables/useUrlSort": "./composables/useUrlSort.ts",
     "./icons": "./icons/index.ts",
     "./icons/*": "./icons/*",
@@ -129,14 +101,10 @@
     "!components/**/AUDIT.md"
   ],
   "peerDependencies": {
-    "astro": ">=5.0.0",
     "vue": ">=3.5.0",
     "vue-router": ">=4.0.0"
   },
   "peerDependenciesMeta": {
-    "astro": {
-      "optional": true
-    },
     "vue": {
       "optional": true
     },

package/styles/0-settings/colors.css

@@ -14,7 +14,7 @@
        --clr-base        panels and cards (the front-most surface)
        --clr-mantle      the page behind them
        --clr-surface-0   accent panels, hover fills, table stripes
-       --clr-surface-1   hairline borders
+       --clr-surface-1   hairline borders, and the neutral selected fill
        --clr-overlay     input borders (clears 3:1)
        --clr-subtext     secondary text (clears 4.5:1)
        --clr-text        body text
@@ -197,6 +197,13 @@
     --bg-clr-surface: var(--clr-base);
     --bg-clr-surface-2: var(--clr-surface-0);
     --bg-clr-accent: var(--clr-surface-0);
+    /* The neutral "selected" rung — one step past the hover fill, so a chosen
+       item stays distinct from a merely hovered one. It rides --clr-surface-1
+       because that is the only neutral that keeps a similar distance from the
+       surface in BOTH themes: darker than the surface in light, lighter in
+       dark. Pair it with --text-clr-base, never --text-clr-inverse — inverse
+       is near-white in both themes, so it would vanish here in the light one. */
+    --bg-clr-selected: var(--clr-surface-1);
     --bg-clr-brand: var(--clr-blue-fill);
     --bg-clr-brand-hover: var(--clr-blue-fill-strong);
     --bg-clr-brand-ink: var(--clr-inverse);

package/styles/0-settings/layout.css

@@ -36,11 +36,29 @@
 
     --opacity-disabled: 0.45;
 
+    /* Stacking ladder. Steps of 10 leave room to slot one in. A rung only
+     ranks siblings inside the SAME stacking context — it is not a promise
+     about the page; escape one by raising the root, not the layer. */
+    --layer-below: -1; /* behind the surface that renders it — a sentinel */
+    --layer-0: 0; /* in flow */
+    --layer-1: 10; /* raised within a component */
+    --layer-2: 20; /* sticky furniture */
+    --layer-3: 30; /* content-anchored overlays */
+    --layer-4: 40; /* scrims and backdrops */
+    --layer-5: 50; /* modal surfaces */
+    --layer-top: 1000; /* above everything, including a modal — a sentinel */
+
     /* Soft elevation. The shadow reads as depth, not as a drawn edge. */
     --shadow-sm: 0 1px 2px
         color-mix(in srgb, var(--shadow-clr) 14%, transparent);
     --shadow-md: 0 3px 8px
         color-mix(in srgb, var(--shadow-clr) 18%, transparent);
+    /* Overlay elevation — a surface that covers page content rather than
+     sitting on it. --shadow-md is tuned for a card in the flow and reads
+     flat under something as large as a sidebar flyout, so this one spreads
+     further and sits lighter. */
+    --shadow-lg: 0 8px 24px
+        color-mix(in srgb, var(--shadow-clr) 16%, transparent);
     --shadow-brand: 0 3px 8px
         color-mix(in srgb, var(--outline-clr-base) 18%, transparent);
 

package/styles/0-settings/motion.css

@@ -1,6 +1,6 @@
 :root {
-    --duration-fast: 80ms; /* hover and press feedback */
-    --duration-base: 120ms; /* colour and background transitions */
+    --duration-fast: 120ms; /* hover and press feedback */
+    --duration-base: 250ms; /* colour and background transitions */
     --duration-slow: 2s; /* one spinner revolution — deliberately unhurried */
 
     --ease-base: ease;

package/styles/0-settings/spacing.css

@@ -11,5 +11,7 @@
 
     /* Layout-shell widths (used by Sidebar et al.) */
     --space-sidebar-width: 16rem;
-    --space-sidebar-width-collapsed: 4rem;
+    /* Wide enough for an icon over a `--step--3` caption. At 4rem real
+       labels ("Dashboard", "Components") ellipsised to two characters. */
+    --space-sidebar-width-collapsed: 4.75rem;
 }