@bearmenu/ui 0.7.1 → 0.8.2

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

@@ -66,3 +66,73 @@ function SlidingPanelsDemo() {
 export const Default: Story = {
   render: () => <SlidingPanelsDemo />,
 };
+
+function KeyboardSafetyDemo() {
+  const [currentPanel, setCurrentPanel] = useState("list");
+
+  const panels = [
+    {
+      id: "list",
+      content: (
+        <div className="space-y-2 p-4">
+          <h3 className="text-lg font-semibold">Items</h3>
+          {["Espresso", "Cortado", "Flat white", "Cold brew"].map((item) => (
+            <Button
+              key={item}
+              variant="outline"
+              className="w-full justify-start"
+              onClick={() => setCurrentPanel("detail")}
+            >
+              {item}
+            </Button>
+          ))}
+        </div>
+      ),
+    },
+    {
+      id: "detail",
+      parentId: "list",
+      showBackButton: true,
+      backButtonLabel: "Assign",
+      content: (
+        <div className="space-y-3 p-4">
+          <p className="text-muted-foreground text-sm">
+            Tab through this panel — focus never reaches the list behind it, because inactive
+            panels are <code>inert</code>.
+          </p>
+          <div className="flex gap-2">
+            <Button variant="outline">Split</Button>
+            <Button variant="outline">Assign</Button>
+            <Button onClick={() => setCurrentPanel("list")}>Done</Button>
+          </div>
+        </div>
+      ),
+    },
+  ];
+
+  return (
+    <div className="w-[400px] space-y-4">
+      <p className="text-muted-foreground text-sm">
+        Open the detail panel, then press Tab repeatedly: only the visible panel is reachable.
+      </p>
+      <div className="rounded-lg border overflow-hidden">
+        <SlidingPanels
+          panels={panels}
+          currentPanel={currentPanel}
+          onPanelChange={setCurrentPanel}
+        />
+      </div>
+      <Button variant="ghost">Control after the panels</Button>
+    </div>
+  );
+}
+
+/**
+ * Hidden panels stay mounted so the slide can animate, but they carry `inert`
+ * — their controls are out of the tab order, untargetable by pointer, and
+ * skipped by find-in-page. Tab from the top of this story: focus goes through
+ * the active panel and straight on to "Control after the panels".
+ */
+export const HiddenPanelsAreNotTabbable: Story = {
+  render: () => <KeyboardSafetyDemo />,
+};

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

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi } from "vitest";
+import { useState } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SlidingPanels, type Panel } from "./sliding-panels";
+
+const basePanels: Panel[] = [
+  { id: "one", content: <button type="button">Action one</button> },
+  {
+    id: "two",
+    showBackButton: true,
+    backButtonLabel: "Two",
+    content: <button type="button">Action two</button>,
+  },
+  { id: "three", content: <button type="button">Action three</button> },
+];
+
+const panelWrappers = () =>
+  Array.from(document.querySelectorAll<HTMLElement>('[data-slot="sliding-panel"]'));
+
+// The back button is icon-only, so it is the one button in the active panel
+// with no text content.
+const backButton = () =>
+  screen.getAllByRole("button").filter((button) => button.textContent === "")[0];
+
+function Controlled({ initial = "one" }: { initial?: string }) {
+  const [current, setCurrent] = useState(initial);
+  return (
+    <SlidingPanels panels={basePanels} currentPanel={current} onPanelChange={setCurrent} />
+  );
+}
+
+describe("SlidingPanels", () => {
+  it("renders every panel so transitions can animate", () => {
+    render(<Controlled />);
+    expect(panelWrappers()).toHaveLength(3);
+    expect(screen.getByText("Action three")).toBeInTheDocument();
+  });
+
+  it("marks inactive panels inert and leaves the active one interactive", () => {
+    render(<Controlled initial="two" />);
+    const [one, two, three] = panelWrappers();
+    expect(one).toHaveAttribute("inert");
+    expect(two).not.toHaveAttribute("inert");
+    expect(three).toHaveAttribute("inert");
+  });
+
+  it("keeps aria-hidden in sync with inert for engines that ignore inert", () => {
+    render(<Controlled initial="two" />);
+    const [one, two] = panelWrappers();
+    expect(one).toHaveAttribute("aria-hidden", "true");
+    expect(two).not.toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("exposes active state via data-state", () => {
+    render(<Controlled initial="three" />);
+    expect(panelWrappers().map((el) => el.dataset.state)).toEqual([
+      "inactive",
+      "inactive",
+      "active",
+    ]);
+  });
+
+  it("moves inert onto the previously active panel after navigation", async () => {
+    const user = userEvent.setup();
+    render(<Controlled initial="two" />);
+    await user.click(backButton());
+
+    const [one, two] = panelWrappers();
+    expect(one).not.toHaveAttribute("inert");
+    expect(two).toHaveAttribute("inert");
+  });
+
+  it("keeps the transform transition classes on inert panels", () => {
+    render(<Controlled initial="two" />);
+    const [one, two, three] = panelWrappers();
+    expect(one.className).toContain("transition-transform");
+    expect(one.className).toContain("-translate-x-[calc(100%+8px)]");
+    expect(two.className).toContain("translate-x-0");
+    expect(three.className).toContain("translate-x-[calc(100%+8px)]");
+  });
+
+  it("never leaves the active panel inert in tree mode", () => {
+    const treePanels: Panel[] = [
+      { id: "root", content: <button type="button">Root</button> },
+      { id: "child", parentId: "root", content: <button type="button">Child</button> },
+      { id: "sibling", parentId: "root", content: <button type="button">Sibling</button> },
+    ];
+    render(
+      <SlidingPanels panels={treePanels} currentPanel="child" onPanelChange={vi.fn()} />
+    );
+    const [root, child, sibling] = panelWrappers();
+    expect(root).toHaveAttribute("inert");
+    expect(child).not.toHaveAttribute("inert");
+    expect(sibling).toHaveAttribute("inert");
+  });
+
+  it("navigates back to the parent panel from the back button", async () => {
+    const user = userEvent.setup();
+    const onPanelChange = vi.fn();
+    const treePanels: Panel[] = [
+      { id: "root", content: <button type="button">Root</button> },
+      {
+        id: "child",
+        parentId: "root",
+        showBackButton: true,
+        content: <button type="button">Child</button>,
+      },
+    ];
+    render(
+      <SlidingPanels panels={treePanels} currentPanel="child" onPanelChange={onPanelChange} />
+    );
+    await user.click(backButton());
+    expect(onPanelChange).toHaveBeenCalledWith("root");
+  });
+});

package/src/components/sliding-panels.tsx

@@ -82,6 +82,7 @@ export const SlidingPanels = ({
 
   return (
     <div
+      data-slot="sliding-panels"
       className={cn(
         "relative overflow-clip transition-[height] duration-500 ease-[cubic-bezier(0.32,0.72,0,1)]",
         className
@@ -101,12 +102,25 @@ export const SlidingPanels = ({
             ref={(el) => {
               panelRefs.current[index] = el;
             }}
+            data-slot="sliding-panel"
+            data-state={isActive ? "active" : "inactive"}
             className={cn(
               "absolute top-0 left-0 w-full transition-transform duration-500 ease-[cubic-bezier(0.32,0.72,0,1)]",
               isActive && "translate-x-0",
               isLeft && "-translate-x-[calc(100%+8px)]",
               isRight && "translate-x-[calc(100%+8px)]"
             )}
+            // Off-screen panels stay mounted (so the slide can animate), which
+            // used to leave their controls in the tab order behind the active
+            // panel. `inert` takes them out of tab order, pointer targeting and
+            // find-in-page without touching layout or the transform transition.
+            // Written as `true | undefined` rather than a raw boolean: HTML
+            // treats *any* value as inert, so a literal `inert={false}` would
+            // disable the active panel on renderers that stringify booleans.
+            // `aria-hidden` is kept alongside it: modern engines derive that
+            // semantic from `inert` itself (no double announcement), but older
+            // ones that ignore `inert` still need it to hide the subtree.
+            inert={!isActive || undefined}
             aria-hidden={!isActive}
           >
             {panel.showBackButton && (

package/src/components/sonner.tsx

@@ -1,10 +1,10 @@
 "use client";
 
 import {
+  CircleAlertIcon,
   CircleCheckIcon,
   InfoIcon,
   Loader2Icon,
-  OctagonXIcon,
   TriangleAlertIcon,
 } from "lucide-react";
 import { useTheme } from "next-themes";
@@ -21,7 +21,7 @@ const Toaster = ({ ...props }: ToasterProps) => {
         success: <CircleCheckIcon className="size-4" />,
         info: <InfoIcon className="size-4" />,
         warning: <TriangleAlertIcon className="size-4" />,
-        error: <OctagonXIcon className="size-4" />,
+        error: <CircleAlertIcon className="size-4" />,
         loading: <Loader2Icon className="size-4 animate-spin" />,
       }}
       style={

package/src/components/stepper.tsx

@@ -76,8 +76,11 @@ const Stepper = React.forwardRef<HTMLElement, StepperProps>(
                   <span
                     className={cn(
                       "whitespace-nowrap transition-colors",
+                      // current and complete share a weight; COLOUR carries the
+                      // state (full → 80% → 40%). `complete` was 500, the one
+                      // step that is not in the 400/600/700 system.
                       status === "current" && "font-semibold text-foreground",
-                      status === "complete" && "font-medium text-foreground/80",
+                      status === "complete" && "font-semibold text-foreground/80",
                       status === "upcoming" && "text-foreground/40",
                     )}
                   >

package/src/components/table.tsx

@@ -56,7 +56,7 @@ const TableFooter = React.forwardRef<
   <tfoot
     ref={ref}
     data-slot="table-footer"
-    className={cn("border-t border-border bg-muted/50 font-medium [&>tr]:last:border-b-0", className)}
+    className={cn("border-t border-border bg-muted/50 font-semibold [&>tr]:last:border-b-0", className)}
     {...props}
   />
 ));

package/src/components/tabs.tsx

@@ -115,7 +115,7 @@ const TabsTrigger = React.forwardRef<
       ref={composedRef}
       data-slot="tabs-trigger"
       className={cn(
-        "relative inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+        "relative inline-flex items-center justify-center whitespace-nowrap text-sm font-semibold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
         variant === "pill" &&
           "rounded-xl px-4 py-1.5 text-muted-foreground hover:text-foreground data-[state=active]:text-foreground",
         variant === "underline" &&

package/src/components/tag-group.tsx

@@ -18,7 +18,7 @@ const TagGroup = React.forwardRef<
     {...props}
   >
     {label && !srLabel && (
-      <span className="mr-1 text-xs font-medium text-muted-foreground">{label}</span>
+      <span className="mr-1 text-xs font-semibold text-muted-foreground">{label}</span>
     )}
     {children}
   </div>

package/src/components/tag.tsx

@@ -6,7 +6,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../lib/utils";
 
 const tagVariants = cva(
-  "inline-flex items-center gap-1 rounded-full border text-xs font-medium transition-colors",
+  "inline-flex items-center gap-1 rounded-full border text-xs font-semibold transition-colors",
   {
     variants: {
       variant: {

package/src/components/text.test.tsx

@@ -2,6 +2,24 @@ import { describe, it, expect } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { Text, textVariants } from "./text";
 
+// Every variant in the scale. Kept explicit (not derived from the cva config)
+// so adding a variant forces a deliberate edit here — the point of a CLOSED
+// set is that growing it is a decision, not a side effect.
+const VARIANTS = [
+  "display",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "body-lg",
+  "body",
+  "body-sm",
+  "small",
+  "caption",
+  "label",
+  "overline",
+] as const;
+
 // ─── textVariants utility ────────────────────────────────────────────────────
 
 describe("textVariants", () => {
@@ -29,17 +47,33 @@ describe("textVariants", () => {
     expect(textVariants({ variant: "body" })).toContain("text-base");
     expect(textVariants({ variant: "body-sm" })).toContain("text-sm");
     expect(textVariants({ variant: "caption" })).toContain("text-xs");
-    expect(textVariants({ variant: "label" })).toContain("font-medium");
+    expect(textVariants({ variant: "label" })).toContain("font-semibold");
     expect(textVariants({ variant: "overline" })).toContain("uppercase");
   });
 
-  it("maps weight props", () => {
+  it("maps weight props onto the 3-weight scale", () => {
     expect(textVariants({ weight: "normal" })).toContain("font-normal");
-    expect(textVariants({ weight: "medium" })).toContain("font-medium");
     expect(textVariants({ weight: "semibold" })).toContain("font-semibold");
     expect(textVariants({ weight: "bold" })).toContain("font-bold");
   });
 
+  // The scale is 400/600/700. `medium` survives as a deprecated alias so the
+  // existing call sites keep compiling, but it must never emit 500 again.
+  it("never emits weight 500", () => {
+    expect(textVariants({ weight: "medium" })).toContain("font-semibold");
+    for (const variant of VARIANTS) {
+      expect(textVariants({ variant })).not.toContain("font-medium");
+    }
+  });
+
+  // `body-lg` and `small` are deprecated duplicates. They must stay
+  // byte-compatible with the role that replaced them, or the two apps drift
+  // back onto two names for one size.
+  it("keeps deprecated aliases identical to their replacements", () => {
+    expect(textVariants({ variant: "body-lg" })).toBe(textVariants({ variant: "body" }));
+    expect(textVariants({ variant: "small" })).toContain("text-sm");
+  });
+
   it("maps leading props", () => {
     expect(textVariants({ leading: "none" })).toContain("leading-none");
     expect(textVariants({ leading: "tight" })).toContain("leading-tight");

package/src/components/text.tsx

@@ -2,6 +2,24 @@ import * as React from "react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../lib/utils";
 
+/**
+ * The type scale is a CLOSED set of roles. Seven carry every surface:
+ *
+ *   h1       page title          30/700
+ *   h3       section heading     20/600
+ *   body     running prose       16/400 relaxed
+ *   label    row / item title    14/600
+ *   body-sm  secondary fact      14/400
+ *   overline eyebrow             12/600 uppercase
+ *   caption  fine print          12/400
+ *
+ * Emphasis, colour and tabular figures are ORTHOGONAL modifiers (`weight`,
+ * `color`, className) — they must never be expressed by changing SIZE. A
+ * paragraph that steps 16 → 14 mid-sentence to mark its lead reads as two
+ * paragraphs jammed together; that is what the modifiers exist for.
+ *
+ * Weights are 400 / 600 / 700. 500 is not in the system.
+ */
 const textVariants = cva("", {
   variants: {
     variant: {
@@ -10,12 +28,19 @@ const textVariants = cva("", {
       h2: "text-2xl font-semibold tracking-tight",
       h3: "text-xl font-semibold",
       h4: "text-lg font-semibold leading-none tracking-tight",
+      /** @deprecated Now identical to `body`. Use `body`. */
       "body-lg": "text-base leading-relaxed",
-      body: "text-base leading-normal",
+      // `leading-relaxed`, absorbing what `body-lg` was: 16px is the prose size
+      // and prose wants relaxed leading. Two variants differing only in
+      // line-height forced every author to choose between two names for one
+      // role, and the two apps duly diverged onto different ones.
+      body: "text-base leading-relaxed",
       "body-sm": "text-sm leading-relaxed",
+      /** @deprecated Use `body-sm` + `color="muted"` — same size, second name. */
       small: "text-sm text-muted-foreground",
       caption: "text-xs leading-normal text-muted-foreground",
-      label: "text-sm font-medium",
+      // 600, not 500 — see the weight scale below.
+      label: "text-sm font-semibold",
       overline: "text-xs font-semibold uppercase tracking-wider",
     },
     color: {
@@ -26,9 +51,13 @@ const textVariants = cva("", {
       "primary-foreground": "text-primary-foreground",
       inherit: "",
     },
+    // Three weights: 400 / 600 / 700. A fourth step is not a hierarchy level,
+    // it is noise — 500 against 600 is indistinguishable at body sizes while
+    // still counting as a separate treatment when you audit a screen.
     weight: {
       normal: "font-normal",
-      medium: "font-medium",
+      /** @deprecated Alias for `semibold`. 500 is not in the 3-weight system. */
+      medium: "font-semibold",
       semibold: "font-semibold",
       bold: "font-bold",
     },

package/src/components/toggle.tsx

@@ -7,7 +7,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../lib/utils";
 
 const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium hover:bg-accent/50 hover:text-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 transition-colors aria-invalid:ring-2 aria-invalid:ring-destructive/40 whitespace-nowrap",
+  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-semibold hover:bg-accent/50 hover:text-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 transition-colors aria-invalid:ring-2 aria-invalid:ring-destructive/40 whitespace-nowrap",
   {
     variants: {
       variant: {

package/src/globals.css

@@ -89,6 +89,26 @@ h6 {
   --shadow-alpha-xl: 0.18;
   --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.
+     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.
+
+     --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
+     the SAME box-shadow value as the outer lift — box-shadow is one property,
+     so two `shadow-*` utilities can't compose — which is why it is a token
+     rather than a second class. Identical in both themes.
+
+     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-menu-cover-inset:
+    inset 0 1px 2px oklch(1 0 0 / 0.15), inset 0 -1px 4px oklch(0 0 0 / 0.18);
+
   /* ─── Motion System v1.0 ─────────────────────────────────────────────
      Three layers of tokens. Feature code reads only `--duration-*` and
      `--ease-*` semantic names; raw values live here.
@@ -181,6 +201,11 @@ h6 {
   --shadow-alpha-lg: 0.5;
   --shadow-alpha-xl: 0.55;
   --shadow-alpha-2xl: 0.65;
+
+  /* Neutral black on a dark canvas — a warm-brown lift is invisible there.
+     The inset well is unchanged between themes, so it has no override. */
+  --shadow-card-image: 0 4px 14px rgba(0, 0, 0, 0.45);
+  --shadow-card-image-hover: 0 12px 28px rgba(0, 0, 0, 0.55);
 }
 
 @theme inline {
@@ -321,26 +346,38 @@ h6 {
   box-shadow: 0 0 12px color-mix(in oklch, var(--accent) 60%, transparent);
 }
 
-/* Scroll-to highlight pulse */
+/* Scroll-to highlight — marks the element a deep link just scrolled to.
+ *
+ * A RIPPLE: a ring born at the element's edge that expands outward and fades to
+ * nothing, three times. The movement is the signal, so it reads on any
+ * background — which matters because the targets include saturated colour
+ * fields in the same warm hue family as `--primary`, where a static ring is
+ * brown-on-brown and disappears into the thing it is marking.
+ *
+ * This replaced two attempts that both failed for the same underlying reason:
+ * an outline whose offset breathed 3px (no colour travel — read as a static
+ * ring), then a ring that faded in place (better, but still competing with the
+ * field on colour rather than on motion).
+ *
+ * Spread-only box-shadow, so nothing reflows: the ripple paints outside the
+ * border box and never affects layout. It IS clippable by an ancestor's
+ * `overflow-hidden`, unlike an outline — target an element whose ancestors
+ * don't clip. */
 @keyframes highlight-pulse {
   0% {
-    outline-color: var(--primary);
-    outline-offset: 3px;
+    box-shadow: 0 0 0 0 color-mix(in oklch, var(--primary) 55%, transparent);
   }
-  50% {
-    outline-color: var(--primary);
-    outline-offset: 6px;
+  70% {
+    box-shadow: 0 0 0 18px transparent;
   }
   100% {
-    outline-color: var(--primary);
-    outline-offset: 3px;
+    box-shadow: 0 0 0 0 transparent;
   }
 }
 
 .scroll-highlight {
-  outline: 2px solid var(--primary);
-  outline-offset: 3px;
-  animation: highlight-pulse 1s ease-in-out 3;
+  border-radius: var(--radius);
+  animation: highlight-pulse 1.4s ease-out 3;
 }
 
 /* Scrollbar styling — token-driven, single rule covers both themes */
@@ -477,6 +514,11 @@ h6 {
   .motion-live-pulse {
     animation: none;
   }
+  /* Keep the ring — it is the only thing identifying the target — but stop it
+     from pulsing. */
+  .scroll-highlight {
+    animation: none;
+  }
 }
 
 /* Swiper pagination styling for experience cards */

package/src/lib/card-hover.ts

@@ -0,0 +1,87 @@
+/**
+ * Card hover motion tokens — the shared recipe for any card with a cover image.
+ *
+ * Every card type animates the same set of properties (transform on the card
+ * root, transform on the image, box-shadow on the image wrapper) so the timings
+ * must stay in lockstep. Defining the tokens in one place is the only way to
+ * guarantee a hover that feels identical across a mixed grid.
+ *
+ * Prefer the COMPOSED tokens (`HOVER_IMAGE_WRAPPER`, `HOVER_IMAGE_MOTION`) over
+ * re-assembling a recipe from `HOVER_DURATION` + `HOVER_EASE` + a shadow at the
+ * call site. Consumers that did the latter silently shipped without a hover
+ * shadow — the transition and the resting shadow were wired up, the hover state
+ * simply never was, and nothing failed loudly. One class per element is what
+ * stops that.
+ *
+ * Companion CSS custom properties live in `./globals.css`:
+ *   --shadow-card-image / --shadow-card-image-hover / --shadow-menu-cover-inset
+ * They carry the dark-mode override, so none of these tokens needs a `dark:`
+ * twin of every state. A consumer app must NOT redefine them locally — app
+ * stylesheets are imported after this one and would silently win.
+ *
+ * Why we don't animate filter / mix-blend-mode opacity:
+ *   - filter animations (`saturate`, `brightness`) on <img> are CPU-heavy and
+ *     can hitch on lower-end devices.
+ *   - mix-blend-multiply opacity transitions composite at unpredictable frame
+ *     rates so they never sync with transform/opacity transitions.
+ * Restricting hover to transform + box-shadow keeps every element on the same
+ * GPU-composited frame, which is what makes the in/out feel perfectly synced.
+ */
+
+export const HOVER_DURATION = "duration-[320ms]";
+export const HOVER_EASE = "ease-[cubic-bezier(0.4,0,0.2,1)]";
+
+/** Apply to the card root — composes the base transform transition. */
+export const HOVER_MOTION = `transition-transform ${HOVER_DURATION} ${HOVER_EASE} motion-reduce:transition-none will-change-transform`;
+
+/** Apply to elements that animate box-shadow on hover (image wrappers). */
+export const HOVER_SHADOW_MOTION = `transition-shadow ${HOVER_DURATION} ${HOVER_EASE}`;
+
+/** Grid/standard/hero card variants — full lift. */
+export const HOVER_LIFT_GRID = "[@media(hover:hover)]:hover:-translate-y-1";
+
+/**
+ * Same lift as `HOVER_LIFT_GRID`, but driven by a NAMED `group/card` ancestor
+ * instead of the element's own `:hover`.
+ *
+ * For overlays that must render as SIBLINGS of the interactive card rather than
+ * children — e.g. a pill that is itself a button or link, which would be
+ * invalid ARIA nested inside the card's own `role="button"` / `<a>`. A sibling
+ * can't inherit the card's transform, so it stays pinned while the card lifts
+ * out from under it. Putting `group/card` on the shared wrapper and this token
+ * on BOTH the card and the overlay moves them as one, and means hovering the
+ * overlay lifts the card too (its own `:hover` never fires for a sibling).
+ */
+export const HOVER_LIFT_GRID_GROUP = "[@media(hover:hover)]:group-hover/card:-translate-y-1";
+
+/** List/compact row variants — half lift since rows are denser. */
+export const HOVER_LIFT_LIST = "[@media(hover:hover)]:hover:-translate-y-0.5";
+
+/** Image inside a card — scales subtly on group hover. */
+export const HOVER_IMAGE_SCALE = "group-hover:scale-[1.05]";
+
+/** Drop-in className for the `<img>` element inside card image wrappers. */
+export const HOVER_IMAGE_MOTION = `${HOVER_MOTION} ${HOVER_IMAGE_SCALE}`;
+
+/** Warm image-wrapper shadow that deepens on group hover. */
+export const HOVER_IMAGE_SHADOW =
+  "shadow-[var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-card-image-hover)]";
+
+/**
+ * Same lift, for covers that ALSO carry an inset "well" edge on a generated
+ * illustration rather than a photo. `box-shadow` is a single property, so the
+ * inset can't be a second `shadow-*` class stacked on `HOVER_IMAGE_SHADOW`; it
+ * has to be part of the same value, which is why both states are spelled out.
+ */
+export const HOVER_IMAGE_SHADOW_INSET =
+  "shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image-hover)]";
+
+/**
+ * The whole cover-wrapper recipe: shadow transition + the warm lift. Pair with
+ * `HOVER_IMAGE_MOTION` on the image inside (covers that render a generated
+ * illustration have no image to scale and use this alone).
+ */
+export const HOVER_IMAGE_WRAPPER = `${HOVER_SHADOW_MOTION} ${HOVER_IMAGE_SHADOW}`;
+
+/** `HOVER_IMAGE_WRAPPER` for the inset-well covers. */
+export const HOVER_IMAGE_WRAPPER_INSET = `${HOVER_SHADOW_MOTION} ${HOVER_IMAGE_SHADOW_INSET}`;