@sableui/react 0.13.1 → 0.14.0

package/dist/components/search-input/search-input.js

@@ -66,21 +66,23 @@ function SearchInput({
         }
       ),
       hasValue && !props.disabled ? (
-        // Sable's own icon button, not a hand-sized <button>: the hit area,
-        // focus ring, press and disabled fade follow the control ladder with
-        // every other icon button. Muted ink until hovered, so the X never
-        // out-shouts the query it clears.
-        /* @__PURE__ */ jsx(
+        // The wrapper carries the arrival, the button keeps its own response.
+        // motion-appear declares a transition list of its own, and on the
+        // Button it would fight motion-interactive for the one
+        // transition-property slot — whichever sorted last would win, and
+        // either the hover ease or the arrival would silently go. Removal
+        // stays instant: an emptied field should not wait on its X.
+        /* @__PURE__ */ jsx("span", { className: "absolute end-2 flex motion-appear", children: /* @__PURE__ */ jsx(
           Button,
           {
             variant: "ghost",
             size: "icon-xs",
             onClick: handleClear,
             "aria-label": "Clear search",
-            className: "absolute end-2 text-muted-foreground hover:text-foreground",
+            className: "text-muted-foreground hover:text-foreground",
             children: /* @__PURE__ */ jsx(Icon, { name: "xmark" })
           }
-        )
+        ) })
       ) : null
     ] })
   );

package/dist/components/search-input/search-input.meta.js

@@ -98,6 +98,32 @@ var searchInputMeta = {
     "ring",
     "destructive"
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-appear",
+      part: "Clear button",
+      why: "The X mounts as the first character lands. Fading and settling in from a smaller scale keeps it from popping into the corner of the eye on every new search; removal is instant so an emptied field does not wait on it."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Input",
+      why: "The focus ring and invalid border ease in, so focus reads as the field answering rather than a repaint."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Root",
+      why: "The field has no states of its own to move between \u2014 the clear button arriving is its only change, and arrival covers it."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Searching is the results' job: a list skeleton or a Spinner beside them, not a field that animates while you type."
+    }
+  ],
   a11y: [
     'Renders a native <input type="search"> \u2014 keyboard and form semantics come for free.',
     "Associate a <label htmlFor> (or wrap) \u2014 the magnifier glyph is decorative, not a label.",

package/dist/components/segmented-bar/segmented-bar.meta.js

@@ -16,7 +16,8 @@ var segmentedBarMeta = {
       },
       {
         guidance: "dont",
-        description: "Use it for a single value against a limit; that is Meter, which carries the meter role and its value."
+        description: "Use it for a single value against a limit; that is Meter, which carries the meter role and its value.",
+        instead: ["Meter"]
       },
       {
         guidance: "dont",

package/dist/components/select/select.meta.js

@@ -29,11 +29,13 @@ var selectMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option."
+        description: "Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option.",
+        instead: ["Combobox"]
       },
       {
         guidance: "dont",
-        description: "Use Select for binary on/off settings. Use Switch or Checkbox instead."
+        description: "Use Select for binary on/off settings. Use Switch or Checkbox instead.",
+        instead: ["Switch", "Checkbox"]
       },
       {
         guidance: "do",

package/dist/components/sheet/sheet.meta.js

@@ -30,11 +30,13 @@ var sheetMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Sheet for simple confirmations or deeply nested workflows."
+        description: "Do not use Sheet for simple confirmations or deeply nested workflows.",
+        instead: ["Dialog"]
       },
       {
         guidance: "dont",
-        description: "Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place."
+        description: "Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place.",
+        instead: ["Dialog"]
       }
     ],
     anatomy: [

package/dist/components/show-more/show-more.js

@@ -70,10 +70,7 @@ function ShowMore({
           Icon,
           {
             name: "chevron-down",
-            className: cn(
-              "transition-transform duration-(--motion-duration-fast) ease-standard",
-              expanded && "rotate-180"
-            )
+            className: cn("motion-interactive", expanded && "rotate-180")
           }
         ),
         children: expanded ? "Show less" : "Show more"

package/dist/components/show-more/show-more.meta.js

@@ -58,6 +58,44 @@ var showMoreMeta = {
     }
   ],
   tokensUsed: ["background", "foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "The preview arrives with the content it clips. Its fade and toggle appear only once a measurement proves the content overflows."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Toggle",
+      why: "The toggle is a link Button, so its hover and focus ease on Button's recipe."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Content",
+      why: "The region eases its max-height between the collapsed and the measured full height on the slow motion token. motion-disclosure keys on Base UI's starting and ending styles, which this self-contained toggle does not have. The text unrolling in place keeps the reader's line; a snap drops them at a different scroll position."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Fade",
+      why: "The bottom fade dissolves as the region opens and returns as it closes, so the cut edge and the reveal read as one movement."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Chevron",
+      why: "The chevron turns 180\xB0 in step with the region (motion-interactive lists `rotate`), so the toggle visibly points at what it will do next."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Expanding is local and instant; nothing loads."
+    }
+  ],
   a11y: [
     "The toggle is a real <button> with aria-expanded reflecting the open state.",
     "The fade overlay is pointer-events-none and decorative; it never traps clicks.",

package/dist/components/side-nav/side-nav.js

@@ -4,19 +4,39 @@
 import { useRender } from "@base-ui/react/use-render";
 import { createContext, useContext } from "react";
 import { cn } from "../../lib/cn.js";
+import { HighlightGlide } from "../../lib/highlight-glide.js";
+import { motionAttribute } from "../../motion/MotionProvider.js";
 import { sideNavItemIconVariants, sideNavItemVariants } from "./side-nav.variants.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var SideNavContext = createContext({
   size: "md",
   activeVariant: "content"
 });
+var GLIDE_HANDOFF = "[&[data-glide]_[data-active]]:bg-transparent";
+var GLIDE_FILL = {
+  content: "rounded-sm bg-accent motion-glide",
+  sidebar: "rounded-sm bg-sidebar-accent motion-glide"
+};
 function SideNav({
   className,
   size = "md",
   activeVariant = "content",
+  motion,
+  children,
   ...props
 }) {
-  return /* @__PURE__ */ jsx(SideNavContext.Provider, { value: { size, activeVariant }, children: /* @__PURE__ */ jsx("nav", { className: cn("flex flex-col gap-0.5", className), ...props }) });
+  return /* @__PURE__ */ jsx(SideNavContext.Provider, { value: { size, activeVariant }, children: /* @__PURE__ */ jsxs(
+    "nav",
+    {
+      "data-motion": motionAttribute(motion),
+      className: cn("flex flex-col gap-0.5", GLIDE_HANDOFF, className),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(HighlightGlide, { follow: "data-active", timing: "selection", className: GLIDE_FILL[activeVariant] }),
+        children
+      ]
+    }
+  ) });
 }
 SideNav.displayName = "SideNav";
 function SideNavGroup({

package/dist/components/side-nav/side-nav.meta.js

@@ -33,7 +33,8 @@ var sideNavMeta = {
       },
       {
         guidance: "dont",
-        description: "Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot."
+        description: "Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot.",
+        instead: ["BottomNav"]
       },
       {
         guidance: "dont",
@@ -79,6 +80,12 @@ var sideNavMeta = {
       type: '"content" | "sidebar"',
       default: '"content"',
       description: 'Active-state token vocabulary shared by all items. "content" uses bg-accent/text-accent-foreground for local rails inside the content area; "sidebar" uses bg-sidebar-accent/text-sidebar-accent-foreground for SideNavs rendered inside app chrome.'
+    },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "How much motion this component uses: `full` inherits the app's policy, `subtle` keeps feedback and drops the current-page glide, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting."
     }
   ],
   subcomponents: [
@@ -93,6 +100,32 @@ var sideNavMeta = {
       description: "A labelled section within a SideNav - groups settings into areas. label renders an optional sentence-case caption heading above the group's items."
     }
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "In-page navigation arrives with the page it navigates."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "SideNavItem",
+      why: "Rows ease their hover fill and focus ring, so moving down a long nav reads as one pointer travelling rather than rows flashing in turn."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-glide",
+      part: "SideNav",
+      why: "The current-item fill is one element that travels to the new row when the section changes inside a persistent layout, so the marker reads as moving rather than one row dimming while another lights. It lands in place on first paint, each row keeps its own fill as the server-render fallback, and the active row's heavier weight lands at once \u2014 font weight does not ease. Expressive: `subtle` moves it at once."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Navigation chrome has no working state; a loading section shows it in the content."
+    }
+  ],
   a11y: [
     "SideNav renders a <nav> landmark; pair multiple navs with aria-label to distinguish them.",
     'The active item carries aria-current="page".',

package/dist/components/side-nav/side-nav.variants.js

@@ -2,7 +2,9 @@
 import { cva } from "class-variance-authority";
 var RAIL_ROW_INLINE = "gap-3 px-3";
 var sideNavItemVariants = cva(
-  "flex w-full items-center text-start motion-interactive focus-visible:outline-none focus-visible:ring-2 data-[active]:font-semibold",
+  // `relative`: a row paints above SideNav's gliding current-page fill, which is
+  // absolutely positioned and earlier in the DOM.
+  "relative flex w-full items-center text-start motion-interactive focus-visible:outline-none focus-visible:ring-2 data-[active]:font-semibold",
   {
     variants: {
       size: {

package/dist/components/sidebar/sidebar.js

@@ -4,9 +4,12 @@
 import { useRender } from "@base-ui/react/use-render";
 import {
   createContext,
-  useContext
+  useContext,
+  useState
 } from "react";
 import { cn } from "../../lib/cn.js";
+import { HighlightGlide } from "../../lib/highlight-glide.js";
+import { motionAttribute } from "../../motion/MotionProvider.js";
 import { RAIL_ROW_INLINE, sideNavItemIconVariants, sideNavItemVariants } from "../side-nav/side-nav.variants.js";
 import { SimpleTooltip } from "../tooltip/index.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -14,6 +17,7 @@ var SidebarContext = createContext({
   collapsed: false,
   icons: true
 });
+var LABEL_FADE = "starting:opacity-0 transition-opacity duration-(--motion-duration-base) ease-decelerate";
 function useSidebar() {
   return useContext(SidebarContext);
 }
@@ -43,13 +47,17 @@ function Sidebar({
   icons = true,
   variant = "app",
   surface = "rail",
+  motion,
   className,
   children,
   ...props
 }) {
-  return /* @__PURE__ */ jsx(SidebarContext.Provider, { value: { collapsed, icons }, children: /* @__PURE__ */ jsx(
+  const [hasCollapsed, setHasCollapsed] = useState(collapsed);
+  if (collapsed && !hasCollapsed) setHasCollapsed(true);
+  return /* @__PURE__ */ jsx(SidebarContext.Provider, { value: { collapsed, icons, reopened: hasCollapsed && !collapsed }, children: /* @__PURE__ */ jsx(
     "aside",
     {
+      "data-motion": motionAttribute(motion),
       "data-collapsed": collapsed || void 0,
       "data-variant": variant,
       "data-surface": surface,
@@ -66,6 +74,15 @@ function Sidebar({
         surface === "rail" ? cn("border-r border-sidebar-border", SIDEBAR_INK) : PAGE_INK,
         SIDEBAR_VARIANT[variant],
         "w-[var(--sidebar-width,16rem)] data-[collapsed]:w-[var(--sidebar-width-collapsed,4rem)]",
+        // Collapsing eases the width (`motion-size`, expressive) rather than
+        // jumping 192px in one frame. It reflows the page beside the rail for
+        // the length of the ease, which is the point: the content visibly
+        // takes the room the rail gave up. Nothing inside jumps, because a
+        // collapsed row's centred icon and an expanded row's inset icon sit
+        // on the same column (measured: 21px from the rail edge in both).
+        // Labels leave at once and fade back in as the rail reopens; the
+        // clip keeps them from painting past the rail while it is narrow.
+        "overflow-x-clip motion-size",
         className
       ),
       ...props,
@@ -94,7 +111,7 @@ function SidebarHeader({
 }
 SidebarHeader.displayName = "SidebarHeader";
 function SidebarBrand({ mark, label, render, className, "aria-label": ariaLabel, ...props }) {
-  const { collapsed } = useSidebar();
+  const { collapsed, reopened } = useSidebar();
   return useRender({
     render: render ?? /* @__PURE__ */ jsx("div", {}),
     props: {
@@ -111,7 +128,7 @@ function SidebarBrand({ mark, label, render, className, "aria-label": ariaLabel,
       ),
       children: /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: "rail" }), children: mark }),
-        collapsed ? null : /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate text-title-sm", children: label })
+        collapsed ? null : /* @__PURE__ */ jsx("span", { className: cn("min-w-0 truncate text-title-sm", reopened && LABEL_FADE), children: label })
       ] })
     },
     defaultTagName: "div"
@@ -120,9 +137,10 @@ function SidebarBrand({ mark, label, render, className, "aria-label": ariaLabel,
 SidebarBrand.displayName = "SidebarBrand";
 function SidebarNav({
   className,
+  children,
   ...props
 }) {
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsxs(
     "nav",
     {
       className: cn(
@@ -130,9 +148,14 @@ function SidebarNav({
         // narrow rail, and contained overscroll so a wheel gesture that runs
         // out of nav stops there instead of scrolling the page behind it.
         "flex flex-1 flex-col gap-1 overflow-y-auto overscroll-contain px-3 py-4 scrollbar-quiet",
+        "[&[data-glide]_[data-active]]:bg-transparent",
         className
       ),
-      ...props
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(HighlightGlide, { follow: "data-active", timing: "selection", className: "rounded-sm bg-sidebar-accent motion-glide" }),
+        children
+      ]
     }
   );
 }
@@ -163,7 +186,7 @@ function SidebarItem({
   "aria-label": ariaLabel,
   ...props
 }) {
-  const { collapsed, icons } = useSidebar();
+  const { collapsed, icons, reopened } = useSidebar();
   const showIcon = icon != null && (icons || collapsed);
   const element = useRender({
     render: render ?? /* @__PURE__ */ jsx("button", { type: "button" }),
@@ -183,7 +206,7 @@ function SidebarItem({
       children: /* @__PURE__ */ jsxs(Fragment, { children: [
         showIcon ? /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: "rail" }), children: icon }) : null,
         collapsed ? null : /* @__PURE__ */ jsxs(Fragment, { children: [
-          /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate", children: label }),
+          /* @__PURE__ */ jsx("span", { className: cn("min-w-0 flex-1 truncate", reopened && LABEL_FADE), children: label }),
           badge ? /* @__PURE__ */ jsx("span", { className: "ms-auto shrink-0", children: badge }) : null
         ] })
       ] })

package/dist/components/sidebar/sidebar.meta.js

@@ -77,6 +77,12 @@ var sidebarMeta = {
       type: '"rail" | "page"',
       default: '"rail"',
       description: `Which surface the rail is painted on. "rail" is its own --sidebar-* surface with a border \u2014 right for a full-height rail that frames the app, which a theme may tint or paint dark. "page" uses the page's surface and ink with no border \u2014 use it when a full-width header sits above the rail, where a tinted column starting under a page-coloured bar reads as pasted on. Use it instead of overriding bg-/text- classes, which the rail's re-pointed tokens defeat.`
+    },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "How much motion this component uses: `full` inherits the app's policy, `subtle` keeps feedback and drops the collapse ease and the current-page glide, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting."
     }
   ],
   subcomponents: [
@@ -96,6 +102,38 @@ var sidebarMeta = {
       description: 'A single nav row. label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}.'
     }
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "The rail is the app's frame, present from first paint. It is not summoned, so it has no entrance."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "SidebarItem",
+      why: "Rows ease their hover fill (SideNav's row recipe on the rail rung), so moving down the nav reads as the pointer travelling rather than rows flashing."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-glide",
+      part: "SidebarNav",
+      why: "The current-page fill is one element that travels to the new item when the page changes inside a persistent layout, so the marker reads as moving rather than one row dimming while another lights. It lands in place on first paint, and each item keeps its own fill as the server-render fallback. Expressive: `subtle` moves it at once."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-size",
+      part: "Root",
+      why: "Collapsing to the icon rail eases the width instead of jumping 192px in one frame, so the content beside it visibly takes the room the rail gave up. Nothing inside jumps \u2014 a collapsed row's centred icon and an expanded row's inset icon sit on the same column \u2014 and labels leave at once and fade back in on reopen, clipped to the rail meanwhile. It reflows the page for the length of the ease, which is acceptable for a deliberate user toggle and never happens on load. Expressive: `subtle` snaps."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Navigation chrome has no working state; a loading route shows it in the page."
+    }
+  ],
   a11y: [
     "SidebarNav renders a <nav> landmark.",
     'Active item carries aria-current="page".',

package/dist/components/skeleton/skeleton.meta.js

@@ -22,7 +22,8 @@ var skeletonMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error)."
+        description: "Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error).",
+        instead: ["EmptyState"]
       },
       {
         guidance: "dont",

package/dist/components/slider/slider.meta.js

@@ -173,6 +173,32 @@ var sliderMeta = {
     }
   ],
   tokensUsed: ["secondary", "primary", "background", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "It arrives with the form or panel it sits in."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Thumb",
+      why: "The thumb's dot grows from 12px to full size on hover and keyboard focus, and a little past it while dragging, on a spring. Only the paint resizes, never the hit target, so the growth says the thumb is live without moving where you have to aim."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Thumb",
+      why: "The thumb and the filled range follow the pointer one-to-one, and keyboard steps land at once. An eased position would trail the drag and show a value the user has already moved past."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "A slider commits as it moves; there is nothing to wait for."
+    }
+  ],
   a11y: [
     "Base UI provides role=slider, aria-valuemin/max/now, and arrow-key / Page Up-Down / Home-End control.",
     "Each thumb is a focusable input[type=range] nested in the thumb element; keyboard focus raises a 2px ring on the thumb via has-[:focus-visible] (a bare focus-visible: on the thumb never fires, since the div itself is not focusable).",

package/dist/components/sparkline/sparkline.js

@@ -5,15 +5,17 @@ import { areaPath, linePath } from "../../lib/chart/geometry.js";
 import { drawTransition, riseTransition, stagger } from "../../lib/chart/motion.js";
 import { toneColor } from "../../lib/chart/types.js";
 import { cn } from "../../lib/cn.js";
-import { useMotion } from "../../motion/MotionProvider.js";
+import { motionAttribute, useMotionLevel } from "../../motion/MotionProvider.js";
+import { chartMotion } from "../../lib/chart/chart-frame.js";
 import { useArrival } from "../../lib/chart/use-arrival.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var W = 100;
 var H = 32;
-function Sparkline({ data, label, variant = "line", tone = "primary", animate = true, locale, className, ...props }) {
-  const { enabled } = useMotion();
+function Sparkline({ data, label, variant = "line", tone = "primary", motion, animate, locale, className, ...props }) {
+  const level = chartMotion(motion, animate);
+  const { expressive } = useMotionLevel(level);
   const [ref, inView] = useArrival();
-  const shown = !animate || !enabled || inView;
+  const shown = !expressive || inView;
   const color = toneColor(tone);
   const min = data.length ? Math.min(...data) : 0;
   const max = data.length ? Math.max(...data) : 1;
@@ -72,6 +74,7 @@ function Sparkline({ data, label, variant = "line", tone = "primary", animate =
       viewBox: `0 0 ${W} ${H}`,
       preserveAspectRatio: "none",
       "data-reveal": shown ? "in" : "out",
+      "data-motion": motionAttribute(level),
       className: cn("inline-block h-8 w-24 shrink-0 overflow-visible align-middle", className),
       ...props,
       children: marks

package/dist/components/sparkline/sparkline.meta.js

@@ -70,11 +70,18 @@ var sparklineMeta = {
       default: '"h-8 w-24"',
       description: "Sizes it; the drawing stretches to fit."
     },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "How much motion this component uses: `full` (default) inherits the app's policy, `subtle` keeps feedback and drops the flourish, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting. Drawing on (or rising) is the flourish, so `subtle` and `off` show the finished line."
+    },
     {
       name: "animate",
       type: "boolean",
       default: "true",
-      description: "Draw on (or rise) when it scrolls into view."
+      description: 'Draw on (or rise) when it scrolls into view. `animate={false}` is `motion="subtle"`.',
+      deprecated: 'motion="subtle" (what animate={false} now maps to) or motion="off"'
     },
     {
       name: "locale",
@@ -106,7 +113,7 @@ var sparklineMeta = {
       slot: "arrival",
       recipe: "custom",
       part: "Line / bars",
-      why: "Once on screen the line draws on (or the bars rise, in sequence). On the motion tokens; reduced motion shows the finished drawing."
+      why: 'Once on screen the line draws on (or the bars rise, in sequence). On the motion tokens; reduced motion shows the finished drawing. The arrival is expressive: it plays at the full motion level only, so `motion="subtle"` (or a subtle app policy) shows the finished line.'
     },
     {
       slot: "response",

package/dist/components/spinner/spinner.meta.js

@@ -22,7 +22,8 @@ var spinnerMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Spinner as the only content for long waits or full page loading."
+        description: "Do not use Spinner as the only content for long waits or full page loading.",
+        instead: ["Skeleton", "PageLoader"]
       },
       {
         guidance: "dont",

package/dist/components/stepper/stepper.meta.js

@@ -30,11 +30,13 @@ var stepperMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Stepper for a task with unknown length or for a percentage. That is Progress; a stepper promises a fixed set of named stops."
+        description: "Do not use Stepper for a task with unknown length or for a percentage. That is Progress; a stepper promises a fixed set of named stops.",
+        instead: ["Progress"]
       },
       {
         guidance: "dont",
-        description: "Do not use it as navigation between independent sections. Sections the user can visit in any order are Tabs; a stepper implies each step depends on the one before."
+        description: "Do not use it as navigation between independent sections. Sections the user can visit in any order are Tabs; a stepper implies each step depends on the one before.",
+        instead: ["Tabs"]
       },
       {
         guidance: "dont",

package/dist/components/switch/switch.meta.js

@@ -26,7 +26,8 @@ var switchMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Switch for one-time agreement, multi-select choices, or submit-only booleans."
+        description: "Do not use Switch for one-time agreement, multi-select choices, or submit-only booleans.",
+        instead: ["Checkbox", "Radio"]
       },
       {
         guidance: "dont",

package/dist/components/table/table.meta.js

@@ -34,7 +34,8 @@ var tableMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Table for heterogeneous items with no stable columns. Use Card, Entity, or a list composition instead."
+        description: "Use Table for heterogeneous items with no stable columns. Use Card, Entity, or a list composition instead.",
+        instead: ["Card", "Entity"]
       },
       {
         guidance: "dont",
@@ -114,6 +115,32 @@ var tableMeta = {
     }
   ],
   tokensUsed: ["border", "muted", "muted-foreground"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "A table renders with the page it sits in. Staggering rows in delays reading data someone opened to scan."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "TableRow",
+      why: "Body rows ease to a muted wash under the pointer. Across a wide row, the wash is what keeps the eye on the right line, and eased it follows the cursor down the table rather than strobing."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "TableCell",
+      why: "A `data-selected` row's fill eases in on every cell together, so the selected row reads as one band being set rather than a stamp."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Table is markup. Loading rows are Skeletons, which carry the shimmer."
+    }
+  ],
   a11y: [
     "Renders semantic native table elements (thead/tbody/tfoot/th/td/caption) preserving built-in table semantics.",
     "Use TableHead (th) for column headers and TableCaption for an accessible description.",