@bearmenu/ui 0.8.2 → 0.8.4

package/src/components/motion-icon.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+/**
+ * MotionIcon — the root for character-animated icons.
+ *
+ * An animated icon performs a behaviour the object it depicts would actually
+ * perform (a roof jumps, utensils uncross, a pin drops and plants) rather than
+ * tweening a property. The rules that make container motion feel right — short
+ * durations, one or two properties, restraint — produce dead icons, so this
+ * primitive is built for the opposite:
+ *
+ *   - Gestures run 400–700ms in five or six beats (anticipation, action, apex,
+ *     impact, settle), which deliberately exceeds the usual UI ceiling. An icon
+ *     gesture is a performance the user chose to trigger, not a transition they
+ *     are waiting through.
+ *   - Amplitudes are 25–40% of the icon box. At a 22px render on a 24-unit grid
+ *     one unit is 0.92px, so anything under ~6 units is physically invisible.
+ *   - The silhouette must change. If the outline is the same shape throughout,
+ *     nothing reads at icon size.
+ *
+ * Three variants, not two:
+ *   rest    — the plain glyph.
+ *   active  — the held pose. Equal to `rest` for gestures that return
+ *             (a roof that lands again); a genuinely different pose for ones
+ *             that stay changed (uncrossed utensils, a filled pin).
+ *   play    — the performance: keyframe arrays that land on `active`.
+ *
+ * `play` is driven by `replayToken`, which callers bump on POINTER DOWN rather
+ * than on the resulting state change. Waiting for state means waiting for
+ * navigation or a network write, which disconnects the gesture from the finger
+ * and reads as dead at any amplitude.
+ */
+
+import * as React from "react";
+import { motion, useAnimationControls, type Transition, type Variants } from "framer-motion";
+
+import { cn } from "../lib/utils";
+
+export type MotionIconProps = {
+  /** The held state. Drives `active` vs `rest`, and the stroke weight. */
+  active?: boolean;
+  /**
+   * Bump on pointer down to perform the gesture. Changing this value replays
+   * `play` even when `active` has not changed, which is what makes the icon
+   * respond to the touch rather than to its consequence.
+   */
+  replayToken?: number;
+  className?: string;
+};
+
+export type MotionIconVariant = "rest" | "active" | "play";
+
+/**
+ * A gesture is a performance with beats, so it is a tween with explicit
+ * `times`. A spring interpolates two keyframes and puts its overshoot at the
+ * end, which cannot express anticipation.
+ */
+export function beats(times: number[], duration = 0.62): Transition {
+  return { duration, times, ease: "easeInOut" };
+}
+
+/** Leaving is not a performance — it returns the glyph, firmly and fast. */
+export const returnTransition: Transition = { type: "spring", stiffness: 320, damping: 26 };
+
+type PoseValues = Record<string, number>;
+
+/**
+ * Builds the three variants for a moving part.
+ * `play` values are keyframe arrays; `rest`/`active` are the two held poses.
+ */
+export function poses(
+  rest: PoseValues,
+  active: PoseValues,
+  play: Record<string, number[]>,
+  transition: Transition
+): Variants {
+  return {
+    rest: { ...rest, transition: returnTransition },
+    active: { ...active, transition: returnTransition },
+    play: { ...play, transition },
+  };
+}
+
+const rootVariants: Variants = {
+  rest: { strokeWidth: 1.75, transition: { duration: 0.18 } },
+  active: { strokeWidth: 2.25, transition: { duration: 0.18 } },
+  play: { strokeWidth: 2.25, transition: { duration: 0.12 } },
+};
+
+/**
+ * Mount poses without playing; pointer down plays; arriving plays unless the
+ * pointer already started it; leaving returns.
+ *
+ * Both effects compare against a ref rather than trusting the dependency array,
+ * so they fire once per actual change and not once per render.
+ */
+export function useIconGesture(active: boolean, replayToken: number) {
+  const controls = useAnimationControls();
+  const lastPlayAt = React.useRef(0);
+  const seenToken = React.useRef(0);
+  // `null` until mounted, so the pose effect can tell a real change from the
+  // first run and never performs the gesture on page load.
+  const seenActive = React.useRef<boolean | null>(null);
+
+  React.useEffect(() => {
+    controls.set(active ? "active" : "rest");
+    seenActive.current = active;
+    // Mount only — the two effects below own everything after that.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  React.useEffect(() => {
+    if (replayToken === seenToken.current) return;
+    seenToken.current = replayToken;
+    lastPlayAt.current = Date.now();
+    void controls.start("play");
+  }, [replayToken, controls]);
+
+  React.useEffect(() => {
+    if (seenActive.current === null || seenActive.current === active) return;
+    seenActive.current = active;
+    if (!active) {
+      void controls.start("rest");
+      return;
+    }
+    // The pointer that caused this state change already started the gesture.
+    if (Date.now() - lastPlayAt.current < 600) return;
+    void controls.start("play");
+  }, [active, controls]);
+
+  return controls;
+}
+
+export function MotionIcon({
+  active = false,
+  replayToken = 0,
+  className,
+  children,
+}: MotionIconProps & { children: React.ReactNode }) {
+  const controls = useIconGesture(active, replayToken);
+
+  return (
+    <motion.svg
+      viewBox="0 0 24 24"
+      // Parts leave the 24-unit box at the apex of a jump. Callers give the
+      // icon padding rather than clipping the gesture.
+      overflow="visible"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      variants={rootVariants}
+      // Without this the active icon replays on hydration and every other one
+      // flashes through its pose on first paint.
+      initial={false}
+      animate={controls}
+      className={cn("size-6", className)}
+      aria-hidden
+    >
+      {children}
+    </motion.svg>
+  );
+}

package/src/components/multi-select-combobox.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof MultiSelectCombobox>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof MultiSelectCombobox>;
 
 const cuisines = [
   { value: "italian", label: "Italian" },

package/src/components/phone-frame.stories.tsx

@@ -11,7 +11,7 @@ const meta = {
 } satisfies Meta<typeof PhoneFrame>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof PhoneFrame>;
 
 export const Default: Story = {
   args: { width: 220 },

package/src/components/rating.stories.tsx

@@ -1,14 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Rating } from "./rating";
 
-const meta = {
+const meta: Meta<typeof Rating> = {
   title: "Components/Rating",
   component: Rating,
   tags: ["autodocs"],
-} satisfies Meta<typeof Rating>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Rating>;
 
 export const Default: Story = {
   render: () => <Rating value={4} reviewCount={128} />,

package/src/components/searchable-select.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof SearchableSelect>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SearchableSelect>;
 
 const frameworks = [
   { value: "next", label: "Next.js", description: "The React Framework" },

package/src/components/selection-bar.stories.tsx

@@ -9,7 +9,7 @@ const meta = {
 } satisfies Meta<typeof SelectionBar>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SelectionBar>;
 
 export const Default: Story = {
   render: () => (

package/src/components/skeleton-card.stories.tsx

@@ -1,14 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { SkeletonCard } from "./skeleton-card";
 
-const meta = {
+const meta: Meta<typeof SkeletonCard> = {
   title: "Components/SkeletonCard",
   component: SkeletonCard,
   tags: ["autodocs"],
-} satisfies Meta<typeof SkeletonCard>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SkeletonCard>;
 
 export const Experience: Story = {
   render: () => <SkeletonCard variant="experience" className="w-[350px]" />,

package/src/components/sliding-panels.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof SlidingPanels>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SlidingPanels>;
 
 function SlidingPanelsDemo() {
   const [currentPanel, setCurrentPanel] = useState("panel-1");

package/src/components/stepper.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof Stepper>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Stepper>;
 
 const steps = [
   { id: "account", title: "Account" },

package/src/components/sticky-container.stories.tsx

@@ -1,14 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { StickyContainer } from "./sticky-container";
 
-const meta = {
+const meta: Meta<typeof StickyContainer> = {
   title: "Components/StickyContainer",
   component: StickyContainer,
   tags: ["autodocs"],
-} satisfies Meta<typeof StickyContainer>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof StickyContainer>;
 
 export const Default: Story = {
   render: () => (

package/src/components/toggle-group.stories.tsx

@@ -9,7 +9,7 @@ const meta = {
 } satisfies Meta<typeof ToggleGroup>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof ToggleGroup>;
 
 export const Default: Story = {
   render: () => (

package/src/components/tooltip.stories.tsx

@@ -3,7 +3,7 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tool
 import { Button } from "./button";
 import { Plus } from "lucide-react";
 
-const meta = {
+const meta: Meta<typeof Tooltip> = {
   title: "Components/Tooltip",
   component: Tooltip,
   tags: ["autodocs"],
@@ -14,7 +14,7 @@ const meta = {
       </TooltipProvider>
     ),
   ],
-} satisfies Meta<typeof Tooltip>;
+};
 
 export default meta;
 type Story = StoryObj<typeof meta>;

package/src/globals.css

@@ -33,34 +33,77 @@ h6 {
   --sab: env(safe-area-inset-bottom);
   --sal: env(safe-area-inset-left);
 
-  --background: oklch(0.97 0.012 80);
-  --foreground: oklch(0.22 0.025 45);
-  --card: oklch(0.99 0.006 70);
-  --card-foreground: oklch(0.22 0.025 45);
-  --popover: oklch(0.99 0.006 70);
-  --popover-foreground: oklch(0.22 0.025 45);
+  /* ─── Light neutral ramp (0.8.3 — "warmth has edges") ─────────────────
+     Every surface and text token below is TRUE NEUTRAL: chroma exactly 0,
+     8-bit R−B spread exactly 0. Grey. Not "warm grey", not "off-white" —
+     grey. That is deliberate and hard-won; read this before adding a tint.
+
+     These used to carry chroma 0.008-0.025 at hue 45-80, on the theory that a
+     faint warm tint everywhere expressed a warm brand. In practice a low-chroma
+     tint spread across large soft areas — page, chip fills, hover fills,
+     hairlines, shadows — does not read as warmth. It reads as a colour cast:
+     "tan", "peachy", "hurts my eyes", "unprofessional for a serious app".
+
+     It was walked down in stages — 0.012 → 0.005 → 0.0025 → 0.003 → 0 — and
+     was still being rejected at chroma 0.0025, an R−B spread of THREE, which
+     is about as small as an 8-bit tint gets. That is the finding: on a large
+     light field there is no amount of warm chroma small enough to be safe.
+     Any nonzero value at hue 45-80 eventually gets described as brown.
+
+     The rule that replaces it: warmth needs an EDGE and real saturation. It
+     lives in --accent, --gradient-primary, badges, CTAs and photography —
+     bounded things at chroma >= 0.09. Never in a fill, a blur or body text.
+     The contrast between a neutral field and a saturated accent is what makes
+     the accent read as intentional. Do not re-warm these. */
+  --background: oklch(0.986 0 0);
+  --foreground: oklch(0.18 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.18 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.18 0 0);
   --primary: oklch(0.25 0.05 35);
   --primary-foreground: oklch(0.98 0 0);
-  --secondary: oklch(0.985 0.008 80);
-  --secondary-foreground: oklch(0.22 0.025 45);
-  --muted: oklch(0.985 0.008 80);
-  --muted-foreground: oklch(0.62 0.015 45);
-  --accent: oklch(0.94 0.04 50);
-  --accent-foreground: oklch(0.22 0.025 45);
+  --secondary: oklch(0.955 0 0);
+  --secondary-foreground: oklch(0.18 0 0);
+  --muted: oklch(0.955 0 0);
+  --muted-foreground: oklch(0.52 0 0);
+  /* BREAKING in 0.8.3 — see CHANGELOG. --accent was oklch(0.94 0.04 50), a
+     pale peach FILL paired with a dark --accent-foreground. It is now the
+     brand terracotta, used as text and as a filled surface with WHITE
+     foreground. A consumer rendering `bg-accent text-accent-foreground` gets a
+     dark brown chip where it used to get a pale one. bearmenu-fe already ran
+     these values as a local override; promoting them stops Storybook and the
+     product disagreeing about what "accent" means. */
+  --accent: oklch(0.51 0.095 45);
+  --accent-foreground: oklch(1 0 0);
+  /* Recessed-well companion to --accent: a tinted surface for active chips,
+     wells and highlighted rows. Neutral on purpose — its call sites pair it
+     with `text-accent`, and the text is what carries the meaning. */
+  --accent-subtle: oklch(0.945 0 0);
   --destructive: oklch(0.577 0.245 27.325);
   --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.9 0.012 60);
-  --input: oklch(0.9 0.012 60);
+  --border: oklch(0.895 0 0);
+  --input: oklch(0.895 0 0);
   --ring: oklch(0.25 0.05 35);
   --chart-1: oklch(0.646 0.222 41.116);
   --chart-2: oklch(0.6 0.118 184.704);
   --chart-3: oklch(0.398 0.07 227.392);
   --chart-4: oklch(0.828 0.189 84.429);
   --chart-5: oklch(0.769 0.188 70.08);
-  --surface: oklch(0.99 0.006 70);
+  --surface: oklch(1 0 0);
   --surface-foreground: var(--foreground);
-  --surface-2: oklch(0.985 0.008 80);
-  --line-soft: oklch(0.94 0.01 60);
+  --surface-2: oklch(0.968 0 0);
+  --line-soft: oklch(0.935 0 0);
+  /* The top plane. In light mode white IS the ceiling — "elevated" means card
+     + shadow, there is nothing above it to reach for — so this equals --card.
+     Dark reaches the same idea from below (see .dark). The asymmetry is
+     correct; do not "fix" the two into agreement. */
+  --surface-elevated: oklch(1 0 0);
+  /* Text tiers. --ink-secondary and --ink-tertiary sit between --foreground
+     and --muted-foreground for captions, counts and metadata. */
+  --ink-primary: var(--foreground);
+  --ink-secondary: oklch(0.45 0 0);
+  --ink-tertiary: oklch(0.52 0 0);
   --radius: 0.625rem;
   --sidebar: oklch(0.985 0 0);
   --sidebar-foreground: oklch(0.145 0 0);
@@ -75,6 +118,26 @@ h6 {
   --warning: oklch(0.72 0.18 68);
   --warning-foreground: oklch(0.18 0.04 45);
 
+  /* ─── Brand gradient ──────────────────────────────────────────────────
+     The terracotta ramp used by the FAB, primary buttons, banner CTAs and
+     featured surfaces. This — not any surface tint — is where the brand's
+     warmth lives: chroma 0.09-0.10, on bounded elements. */
+  --gradient-primary: linear-gradient(180deg, oklch(0.58 0.1 45) 0%, oklch(0.44 0.09 42) 100%);
+  --gradient-primary-from: oklch(0.58 0.1 45);
+  --gradient-primary-to: oklch(0.44 0.09 42);
+
+  /* ─── Generic elevation ───────────────────────────────────────────────
+     Pure neutral (chroma 0) at L 0.52. These were a saturated brown, which put
+     a soft-edged tan patch under every card, row and overlay — the single
+     largest warm area on a light page, and the hardest to attribute because a
+     blur has no boundary to blame it on. Alphas are the calibrated set; only
+     the tint changed. Apps compose these; they must not re-tint them. */
+  --shadow-card: 0 1px 2px oklch(0.52 0 0 / 0.05), 0 2px 6px -1px oklch(0.52 0 0 / 0.08);
+  --shadow-card-hover:
+    0 2px 4px -1px oklch(0.52 0 0 / 0.07), 0 10px 24px -6px oklch(0.52 0 0 / 0.16);
+  --shadow-overlay:
+    0 4px 12px -2px oklch(0.52 0 0 / 0.1), 0 16px 48px -12px oklch(0.52 0 0 / 0.2);
+
   /* Brown variant — replaces hardcoded #482E1F across button/badge */
   --brown: oklch(0.31 0.05 45);
   --brown-foreground: oklch(0.985 0 0);
@@ -90,10 +153,18 @@ h6 {
   --shadow-alpha-2xl: 0.25;
 
   /* ─── Card cover shadows (companion to lib/card-hover.ts) ─────────────
-     The warm lift under a card's cover region, and its deepened hover state.
+     The lift under a card's cover region, and its deepened hover state.
      Deliberately separate from the --shadow-alpha-* ladder above: that is a
-     neutral black ramp for surfaces, this is the warm brown cast that only
-     reads correctly under photography and generated cover art.
+     pure-black ramp for surfaces, this is a softer, lighter cast tuned for
+     photography and generated cover art.
+
+     0.8.3: was rgba(120, 80, 50, …) — an 8-bit R−B spread of 70, by far the
+     most saturated shadow in the system, compositing to spread 18-23 under
+     every card cover. It survived an entire light-theme neutralisation pass
+     because it lives here and nothing overrode it. Now oklch(0.45 0 0),
+     matched on LUMINANCE (0.091 vs the old 0.100) so the visual weight is
+     unchanged, with the tint gone entirely. Same reasoning as the light ramp
+     above: a wide blur cannot hold a tint without reading as a stain.
 
      --shadow-menu-cover-inset is the pressed-in "well" edge carried by covers
      that render a generated illustration instead of a photo. It has to live in
@@ -104,8 +175,8 @@ h6 {
      Consumer apps must not redefine these: their stylesheet is imported after
      this one and would silently win, which is the drift these tokens exist to
      end. */
-  --shadow-card-image: 0 4px 14px rgba(120, 80, 50, 0.22);
-  --shadow-card-image-hover: 0 12px 28px rgba(120, 80, 50, 0.3);
+  --shadow-card-image: 0 4px 14px oklch(0.45 0 0 / 0.22);
+  --shadow-card-image-hover: 0 12px 28px oklch(0.45 0 0 / 0.3);
   --shadow-menu-cover-inset:
     inset 0 1px 2px oklch(1 0 0 / 0.15), inset 0 -1px 4px oklch(0 0 0 / 0.18);
 
@@ -148,35 +219,52 @@ h6 {
 }
 
 .dark {
-  --background: oklch(0.17 0.014 45);
-  --foreground: oklch(0.97 0.008 60);
-  --card: oklch(0.21 0.016 45);
-  --card-foreground: oklch(0.97 0.008 60);
-  --popover: oklch(0.21 0.016 45);
-  --popover-foreground: oklch(0.97 0.008 60);
-  --primary: oklch(0.98 0 0);
-  --primary-foreground: oklch(0.25 0.05 35);
+  /* Dark keeps its warmth: on a dark canvas a low-chroma warm tint reads as
+     "espresso", not as a cast — the light-mode problem is a light-mode
+     problem. These are bearmenu-fe's shipped dark values, promoted in 0.8.3
+     alongside the light ramp so both themes have one source of truth. */
+  --background: oklch(0.155 0.01 45);
+  --foreground: oklch(0.96 0.005 60);
+  --card: oklch(0.205 0.01 45);
+  --card-foreground: oklch(0.96 0.005 60);
+  --popover: oklch(0.205 0.01 45);
+  --popover-foreground: oklch(0.96 0.005 60);
+  --primary: oklch(0.66 0.09 45);
+  --primary-foreground: oklch(0.155 0.01 45);
   --secondary: oklch(0.24 0.018 45);
-  --secondary-foreground: oklch(0.97 0.008 60);
-  --muted: oklch(0.24 0.018 45);
-  --muted-foreground: oklch(0.6 0.012 60);
-  --accent: oklch(0.3 0.04 50);
-  --accent-foreground: oklch(0.97 0.008 60);
+  --secondary-foreground: oklch(0.96 0.005 60);
+  --muted: oklch(0.22 0.01 45);
+  --muted-foreground: oklch(0.72 0.008 60);
+  /* BREAKING alongside light: --accent is the terracotta, not a dark tint. */
+  --accent: oklch(0.66 0.09 45);
+  --accent-foreground: oklch(0.155 0.01 45);
+  --accent-subtle: oklch(0.255 0.022 45);
   /* AA-compliant on dark surfaces but dialed back from 0.68 to soften eye strain */
   --destructive: oklch(0.58 0.17 25.7);
   --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.3 0.015 45);
-  --input: oklch(0.3 0.015 45);
+  --border: oklch(0.32 0.01 45);
+  --input: oklch(0.32 0.01 45);
   --ring: oklch(0.98 0 0);
   --chart-1: oklch(0.488 0.243 264.376);
   --chart-2: oklch(0.696 0.17 162.48);
   --chart-3: oklch(0.769 0.188 70.08);
   --chart-4: oklch(0.627 0.265 303.9);
   --chart-5: oklch(0.645 0.246 16.439);
-  --surface: oklch(0.21 0.016 45);
+  --surface: oklch(0.205 0.01 45);
   --surface-foreground: var(--foreground);
   --surface-2: oklch(0.24 0.018 45);
   --line-soft: oklch(0.26 0.014 45);
+  /* Dark reaches "top plane" from BELOW — a step up off the canvas — where
+     light reaches it by being white. Same token, opposite direction. */
+  --surface-elevated: oklch(0.225 0.012 45);
+  --ink-primary: var(--foreground);
+  --ink-secondary: oklch(0.78 0.005 60);
+  --ink-tertiary: oklch(0.6 0.006 60);
+  /* Black, not the light ramp's near-neutral grey: on a 0.155 canvas a grey
+     shadow has nothing to darken. */
+  --shadow-card: 0 1px 3px oklch(0 0 0 / 0.2), 0 1px 2px oklch(0 0 0 / 0.15);
+  --shadow-card-hover: 0 4px 16px oklch(0 0 0 / 0.3), 0 1px 4px oklch(0 0 0 / 0.2);
+  --shadow-overlay: 0 8px 32px oklch(0 0 0 / 0.4), 0 2px 8px oklch(0 0 0 / 0.25);
   --sidebar: oklch(0.205 0 0);
   --sidebar-foreground: oklch(0.985 0 0);
   --sidebar-primary: oklch(0.488 0.243 264.376);
@@ -262,7 +350,12 @@ h6 {
   --color-surface: var(--surface);
   --color-surface-foreground: var(--surface-foreground);
   --color-surface-2: var(--surface-2);
+  --color-surface-elevated: var(--surface-elevated);
   --color-line-soft: var(--line-soft);
+  --color-accent-subtle: var(--accent-subtle);
+  --color-ink-primary: var(--ink-primary);
+  --color-ink-secondary: var(--ink-secondary);
+  --color-ink-tertiary: var(--ink-tertiary);
 
   /* Theme-aware shadow utilities — override Tailwind defaults so they
      stay visible on dark surfaces */
@@ -294,15 +387,44 @@ h6 {
     @apply border-border outline-ring/50;
   }
 
+  /* Reserve the scrollbar gutter so content does not jump when a page grows
+   * past one viewport, or when a modal locks scrolling.
+   *
+   * This was `overflow-y: scroll`, which reserved the same space by forcing a
+   * permanent scrollbar — and silently disabled every scroll lock in every
+   * consumer app.
+   *
+   * WHY IT BROKE THEM. `react-remove-scroll` — which Radix Dialog and Sheet
+   * use, and which vaul's Drawer sits on top of — locks the page by setting
+   * `overflow: hidden !important` on BODY. That only reaches the viewport
+   * through CSS overflow propagation, and the propagation rule applies ONLY
+   * while the ROOT element's overflow is `visible`: give <html> any explicit
+   * overflow and the viewport takes its value from <html> instead, so the body
+   * rule merely clips the body box while the document scrolls on behind the
+   * open dialog. Symptom: the page scrolls under every drawer and sheet, in
+   * every browser except Safari — where vaul has a second, `position: fixed`
+   * lock that does not depend on propagation (`usePositionFixed`, Safari-gated),
+   * which is what makes this look intermittent.
+   *
+   * `scrollbar-gutter: stable` reserves the same space without touching
+   * overflow, so <html> stays `visible` and the lock works as designed. Safari
+   * below 18.2 ignores the property, but Safari's overlay scrollbars take no
+   * layout space there, so there is nothing to reserve and nothing to shift.
+   *
+   * DO NOT put an `overflow` of any kind back on <html>. An app that needs to
+   * clip an axis puts it on `body`, which propagates rather than blocking. */
   html {
-    overflow-y: scroll; /* Always show vertical scrollbar to prevent layout shift */
+    scrollbar-gutter: stable;
   }
 
   body {
     @apply bg-background text-foreground;
   }
 
-  /* Prevent Radix UI from adding padding when locking scroll */
+  /* `react-remove-scroll` compensates for the scrollbar it removes by adding an
+   * equal `margin-right`. The gutter above is reserved permanently and never
+   * goes away, so that compensation would double up and shove the page sideways
+   * by a scrollbar width every time a dialog opens. Keep this. */
   body[data-scroll-locked] {
     margin-right: 0px !important;
   }