@elabs-ai/components-ui 4.2.0 → 5.1.0

package/src/components/metric-card/metric-card.tsx

@@ -7,7 +7,34 @@ import { CopyableValue } from "../copyable-value";
 import { Skeleton } from "../skeleton";
 import { useLocale } from "../locale-provider";
 import { cn } from "../../lib/cn";
-import { type NumberFormatKind, numberFormatOptions } from "../../lib/compact-number";
+import {
+  type NumberFormat,
+  type ResolvedNumberFormat,
+  resolveNumberFormat,
+} from "../../lib/compact-number";
+
+/**
+ * Applies a {@link ResolvedNumberFormat}'s `prefix`/`suffix`/`parens` on top
+ * of the plain `Intl` string `formatNumber` produces — the two things Intl
+ * itself cannot render (RM-109). Twin of `formatResolvedChartValue`
+ * (`packages/charts/src/charts/chart-formatters.ts`).
+ */
+function formatResolvedNumber(
+  resolved: ResolvedNumberFormat,
+  formatNumber: (n: number, opts?: Intl.NumberFormatOptions) => string,
+  value: number,
+): string {
+  const numeric = formatNumber(resolved.parens ? Math.abs(value) : value, resolved.options);
+  const signed = resolved.parens && value < 0 ? `(${numeric})` : numeric;
+  return `${resolved.prefix}${signed}${resolved.suffix}`;
+}
+
+/*
+ * ADR 0012: this is the ONE KPI tile — `@elabs-ai/components-charts` re-exports it.
+ * RM-072 adds `size` (sm | md | lg) for dashboard-sheet tiles and a `sparkline`
+ * slot under the value. `ui` never imports `charts`: the host passes the
+ * `<Sparkline …/>` element in.
+ */
 
 /*
  * `emphasis` — size/weight/space ONLY, no new hue (research 11 §B.5 KPI-1/5):
@@ -22,8 +49,14 @@ const metricValueVariants = cva("tabular-nums text-foreground", {
       default: "text-2xl font-semibold tracking-tight",
       headline: "text-kpi",
     },
+    /* `md` adds nothing (today's rungs); `sm`/`lg` override the size via `cn()`. */
+    size: {
+      sm: "text-title",
+      md: "",
+      lg: "text-kpi",
+    },
   },
-  defaultVariants: { emphasis: "default" },
+  defaultVariants: { emphasis: "default", size: "md" },
 });
 
 const metricContentVariants = cva("space-y-2", {
@@ -32,12 +65,36 @@ const metricContentVariants = cva("space-y-2", {
       default: "p-5",
       headline: "p-6",
     },
+    size: {
+      sm: "space-y-1 p-3",
+      md: "",
+      lg: "p-6",
+    },
+  },
+  defaultVariants: { emphasis: "default", size: "md" },
+});
+
+const metricSparklineVariants = cva("", {
+  variants: {
+    size: {
+      /* never rendered — `sm` drops the slot; kept so the axis is total */
+      sm: "",
+      md: "pt-1",
+      lg: "min-h-12 pt-2",
+    },
   },
-  defaultVariants: { emphasis: "default" },
+  defaultVariants: { size: "md" },
 });
 
 export type MetricCardEmphasis = NonNullable<VariantProps<typeof metricValueVariants>["emphasis"]>;
 
+/**
+ * Tile tier (RM-072). `sm`: label + value only (no icon, delta, description,
+ * sparkline, visual or evidence); `md`: the default tile; `lg`: the kpi value
+ * rung with more room for the `sparkline` slot.
+ */
+export type MetricCardSize = NonNullable<VariantProps<typeof metricValueVariants>["size"]>;
+
 /**
  * How a NUMERIC `value` is rendered. A function takes over completely.
  *
@@ -46,8 +103,15 @@ export type MetricCardEmphasis = NonNullable<VariantProps<typeof metricValueVari
  * away via `CopyableValue`. Anything that is not a `number` (a string, an
  * element) is passed through untouched, so every existing call site is
  * unaffected.
+ *
+ * Also accepts the object form (RM-109, `NumberFormatSpec` —
+ * `{ decimals, abbreviate, sign, prefix, suffix, … }`,
+ * `packages/ui/src/lib/compact-number.ts`) for a tile that needs e.g.
+ * `{ decimals: 1, suffix: "%" }` without hand-formatting the string itself.
+ * The two preset-string cases render byte-for-byte as before this type
+ * widened — only a spec OBJECT argument reaches the new code path.
  */
-export type MetricCardValueFormat = NumberFormatKind | ((value: number) => ReactNode);
+export type MetricCardValueFormat = NumberFormat | ((value: number) => ReactNode);
 
 export interface MetricCardProps
   extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof metricValueVariants> {
@@ -74,8 +138,13 @@ export interface MetricCardProps
   /** Whether "up" is good (green) — flip for metrics where down is good. */
   positiveIsGood?: boolean;
   icon?: ReactNode;
-  /** Optional inline visual (e.g. a sparkline) shown under the value/description. */
+  /** Optional inline visual shown under the value/description. */
   visual?: ReactNode;
+  /**
+   * Trend slot rendered directly under the value (RM-072) — pass a
+   * `<Sparkline …/>` from `@elabs-ai/components-charts`. Hidden at `size="sm"`.
+   */
+  sparkline?: ReactNode;
   /**
    * Optional grounding footer (research 11 §B.5 KPI-3) — connects a cited
    * figure to its source (e.g. an `EvidenceChip` from `@elabs-ai/components-ai`). Rendered
@@ -111,8 +180,10 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
     positiveIsGood = true,
     icon,
     visual,
+    sparkline,
     evidence,
     emphasis,
+    size,
     loading = false,
     announceLoading = true,
     className,
@@ -130,7 +201,11 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
     ? value
     : typeof valueFormat === "function"
       ? valueFormat(value)
-      : formatNumber(value, numberFormatOptions(valueFormat, value, currency));
+      : formatResolvedNumber(
+          resolveNumberFormat(valueFormat, value, currency),
+          formatNumber,
+          value,
+        );
   // Only offer the exact figure when the display actually differs from it —
   // a button around a value that was never shortened is noise.
   const showsExact = isNumeric && String(formattedValue) === String(value);
@@ -152,11 +227,14 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
   // polarity is otherwise invisible to AT. See accessibility.md, #162.
   const directionLabel = deltaDirection === "up" ? "up" : deltaDirection === "down" ? "down" : "";
   const polarityLabel = good === null ? "" : good ? ", favorable" : ", unfavorable";
+  // `sm` is label + value only: every secondary row is dropped (RM-072).
+  const compact = size === "sm";
+  const valueClassName = cn(metricValueVariants({ emphasis, size }));
 
   return (
     <Card ref={ref} className={cn("overflow-hidden", className)} {...props}>
       <CardContent
-        className={metricContentVariants({ emphasis })}
+        className={cn(metricContentVariants({ emphasis, size }))}
         {...(loading && announceLoading ? { role: "status", "aria-live": "polite" as const } : {})}
       >
         {loading && announceLoading ? (
@@ -185,7 +263,7 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
           )}
           {/* `shrink-0`: the icon is a fixed 16px mark, so the LABEL is what
               gives way when the row runs out of width. */}
-          {icon ? (
+          {icon && !compact ? (
             <span className="shrink-0 text-muted-foreground [&_svg]:size-4">{icon}</span>
           ) : null}
         </div>
@@ -194,7 +272,7 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
             <Skeleton className={emphasis === "headline" ? "h-9 w-28" : "h-8 w-24"} />
           ) : canCopyExact ? (
             <CopyableValue
-              className={metricValueVariants({ emphasis })}
+              className={valueClassName}
               // Two tiles in one grid can compact to the same display ("$1.2M"),
               // and the visible label is a sibling node the button's name does
               // not include — so without this a screen-reader user tabbing the
@@ -208,9 +286,9 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
               {formattedValue}
             </CopyableValue>
           ) : (
-            <span className={metricValueVariants({ emphasis })}>{formattedValue}</span>
+            <span className={valueClassName}>{formattedValue}</span>
           )}
-          {delta ? (
+          {delta && !compact ? (
             loading ? (
               <Skeleton className="h-4 w-14" />
             ) : (
@@ -227,17 +305,22 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
             )
           ) : null}
         </div>
-        {description ? (
+        {sparkline && !compact ? (
+          <div className={metricSparklineVariants({ size })}>
+            {loading ? <Skeleton className="h-8 w-full" /> : sparkline}
+          </div>
+        ) : null}
+        {description && !compact ? (
           loading ? (
             <Skeleton className="h-3 w-32" />
           ) : (
             <p className="text-meta font-normal text-muted-foreground">{description}</p>
           )
         ) : null}
-        {visual ? (
+        {visual && !compact ? (
           <div className="pt-1">{loading ? <Skeleton className="h-8 w-full" /> : visual}</div>
         ) : null}
-        {evidence ? (
+        {evidence && !compact ? (
           <div className="pt-1 text-meta font-normal text-muted-foreground">
             {loading ? <Skeleton className="h-3 w-24" /> : evidence}
           </div>

package/src/components/nav-user/nav-user.test.tsx

@@ -1,5 +1,6 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { SidebarProvider } from "../sidebar";
 import { NavUser } from "./nav-user";
 
@@ -26,4 +27,25 @@ describe("NavUser", () => {
     );
     expect(screen.getAllByText("JS").length).toBeGreaterThan(0);
   });
+
+  it("opens the account menu with Settings and Sign out", async () => {
+    const onSignOut = vi.fn();
+    render(
+      <Wrapper>
+        <NavUser
+          user={{ name: "Jane Doe", email: "jane@example.com" }}
+          settingsHref="/settings"
+          onSignOut={onSignOut}
+        />
+      </Wrapper>,
+    );
+    const user = userEvent.setup();
+    await user.click(screen.getByRole("button", { name: "Jane Doe jane@example.com" }));
+    expect(await screen.findByRole("menuitem", { name: "Settings" })).toHaveAttribute(
+      "href",
+      "/settings",
+    );
+    await user.click(screen.getByRole("menuitem", { name: "Sign out" }));
+    expect(onSignOut).toHaveBeenCalledTimes(1);
+  });
 });

package/src/components/nav-user/nav-user.tsx

@@ -1,6 +1,7 @@
 "use client";
 
-import { BadgeCheck, Bell, ChevronsUpDown, CreditCard, LogOut, Sparkles } from "lucide-react";
+import type { ReactNode } from "react";
+import { ChevronsUpDown, LogOut, Settings } from "lucide-react";
 import { Avatar, AvatarFallback, AvatarImage } from "../avatar";
 import {
   DropdownMenu,
@@ -11,6 +12,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "../dropdown-menu";
+import { useLocale } from "../locale-provider";
 import { SidebarMenu, SidebarMenuButton, SidebarMenuItem, useSidebar } from "../sidebar";
 
 export interface NavUserUser {
@@ -22,24 +24,41 @@ export interface NavUserUser {
 
 export interface NavUserProps {
   user: NavUserUser;
+  /** Fires when "Settings" is chosen. Ignored when `settingsHref` is set. */
+  onSettings?: () => void;
+  /** Route of the settings screen — "Settings" renders as a link to it. */
+  settingsHref?: string;
+  /** Fires when "Sign out" is chosen. */
+  onSignOut?: () => void;
+  /**
+   * Extra `DropdownMenuItem`s, placed above "Settings" (e.g. Profile, Billing).
+   * Settings and Sign out are always present — they are the standard pair.
+   */
+  children?: ReactNode;
 }
 
-/**
- * Sidebar account / user menu. Shared primitive from sidebar-04 (issue #99).
- * Renders a trigger showing name + email + avatar; the dropdown exposes
- * account, billing, notifications and log-out actions.
- *
- * Wire your own action handlers by composing custom `DropdownMenuItem` children
- * if you need more than the default actions — or extend via className.
- */
-export function NavUser({ user }: NavUserProps) {
-  const { isMobile } = useSidebar();
-  const initials = user.name
+function initialsOf(name: string): string {
+  return name
     .split(" ")
-    .map((n) => n[0])
+    .map((part) => part[0])
     .join("")
     .slice(0, 2)
     .toUpperCase();
+}
+
+/**
+ * The standard sidebar footer: the signed-in user (avatar, name, email) as one
+ * row that opens the account menu — Settings, then Sign out. EVERY app shell's
+ * nav rail ends with this; settings never sits in the footer as a loose nav
+ * row, and the footer carries no environment/meta line.
+ *
+ * Collapsed to the 48px icon rail the row is the avatar alone, and its
+ * accessible name is written out because the visible label is gone.
+ */
+export function NavUser({ user, onSettings, settingsHref, onSignOut, children }: NavUserProps) {
+  const { isMobile } = useSidebar();
+  const { t } = useLocale();
+  const initials = initialsOf(user.name);
 
   return (
     <SidebarMenu>
@@ -48,63 +67,59 @@ export function NavUser({ user }: NavUserProps) {
           <DropdownMenuTrigger asChild>
             <SidebarMenuButton
               size="lg"
-              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground md:h-8 md:p-0"
+              tooltip={user.name}
+              // Written out: collapsed, the trigger is only an avatar, so its
+              // contents cannot name it. Same string as the visible label, in
+              // reading order (WCAG 2.5.3).
+              aria-label={`${user.name} ${user.email}`}
+              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
             >
-              <Avatar className="h-8 w-8 rounded-lg">
-                {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
+              <Avatar className="size-8 rounded-lg">
+                {user.avatar && <AvatarImage src={user.avatar} alt="" />}
                 <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
               </Avatar>
-              <div className="grid flex-1 text-start text-body leading-tight">
+              <div className="grid flex-1 text-start text-body leading-tight group-data-[collapsible=icon]:hidden">
                 <span className="truncate font-medium">{user.name}</span>
-                <span className="truncate text-meta">{user.email}</span>
+                <span className="truncate text-meta text-sidebar-muted-foreground">
+                  {user.email}
+                </span>
               </div>
-              <ChevronsUpDown className="ms-auto size-4" />
+              <ChevronsUpDown
+                aria-hidden="true"
+                className="ms-auto size-4 group-data-[collapsible=icon]:hidden"
+              />
             </SidebarMenuButton>
           </DropdownMenuTrigger>
           <DropdownMenuContent
+            data-slot="nav-user-menu"
             className="w-(--radix-dropdown-menu-trigger-width) min-w-56 rounded-lg"
             side={isMobile ? "bottom" : "right"}
             align="end"
             sideOffset={4}
           >
-            <DropdownMenuLabel className="p-0 font-normal">
-              <div className="flex items-center gap-2 px-1 py-1.5 text-start text-body">
-                <Avatar className="h-8 w-8 rounded-lg">
-                  {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
-                  <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
-                </Avatar>
-                <div className="grid flex-1 text-start text-body leading-tight">
-                  <span className="truncate font-medium">{user.name}</span>
-                  <span className="truncate text-meta">{user.email}</span>
-                </div>
-              </div>
+            <DropdownMenuLabel className="text-meta text-muted-foreground">
+              {t("ui.navUser.label")}
             </DropdownMenuLabel>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <Sparkles />
-                Upgrade to Pro
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-            <DropdownMenuSeparator />
             <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <BadgeCheck />
-                Account
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <CreditCard />
-                Billing
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <Bell />
-                Notifications
-              </DropdownMenuItem>
+              {children}
+              {settingsHref ? (
+                <DropdownMenuItem asChild>
+                  <a href={settingsHref}>
+                    <Settings aria-hidden="true" />
+                    {t("ui.navUser.settings")}
+                  </a>
+                </DropdownMenuItem>
+              ) : (
+                <DropdownMenuItem onSelect={onSettings}>
+                  <Settings aria-hidden="true" />
+                  {t("ui.navUser.settings")}
+                </DropdownMenuItem>
+              )}
             </DropdownMenuGroup>
             <DropdownMenuSeparator />
-            <DropdownMenuItem>
-              <LogOut />
-              Log out
+            <DropdownMenuItem onSelect={onSignOut}>
+              <LogOut aria-hidden="true" />
+              {t("ui.navUser.signOut")}
             </DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>

package/src/components/navigation-menu/navigation-menu.stories.tsx

@@ -112,3 +112,45 @@ export const Default: Story = {
     await waitFor(() => expect(trigger).toHaveAttribute("aria-expanded", "false"));
   },
 };
+
+/**
+ * Locks WCAG 1.4.11 (#308): `NavigationMenuTrigger` painted `hover:` and
+ * `focus:` identically, with the fill alone (no ring/outline layer) as the
+ * only signal — not a visible indicator. Keyboard (Tab) focus must now paint
+ * a real compound ring (`focus-ring`: a `boxShadow` layer, or a non-zero,
+ * non-`none` `outline`), and the resting trigger must carry neither layer.
+ *
+ * NOTE: this does not additionally assert "a mouse click shows no ring" —
+ * confirmed BOTH before and after this fix (and independent of story order),
+ * a real click on this trigger still lands the browser in `:focus-visible`
+ * in this environment. `NavigationMenuTrigger` sits in Radix's roving-
+ * tabindex collection, which manages its focus imperatively rather than via
+ * the browser's native click-to-focus default action — the same class of
+ * "script-triggered focus" `CompoundFocusIndicator` (`button.stories.tsx`)
+ * already notes as unreliable against `:focus-visible`. Converting `focus:`
+ * to `focus-visible:` is still the correct, spec-aligned fix (mouse-click
+ * suppression is now possible, keyed on the browser's own determination);
+ * whether Radix's roving-focus internals let the browser actually make that
+ * determination for a plain click is a separate, deeper defect — flagged as
+ * a residual follow-up, not fixed here.
+ */
+export const KeyboardFocusIndicator: Story = {
+  name: "Keyboard focus",
+  render: Default.render,
+  play: async ({ canvas, userEvent }) => {
+    const trigger = canvas.getByRole("button", { name: /products/i });
+
+    const resting = getComputedStyle(trigger);
+    await expect(resting.boxShadow).toBe("none");
+    await expect(resting.outlineStyle).toBe("none");
+
+    // Tab rather than .focus(): `:focus-visible` is what `focus-ring` keys
+    // on, and a programmatic focus does not reliably match it.
+    await userEvent.tab();
+    await expect(trigger).toHaveFocus();
+    const afterTab = getComputedStyle(trigger);
+    const tabHasRing = afterTab.boxShadow !== "none";
+    const tabHasOutline = afterTab.outlineStyle !== "none" && parseFloat(afterTab.outlineWidth) > 0;
+    await expect(tabHasRing || tabHasOutline).toBe(true);
+  },
+};

package/src/components/navigation-menu/navigation-menu.tsx

@@ -198,7 +198,7 @@ export const NavigationMenuItem = forwardRef<
 });
 
 export const navigationMenuTriggerStyle = cva(
-  "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-body font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:outline-none disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-accent",
+  "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-body font-medium outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground focus-ring disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-accent",
 );
 
 export const NavigationMenuTrigger = forwardRef<

package/src/components/page-shell/page-shell.stories.tsx

@@ -26,7 +26,7 @@ export const Default: Story = {
 /**
  * `headerVariant="toolbar"` places a real `<ViewToolbar>` in `PageShell`'s
  * header slot and pins it in POSITION (never a fixed height — see
- * `Docs/View Toolbar Contract` R7) while the body scrolls beneath it. The
+ * `Layout/ViewToolbar → Contract` R7) while the body scrolls beneath it. The
  * outer `h-[420px] overflow-y-auto` div stands in for the `SidebarInset`
  * scroll region `PageShell` is normally embedded in — `PageShell` itself
  * never owns a scroll container (#367).

package/src/components/page-shell/page-shell.tsx

@@ -10,12 +10,12 @@ export interface PageShellProps extends ComponentProps<"div"> {
    * Byte-identical to today.
    *
    * "toolbar" — for a `<ViewToolbar>` header (`@elabs-ai/components-ui`,
-   * `Docs/View Toolbar Contract`): wraps `header` in a `sticky top-0` container
+   * `Layout/ViewToolbar → Contract`): wraps `header` in a `sticky top-0` container
    * with an opaque/blurred fill and a bottom hairline, so it stays pinned while
    * the body scrolls beneath it. PLACES whatever node `header` is — it does not
    * reimplement ViewToolbar's own info/left-cluster/actions grammar, and it does
    * NOT cap the row's height (a `<ViewToolbar>` wraps at narrow widths; see
-   * `Docs/View Toolbar Contract` R7).
+   * `Layout/ViewToolbar → Contract` R7).
    */
   headerVariant?: "default" | "toolbar";
   /** Constrain content width. Defaults to "xl". */
@@ -92,6 +92,7 @@ export const PageShell = forwardRef<HTMLDivElement, PageShellProps>(function Pag
 
   const headerNode = header ? (
     headerVariant === "toolbar" ? (
+      // header-band-exempt: a page-section toolbar under the top bar, not beside it
       <div
         data-slot="page-shell-toolbar-header"
         className="sticky top-0 z-10 border-b border-border bg-background/95 py-3 backdrop-blur"

package/src/components/pagination/pagination.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { forwardRef, type ComponentProps } from "react";
 import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";
 import { cn } from "../../lib/cn";

package/src/components/parallax-plane/index.ts

@@ -0,0 +1,8 @@
+export {
+  ParallaxPlane,
+  PARALLAX_MAX_TRAVEL,
+  PARALLAX_PLANE_RATES,
+  parallaxOffset,
+  type ParallaxPlaneKind,
+  type ParallaxPlaneProps,
+} from "./parallax-plane";

package/src/components/parallax-plane/parallax-plane.css

@@ -0,0 +1,26 @@
+/*
+ * ParallaxPlane — the scroll-driven path (`animation-timeline: scroll(root)`).
+ * The component sets `data-parallax="timeline"` only after hydration, only when the motion gate
+ * is open and the browser supports scroll timelines, and passes the geometry in:
+ *   --parallax-travel  signed end offset (never more than 60px from the content plane)
+ *   --parallax-range   scroll distance over which that offset is reached (travel / |1 − rate|)
+ * Past the range the plane holds its offset (`both` fill), so the total travel stays clamped at
+ * every scroll position. Under reduced motion the attribute is never set: no animation, no
+ * transform. `transform` only — nothing here triggers layout.
+ */
+@layer base {
+  [data-slot="parallax-plane"][data-parallax="timeline"] {
+    animation: brand-ui-parallax-plane linear both;
+    animation-timeline: scroll(root block);
+    animation-range: 0px var(--parallax-range);
+  }
+
+  @keyframes brand-ui-parallax-plane {
+    from {
+      transform: translateY(0);
+    }
+    to {
+      transform: translateY(var(--parallax-travel));
+    }
+  }
+}

package/src/components/parallax-plane/parallax-plane.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+import { Card, CardDescription, CardHeader, CardTitle } from "../card";
+import { ParallaxPlane, type ParallaxPlaneKind } from "./parallax-plane";
+
+const PLANES: { plane: ParallaxPlaneKind; title: string; description: string }[] = [
+  { plane: "ground", title: "Ground plane", description: "Scrolls at 0.15× — it lags behind." },
+  { plane: "content", title: "Content plane", description: "Scrolls with the page at 1×." },
+  { plane: "float", title: "Float plane", description: "Scrolls at 1.2× — it runs ahead." },
+];
+
+function Planes() {
+  return (
+    <div className="min-h-screen p-8">
+      <p className="text-body text-muted-foreground">
+        Scroll the page: each card moves at its plane’s rate, never more than 60px from the content.
+      </p>
+      <div className="mt-40 grid gap-6 sm:grid-cols-3">
+        {PLANES.map(({ plane, title, description }) => (
+          <ParallaxPlane key={plane} plane={plane}>
+            <Card>
+              <CardHeader>
+                <CardTitle>{title}</CardTitle>
+                <CardDescription>{description}</CardDescription>
+              </CardHeader>
+            </Card>
+          </ParallaxPlane>
+        ))}
+      </div>
+      <div className="min-h-screen" />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Display/ParallaxPlane",
+  component: ParallaxPlane,
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+  render: () => <Planes />,
+} satisfies Meta<typeof ParallaxPlane>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Names a running animation so a failing reduced-motion play says what still moves. */
+function describeAnimation(a: Animation) {
+  const effect = a.effect as KeyframeEffect | null;
+  const target = effect?.target as Element | null | undefined;
+  const name = (a as CSSAnimation).animationName ?? (a as CSSTransition).transitionProperty ?? a.id;
+  return `${name} on ${target?.getAttribute("data-slot") ?? target?.tagName ?? "?"}${effect?.pseudoElement ?? ""}`;
+}
+
+export const Default: Story = {};
+
+export const Dark: Story = {
+  parameters: { themes: { themeOverride: "dark" } },
+};
+
+export const Decoration10: Story = {
+  globals: { decoration: "10" },
+};
+
+/** Under reduced motion every plane scrolls at 1×: no animation, no transform. */
+export const ReducedMotion: Story = {
+  // The real gate on :root (Storybook motion toolbar) plus a subtree dial, because the toolbar
+  // writes :root after the story has mounted.
+  globals: { motionPref: "reduced" },
+  render: () => (
+    <div data-motion-pref="reduced">
+      <Planes />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    // Transitions the harness started before the gate applied (theme/decoration swaps between
+    // stories) settle; a primitive that still animates under the gate never would.
+    await waitFor(() =>
+      expect(
+        document
+          .getAnimations()
+          .filter((a) => a.playState === "running")
+          .map(describeAnimation),
+      ).toEqual([]),
+    );
+    for (const plane of canvasElement.querySelectorAll('[data-slot="parallax-plane"]')) {
+      await expect(getComputedStyle(plane).transform).toBe("none");
+    }
+  },
+};