@sableui/react 0.13.1 → 0.14.0

package/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://sable.design/registry.schema.json",
   "name": "@sableui/react",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Themeable React components, semantic tokens, layout patterns, presets, and package-owned agent skills. Default theme: Sable.",
   "engine": {
     "behavior": "@base-ui/react",
@@ -949,6 +949,12 @@
         "motion-slide-right",
         "motion-disclosure",
         "motion-icon-swap",
+        "motion-glide",
+        "motion-shake",
+        "motion-tick",
+        "motion-appear",
+        "motion-arrive",
+        "motion-size",
         "motion-reveal",
         "motion-draw",
         "motion-spin",
@@ -966,6 +972,7 @@
       ],
       "policy": [
         "data-motion=full",
+        "data-motion=subtle",
         "data-motion=reduced",
         "data-motion=off",
         "prefers-reduced-motion"
@@ -2706,7 +2713,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not nest an Accordion inside an Accordion. Two layers of roving focus fight each other, and the arrow keys become ambiguous — flatten the hierarchy or use a Tree."
+            "description": "Do not nest an Accordion inside an Accordion. Two layers of roving focus fight each other, and the arrow keys become ambiguous — flatten the hierarchy or use a Tree.",
+            "instead": [
+              "Tree"
+            ]
           }
         ],
         "anatomy": [
@@ -2806,6 +2816,12 @@
           "part": "AccordionPanel",
           "why": "Panel height is the only cue that content came from THIS header rather than appearing at the bottom of the page. Snapping it open moves everything below by a screenful with nothing connecting cause to effect."
         },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Chevron",
+          "why": "The chevron turning is the header's half of the same event as the panel opening. motion-interactive lists `rotate` (what Tailwind's rotate-* writes), so it turns with the panel instead of flipping 180° in one frame beside an easing panel. A custom `indicator` that rotates should carry motion-interactive itself."
+        },
         {
           "slot": "activity",
           "recipe": "none",
@@ -2818,7 +2834,7 @@
         "Arrow keys move roving focus between triggers; Home/End jump to the first/last; loopFocus wraps by default.",
         "Each trigger toggles its panel with Enter/Space; the panel is announced as a labelled region.",
         "A disabled AccordionItem dims and is skipped by keyboard focus while neighbouring items stay interactive.",
-        "The chevron rotation is driven by data-[panel-open] and the focus ring by focus-visible — both honor reduced-motion via the consumer's transitions."
+        "The chevron rotation is driven by data-[panel-open] and the focus ring by focus-visible; both ride motion-interactive, so reduced motion stills them with everything else."
       ],
       "examples": [
         {
@@ -2833,7 +2849,7 @@
         },
         {
           "label": "Custom indicator (plus-becomes-×)",
-          "code": "<Accordion defaultValue={[\"a\"]}><AccordionItem value=\"a\"><AccordionTrigger indicator={<Icon name=\"plus\" className=\"text-xs text-muted-foreground transition-transform [[data-panel-open]_&]:rotate-45\" />}>Can I cancel anytime?</AccordionTrigger><AccordionPanel>Yes — from billing settings.</AccordionPanel></AccordionItem></Accordion>",
+          "code": "<Accordion defaultValue={[\"a\"]}><AccordionItem value=\"a\"><AccordionTrigger indicator={<Icon name=\"plus\" className=\"text-xs text-muted-foreground motion-interactive [[data-panel-open]_&]:rotate-45\" />}>Can I cancel anytime?</AccordionTrigger><AccordionPanel>Yes — from billing settings.</AccordionPanel></AccordionItem></Accordion>",
           "imports": "import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, Icon } from \"@sableui/react\""
         }
       ]
@@ -3211,11 +3227,18 @@
           "default": "false for columns; true for horizontal bars",
           "description": "The vertical axis."
         },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The arrival (draw-on, rising fill) and the data-change morph are the flourish; the gliding cursor and tooltip are the feedback `subtle` keeps."
+        },
         {
           "name": "animate",
           "type": "boolean",
           "default": "true",
-          "description": "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart."
+          "description": "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. `animate={false}` is `motion=\"subtle\"`.",
+          "deprecated": "motion=\"subtle\" (what animate={false} now maps to: no arrival, hover kept) or motion=\"off\""
         },
         {
           "name": "activeIndex",
@@ -3270,7 +3293,7 @@
           "slot": "arrival",
           "recipe": "custom",
           "part": "Area + line",
-          "why": "Once on screen, each line draws on (stroke-dashoffset) and its fill rises from the baseline, series staggered — the trend is read as it is drawn. On the motion tokens; reduced motion shows the finished chart."
+          "why": "Once on screen, each line draws on (stroke-dashoffset) and its fill rises from the baseline, series staggered — the trend is read as it is drawn. On the motion tokens; reduced motion shows the finished chart. The arrival is expressive: it plays at the full motion level only, so `motion=\"subtle\"` (or a subtle app policy) shows the finished chart while hover feedback stays."
         },
         {
           "slot": "response",
@@ -3282,7 +3305,7 @@
           "slot": "transition",
           "recipe": "custom",
           "part": "Area + line",
-          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place. Expressive, like the arrival: under `subtle` new data swaps in place."
         },
         {
           "slot": "activity",
@@ -3473,6 +3496,32 @@
         "overlay-foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "An attachment lands as part of a composer or a message, and that surface owns the entrance. A card that animated in on its own would read as a second, separate event — as if another file had been added."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "With `onOpen`, the edge steps up under the pointer; it is the only cue that the card itself opens the file, not just its actions. Eased, it reads as the card answering the cursor rather than a border flickering as the pointer crosses a busy composer."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "Uploading to failed re-colours the edge and fill without changing the shape. The ease keeps it legible as the same file turning red; snapped, a failed card looks like a different card replaced the one that was sent."
+        },
+        {
+          "slot": "activity",
+          "recipe": "motion-pulse",
+          "part": "Progress",
+          "why": "While uploading with no known `progress`, the bar is indeterminate and pulses (Progress's own recipe); with a number, the fill eases toward each new value. A still bar at a fixed width is indistinguishable from an upload that has stalled."
+        }
+      ],
       "a11y": [
         "The full-card trigger is a real stretched `<button>` with an accessible label, not a click handler on a div — so it is one tab stop, keyboard-activatable, and focus-ringed.",
         "Actions sit above that trigger in the stacking order, which keeps them individually focusable and stops a click on `remove` from also opening the file. Text is only made click-through when a trigger is present, so a filename stays selectable otherwise.",
@@ -3819,7 +3868,11 @@
           },
           {
             "guidance": "dont",
-            "description": "Use a Badge as a button. If it triggers an action, use Button, Toggle, or a menu item."
+            "description": "Use a Badge as a button. If it triggers an action, use Button, Toggle, or a menu item.",
+            "instead": [
+              "Button",
+              "Toggle"
+            ]
           },
           {
             "guidance": "do",
@@ -4047,11 +4100,18 @@
           },
           {
             "guidance": "dont",
-            "description": "Use Banner for field-level validation, row status, or small local hints; use Field, InlineStatus, or Badge instead."
+            "description": "Use Banner for field-level validation, row status, or small local hints; use Field, InlineStatus, or Badge instead.",
+            "instead": [
+              "InlineStatus",
+              "Badge"
+            ]
           },
           {
             "guidance": "dont",
-            "description": "Use Banner inside a dialog, a form, or a section to qualify the content around it — that is Note. Banner is a full-width announcement strip for page- or app-level state, so in a modal it reads as a slab heavier than the fields it warns about, and its soft appearance has no border and no tone-colored icon: the severity survives only as a faint wash."
+            "description": "Use Banner inside a dialog, a form, or a section to qualify the content around it — that is Note. Banner is a full-width announcement strip for page- or app-level state, so in a modal it reads as a slab heavier than the fields it warns about, and its soft appearance has no border and no tone-colored icon: the severity survives only as a faint wash.",
+            "instead": [
+              "Note"
+            ]
           }
         ],
         "anatomy": [
@@ -4326,11 +4386,18 @@
           "default": "false for columns; true for horizontal bars",
           "description": "The vertical axis."
         },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The arrival (bars rising in sequence) and the data-change morph are the flourish; the hover dim and gliding cursor are the feedback `subtle` keeps."
+        },
         {
           "name": "animate",
           "type": "boolean",
           "default": "true",
-          "description": "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart."
+          "description": "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. `animate={false}` is `motion=\"subtle\"`.",
+          "deprecated": "motion=\"subtle\" (what animate={false} now maps to: no arrival, hover kept) or motion=\"off\""
         },
         {
           "name": "activeIndex",
@@ -4408,19 +4475,19 @@
           "slot": "arrival",
           "recipe": "custom",
           "part": "Bar",
-          "why": "Once on screen, bars rise from the baseline in sequence on the emphasized easing (scale from the zero line) and their labels fade in. On the motion tokens; reduced motion shows the finished chart."
+          "why": "Once on screen, bars rise from the baseline in sequence on the emphasized easing (scale from the zero line) and their labels fade in. On the motion tokens; reduced motion shows the finished chart. The arrival is expressive: it plays at the full motion level only, so `motion=\"subtle\"` (or a subtle app policy) shows the finished chart while hover feedback stays."
         },
         {
           "slot": "response",
           "recipe": "none",
           "part": "Cursor + tooltip",
-          "why": "The hovered category gets a band behind it and the other bars dim at once — a lagging highlight reads as a slow chart."
+          "why": "The hovered category gets a band behind it and the other bars dim at once — a lagging highlight reads as a slow chart. The dim mixes each bar toward the surface instead of fading it, so gridlines never strike through a dimmed column and stacked segments stay solid. Essential: `subtle` keeps it."
         },
         {
           "slot": "transition",
           "recipe": "custom",
           "part": "Bar",
-          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place. Expressive, like the arrival: under `subtle` new data swaps in place."
         },
         {
           "slot": "activity",
@@ -4520,6 +4587,38 @@
         "foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Fixed app chrome, present from the first paint of every screen. Animating it in on navigation would make each route change look like the app restarting."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "BottomNavItem",
+          "why": "The ink steps up on hover and the focus ring eases in, so a pointer or a keyboard on a tablet gets the same answer as every other control in the app."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "BottomNavItem",
+          "why": "On a phone there is no hover to say a tap landed, and a route can take a beat to paint. The settle on press is the receipt; without it people tap the tab a second time."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "BottomNavItem",
+          "why": "Changing tab eases the active ink out of one item and into the next. It is a cross-fade, not a travelling indicator: each item owns its colour, so there is no single mark to glide."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Navigation has no working state of its own. A slow route shows its pending state in the page it is loading, not in the tab bar."
+        }
+      ],
       "a11y": [
         "BottomNav renders a <nav> landmark.",
         "Each tab is a 44px minimum touch target with an aria-label.",
@@ -4634,6 +4733,32 @@
         "muted-foreground",
         "foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The trail is page furniture, rendered with the page header. An entrance would replay on every navigation, which is exactly when the reader looks at it to get their bearings."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "BreadcrumbLink",
+          "why": "Ancestors are muted until hovered or focused. Easing the ink makes the trail read as links answering the pointer; a hard snap across a row of small text looks like flicker."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A breadcrumb has no state of its own. The current page changes by navigation, which replaces the trail; animating between two trails would imply the path itself moved."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It never works in the background. A route that is still loading says so in the page, not in its address."
+        }
+      ],
       "a11y": [
         "The <nav> carries aria-label=\"Breadcrumb\" so assistive tech announces the landmark.",
         "Crumbs sit in an ordered list (<ol>) to convey hierarchy and position.",
@@ -4944,7 +5069,7 @@
           },
           {
             "guidance": "do",
-            "description": "For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`. Text that costs something to produce (a file to fetch) goes in as a function, `useCopy(() => fetch(url).then((r) => r.text()))`, called only on click."
+            "description": "For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`. Text that costs something to produce (a file to fetch) goes in as a function, `useCopy(() => fetch(url).then((r) => r.text()))`, called only on click. Keep both glyphs mounted in a `motion-icon-swap` cell so the copy mark visibly becomes a check (a `copied ? \"check\" : \"copy\"` swap snaps between frames and is easy to miss), and say \"Copied\" in a polite `role=\"status\"` region: the glyph change is silent to a screen reader."
           },
           {
             "guidance": "do",
@@ -5045,7 +5170,7 @@
           "name": "loading",
           "type": "boolean",
           "default": "false",
-          "description": "Show a leading Spinner while an action is in flight and refuse presses. Sets aria-busy and aria-disabled, never the native disabled: disabling the focused button sent focus to <body>, so a sheet the action opened had nowhere to return it."
+          "description": "Show a Spinner while an action is in flight and refuse presses. The spinner takes the iconStart slot when there is one; otherwise it lays over the label, which fades out in place, so the button keeps its width. Sets aria-busy and aria-disabled, never the native disabled: disabling the focused button sent focus to <body>, so a sheet the action opened had nowhere to return it."
         },
         {
           "name": "onClick",
@@ -5060,7 +5185,7 @@
         {
           "name": "loadingLabel",
           "type": "ReactNode",
-          "description": "Optional text shown in place of children while loading."
+          "description": "Optional text shown in place of children while loading, with the spinner beside it. The width follows the new text, so prefer no loadingLabel where the row must not move."
         },
         {
           "name": "iconStart",
@@ -5138,9 +5263,9 @@
         },
         {
           "slot": "transition",
-          "recipe": "none",
-          "part": "Root",
-          "why": "A button has no state of its own to move between. A control that toggles is a Switch or a Toggle, and those carry the transition."
+          "recipe": "motion-appear",
+          "part": "Spinner",
+          "why": "Going busy is the one state change a button has. The spinner fades in where it mounts — in the icon slot, or laid over a plain label that fades out beneath it and keeps its place — so the width never changes and the row does not shift under the pointer that just pressed it. The label fades back when the work settles. A toggling control is a Switch or a Toggle; those carry their own transition."
         },
         {
           "slot": "activity",
@@ -5181,8 +5306,8 @@
         },
         {
           "label": "Copy to clipboard",
-          "code": "const { copy, copied } = useCopy(address)\n<Button variant=\"ghost\" size=\"icon-sm\" aria-label=\"Copy address\" onClick={copy}><Icon name={copied ? \"check\" : \"copy\"} /></Button>",
-          "imports": "import { Button, Icon, useCopy } from \"@sableui/react\""
+          "code": "const { copy, copied } = useCopy(address)\n<Row gap={1}><Button variant=\"ghost\" size=\"icon-sm\" aria-label=\"Copy address\" onClick={copy}><span aria-hidden=\"true\" className=\"motion-icon-swap\"><span data-active={!copied} className=\"inline-flex\"><Icon name=\"copy\" /></span><span data-active={copied} className=\"inline-flex\"><Icon name=\"check\" /></span></span></Button><span role=\"status\" className=\"sr-only\">{copied ? \"Copied\" : \"\"}</span></Row>",
+          "imports": "import { Button, Icon, Row, useCopy } from \"@sableui/react\""
         },
         {
           "label": "As link",
@@ -5282,7 +5407,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state."
+            "description": "Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state.",
+            "instead": [
+              "ToggleGroup"
+            ]
           }
         ]
       },
@@ -5418,6 +5546,12 @@
           "default": "false",
           "description": "Drop the card frame (border, fill, padding) so the grid sits flush inside a surface that already has one, such as a Popover. DatePicker renders its Calendar this way."
         },
+        {
+          "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 month slide, `off` stills it. It can only turn motion down — it never overrides a reader's reduce-motion setting."
+        },
         {
           "name": "className",
           "type": "string",
@@ -5452,6 +5586,38 @@
         "muted-foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Inline, it arrives with its form; in a DatePicker the Popover carries the entrance. A grid that animated in by itself would put a second motion on the same opening."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Day",
+          "why": "Days ease their hover wash, and the month arrows are ghost Buttons on Button's own recipe. Across a seven-column grid the pointer crosses many cells at once, and an eased wash reads as a cursor travelling rather than a grid flashing."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Day",
+          "why": "Picking a day eases the primary fill onto it and off the previous one, so a click reads as the selection moving rather than two cells flipping. A range's band is painted on the cells, which carry the same recipe, so the band eases along with its endpoints as the range grows."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Days are resident data; nothing in the grid loads. Availability fetched per month belongs to the surface around the calendar."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "Month",
+          "why": "Paging months slides the outgoing grid toward the edge it is leaving by and brings the new one in from the other, over a short travel with a fade (react-day-picker's `animate` mode on Sable keyframes in styles.css), so forward and back read as direction rather than a grid swapping in one frame. RDP adds a single class per part, which a recipe utility cannot be; mirrored in RTL. Expressive: Calendar turns `animate` on only at full motion, and an explicit `animate` prop still wins."
+        }
+      ],
       "a11y": [
         "react-day-picker manages the roving-tabindex grid, arrow-key navigation, and ARIA roles/labels for the calendar.",
         "Selected days use bg-primary/text-primary-foreground for AA contrast; today is marked with a dot under the number (not a ring, which is reserved for keyboard focus) rather than color alone.",
@@ -5975,6 +6141,12 @@
           "name": "arrowClassName",
           "type": "string",
           "description": "Class for both prev/next arrow buttons. Merged through cn(), so a radius or shadow utility replaces the default rounded-full shadow-md rather than stacking with it."
+        },
+        {
+          "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 glide, `off` stills it. It can only turn motion down — it never overrides a reader's reduce-motion setting. Under subtle the slides still travel and the active dot snaps; off also cuts between slides and pauses autoplay."
         }
       ],
       "tokensUsed": [
@@ -5985,6 +6157,38 @@
         "foreground",
         "muted-foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A carousel arrives with its section. Its content already moves on every advance; an entrance on top would make the first view feel like an advance nobody asked for."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Dot",
+          "why": "The dot's 24px hit area eases its focus ring and the dot brightens under the pointer, which is how a 6px mark tells you it is a button."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "Track",
+          "why": "The slide track's translate is set inline from the measured slide pitch, on --motion-duration-slow and the emphasized easing, and switched off during a drag so the track follows the finger. A recipe cannot carry a measured, drag-interrupted offset. Essential: it is the answer to \"next\", so it plays under subtle."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-glide",
+          "part": "Dot",
+          "why": "The active dot stretches to a bar while the one it left shrinks, on one timeline, so the row keeps its length and the mark reads as travelling with the slide. It used to change width unanimated and jumped while the slides beside it glided. Expressive: motion=\"subtle\" snaps it."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Autoplay's progress is the slides themselves advancing and the play/pause control; a separate timer animation would put a second clock beside the first."
+        }
+      ],
       "a11y": [
         "Region carries aria-roledescription='carousel'; each slide is a group with aria-roledescription='slide' and an 'N of M' label; clones are aria-hidden.",
         "Arrows and dots are real buttons (dots set aria-current); Left/Right arrow keys navigate when the viewport is focused.",
@@ -6011,6 +6215,11 @@
           "label": "Autoplay",
           "code": "<Carousel loop autoplay={4000} counter>{slides}</Carousel>",
           "imports": "import { Carousel } from \"@sableui/react\""
+        },
+        {
+          "label": "Subtle motion",
+          "code": "<Carousel loop motion=\"subtle\" label=\"Gallery\">{slides}</Carousel>",
+          "imports": "import { Carousel } from \"@sableui/react\""
         }
       ]
     },
@@ -6229,6 +6438,12 @@
           "type": "Ref<HTMLTextAreaElement>",
           "description": "Ref to the underlying textarea — for focusing after a send, or on mount, and the extension point for anything that listens to the field. Pass `useCaretTrigger`'s `fieldRef` here for mentions and slash commands (CaretMenu). An Enter another listener already handled (`preventDefault()`) does not send."
         },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. Under `subtle` the field snaps to its new height and the send/stop glyphs swap without the morph."
+        },
         {
           "name": "...form props",
           "type": "Omit<ComponentPropsWithRef<\"form\">, \"onSubmit\" | \"defaultValue\">",
@@ -6255,6 +6470,38 @@
         "accent",
         "accent-foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The composer is the fixed foot of a thread, there before anything else is. An entrance would only delay the first keystroke."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "The surface's focus ring and invalid border ease in, so focusing the field reads as the whole box waking up rather than a frame flicker."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "Field",
+          "why": "As a line breaks or a paste lands, the field eases to its new height (up to its cap) instead of jumping, so the transcript above is visibly pushed rather than teleported. `field-sizing` alone cannot ease — its height stays `auto` — so a small hook measures and pins a pixel height. Expressive and short (`fast`): the text itself lands at once, and `subtle` snaps the box."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-icon-swap",
+          "part": "Send button",
+          "why": "Send turning into stop is the moment a reply starts, and stop turning back is the moment it is over. One button changes role in place — the fill eases, the arrow collapses into the square — so it reads as the same control changing what it does, not a different button appearing under the cursor."
+        },
+        {
+          "slot": "activity",
+          "recipe": "motion-spin",
+          "part": "Send button",
+          "why": "Busy with no stop handler, Button's own loading Spinner replaces the arrow, so a send in flight is not mistaken for a disabled one."
+        }
+      ],
       "a11y": [
         "A real `<form>`, so the send button is a submit button and the whole thing behaves as one control to assistive tech and to password managers alike.",
         "Enter never submits while an IME composition is open (`isComposing`), so a CJK reader confirming a candidate word does not mail a fragment of their first sentence.",
@@ -6317,7 +6564,11 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Checkbox for mutually exclusive choices; use Radio or Select instead."
+            "description": "Do not use Checkbox for mutually exclusive choices; use Radio or Select instead.",
+            "instead": [
+              "Radio",
+              "Select"
+            ]
           },
           {
             "guidance": "dont",
@@ -6385,6 +6636,12 @@
           "name": "render",
           "type": "ReactElement | (props, state) => ReactElement",
           "description": "Compose the root with another element through the Base UI render prop."
+        },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. Under `subtle` the tick fades in instead of drawing itself."
         }
       ],
       "tokensUsed": [
@@ -6394,6 +6651,32 @@
         "primary-foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It arrives with the form it belongs to. Animating each box in turns a settings list into a title sequence."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Box",
+          "why": "The box fills with the primary colour as it is checked; easing the fill keeps the mark and the box changing as one event rather than two frames apart."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-tick",
+          "part": "Mark",
+          "why": "The check draws itself in from its leading stroke, so checking reads as the box being ticked rather than a glyph appearing. The dash wipes the same way. Unchecking only fades, so clearing a list is quick; under `subtle` checking fades too."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A checkbox commits instantly. A slow write belongs to the surrounding form's pending state, not the control."
+        }
+      ],
       "a11y": [
         "Base UI renders a hidden native <input type=checkbox> for keyboard, focus, and form semantics.",
         "Space toggles; focus-visible draws a 2px ring in the --ring token.",
@@ -6524,6 +6807,12 @@
           "name": "checked / onCheckedChange / defaultChecked / disabled",
           "type": "Base UI Checkbox.Root props",
           "description": "Standard checkbox state. Without a group-owned value, each card is independent — drive checked/onCheckedChange per item for multi-select."
+        },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. Under `subtle` the tick fades in instead of drawing itself."
         }
       ],
       "subcomponents": [
@@ -6563,6 +6852,32 @@
         "tone-warning",
         "tone-warning-foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It arrives with the form it belongs to. Animating each box in turns a settings list into a title sequence."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Box",
+          "why": "The box fills with the primary colour as it is checked; easing the fill keeps the mark and the box changing as one event rather than two frames apart."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-tick",
+          "part": "Mark",
+          "why": "The check draws itself in from its leading stroke, so checking reads as the box being ticked rather than a glyph appearing. The dash wipes the same way. Unchecking only fades, so clearing a list is quick; under `subtle` checking fades too."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A checkbox commits instantly. A slow write belongs to the surrounding form's pending state, not the control."
+        }
+      ],
       "a11y": [
         "Base UI provides the checkbox role, aria-checked, hidden native input, keyboard toggle, and data-[checked]/data-disabled state.",
         "The whole card is the hit target; focus draws a 2px outline outside the card (not a ring, so the checked tone ring survives focus); Space toggles the focused card.",
@@ -6756,9 +7071,36 @@
         "muted-foreground",
         "foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Code is reading content and arrives with the page or message it belongs to. An entrance of its own would delay the text someone came to copy."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Copy button",
+          "why": "The copy button is a quiet ghost icon in the corner of a block. Its hover fill is what tells the pointer it is a control and not decoration."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-icon-swap",
+          "part": "Copy glyph",
+          "why": "The copy mark turning into a check is the only proof the clipboard took the text. Snapped between frames it was easy to miss at the edge of a block; the swap reads as one mark being replaced."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Copying is instant. There is no in-between worth showing, and a spinner for a clipboard write would read as a slow one."
+        }
+      ],
       "a11y": [
         "Code renders inside a <pre><code> for correct semantics and screen-reader handling.",
-        "Copy is the ghost icon Button with `useCopy`, which guards clipboard access for SSR safety."
+        "Copy is the ghost icon Button with `useCopy`, which guards clipboard access for SSR safety.",
+        "A successful copy is announced as \"Copied\" through a polite role=status region that is always mounted; the button keeps its label, which names what it does. Both glyphs are aria-hidden."
       ],
       "examples": [
         {
@@ -6804,7 +7146,11 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Collapsible for multi-section navigation; use Accordion or Tabs instead."
+            "description": "Do not use Collapsible for multi-section navigation; use Accordion or Tabs instead.",
+            "instead": [
+              "Accordion",
+              "Tabs"
+            ]
           },
           {
             "guidance": "dont",
@@ -6876,6 +7222,38 @@
         "foreground",
         "muted-foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A collapsible is part of the page it sits in, present from first paint. Its trigger is what the reader notices, not an entrance."
+        },
+        {
+          "slot": "response",
+          "recipe": "none",
+          "part": "CollapsibleTrigger",
+          "why": "The trigger is whatever the consumer renders (usually a Button), and that control brings its own response. Adding one here would double it."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-disclosure",
+          "part": "CollapsiblePanel",
+          "why": "The height change ties the content that appears to the trigger that was pressed; snapped open, everything below jumps with nothing linking cause to effect."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "CollapsibleIndicator",
+          "why": "The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 writes."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Nothing here is indeterminate; content that loads on open should put its own loader inside the panel."
+        }
+      ],
       "a11y": [
         "Base UI wires aria-expanded on the trigger and aria-controls/id between trigger and panel.",
         "Trigger is a real <button>; toggles on click and Enter/Space.",
@@ -7017,22 +7395,48 @@
         "ring",
         "popover"
       ],
-      "a11y": [
-        "The trigger's accessible name includes the current value, so a screen reader announces the colour rather than just \"button\" — the swatch itself conveys nothing without sight.",
-        "The Transparent entry is a toggle with aria-pressed, because it is a state of the value and not a navigation action.",
-        "The hex field is the keyboard path to any colour. The saturation/value area and the sliders are pointer-driven and are NOT keyboard operable — a known gap, and the reason the hex field is never hidden.",
-        "The eyedropper is only rendered where the EyeDropper API exists (Chromium), rather than shown and broken elsewhere."
-      ],
-      "examples": [
+      "motion": [
         {
-          "label": "Canvas background",
-          "code": "<PropertyRow label=\"Background\">\n  <ColorField value={background} onValueChange={setBackground} allowTransparent />\n</PropertyRow>",
-          "imports": "import { ColorField, PropertyRow } from \"@sableui/react\""
+          "slot": "arrival",
+          "recipe": "motion-pop",
+          "part": "Popover",
+          "why": "The picker grows out of the swatch it edits (PopoverContent's recipe, its origin on the anchor). In a property panel with a column of swatches, that origin is what tells you which colour you are now editing."
         },
         {
-          "label": "With alpha and a palette",
-          "code": "<ColorField\n  value={tint}\n  onValueChange={setTint}\n  allowAlpha\n  swatches={[\"#f43f5e\", \"#facc15\", \"#22c55e\", \"#3b82f6\", \"#a855f7\"]}\n  label=\"Tint\"\n/>",
-          "imports": "import { ColorField } from \"@sableui/react\""
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Swatch",
+          "why": "Preset swatches lift slightly under the pointer. They are 20px chips of colour with no label, and the eased lift is what tells you which one a click will take."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Handles",
+          "why": "The saturation, hue and alpha handles follow the pointer exactly. A handle that trailed the drag would misreport the colour under the cursor, and a swatch or a typed hex moving them is the value changing, which the field should show at once."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Picking is synchronous. The EyeDropper is the browser's own modal, with its own feedback."
+        }
+      ],
+      "a11y": [
+        "The trigger's accessible name includes the current value, so a screen reader announces the colour rather than just \"button\" — the swatch itself conveys nothing without sight.",
+        "The Transparent entry is a toggle with aria-pressed, because it is a state of the value and not a navigation action.",
+        "The hex field is the keyboard path to any colour. The saturation/value area and the sliders are pointer-driven and are NOT keyboard operable — a known gap, and the reason the hex field is never hidden.",
+        "The eyedropper is only rendered where the EyeDropper API exists (Chromium), rather than shown and broken elsewhere."
+      ],
+      "examples": [
+        {
+          "label": "Canvas background",
+          "code": "<PropertyRow label=\"Background\">\n  <ColorField value={background} onValueChange={setBackground} allowTransparent />\n</PropertyRow>",
+          "imports": "import { ColorField, PropertyRow } from \"@sableui/react\""
+        },
+        {
+          "label": "With alpha and a palette",
+          "code": "<ColorField\n  value={tint}\n  onValueChange={setTint}\n  allowAlpha\n  swatches={[\"#f43f5e\", \"#facc15\", \"#22c55e\", \"#3b82f6\", \"#a855f7\"]}\n  label=\"Tint\"\n/>",
+          "imports": "import { ColorField } from \"@sableui/react\""
         },
         {
           "label": "The value format is the contract",
@@ -7078,7 +7482,11 @@
           },
           {
             "guidance": "dont",
-            "description": "Use Combobox for tiny option sets where Select or Radio would be easier to scan."
+            "description": "Use Combobox for tiny option sets where Select or Radio would be easier to scan.",
+            "instead": [
+              "Select",
+              "Radio"
+            ]
           },
           {
             "guidance": "do",
@@ -7090,7 +7498,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Use Combobox as a command launcher. Use CommandMenu for actions and navigation."
+            "description": "Use Combobox as a command launcher. Use CommandMenu for actions and navigation.",
+            "instead": [
+              "CommandMenu"
+            ]
           },
           {
             "guidance": "dont",
@@ -7256,6 +7667,50 @@
         "secondary",
         "secondary-foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "motion-pop",
+          "part": "ComboboxContent",
+          "why": "The list grows from the field it filters, its origin on Base UI's anchor. With several comboboxes in a form, that is what attaches the open list to the one being typed in."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "ComboboxItem",
+          "why": "A row's ink eases as the pointer or the arrow keys reach it, so moving through a long filtered list reads as continuous movement rather than rows blinking."
+        },
+        {
+          "slot": "response",
+          "recipe": "custom",
+          "part": "Highlight",
+          "why": "One highlight travels to the active row (lib/highlight-glide: a measured translate on the motion tokens) instead of each row painting its own fill. When the list re-filters under the caret, the highlight sliding to the new match is what shows the keyboard target moved."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Toggle",
+          "why": "The chevron toggle at the field's edge eases its ink on hover; the change is what tells you it is a separate target from the text box."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Toggle",
+          "why": "The chevron turns 180° as the list opens and closes (motion-interactive lists `rotate`), in step with the popup, so it reads as one control changing direction."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-pop",
+          "part": "ComboboxContent",
+          "why": "Closing shrinks back toward the field, returning the eye to the input that now holds the value."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Combobox ships no loading part. A list fetched as you type shows a Spinner (motion-spin) in ComboboxEmpty or the content — where the results will land — and only the caller knows a fetch is in flight."
+        }
+      ],
       "a11y": [
         "Base UI provides role=combobox/listbox/option, roving tabindex, arrow-key navigation, and type-to-filter.",
         "Esc and outside-press dismiss; focus returns to the input on close.",
@@ -7332,7 +7787,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Hand-style a <button> to look like a search field, or put a SearchInput in the header that opens a dialog when focused. The first drifts from the field it imitates; the second is a text box you cannot type in. A header search that opens the palette is CommandMenuTrigger."
+            "description": "Hand-style a <button> to look like a search field, or put a SearchInput in the header that opens a dialog when focused. The first drifts from the field it imitates; the second is a text box you cannot type in. A header search that opens the palette is CommandMenuTrigger.",
+            "instead": [
+              "CommandMenuTrigger"
+            ]
           },
           {
             "guidance": "do",
@@ -7348,7 +7806,12 @@
           },
           {
             "guidance": "dont",
-            "description": "Use CommandMenu as a replacement for every dropdown. Simple choices belong in Select, Menu, or Tabs."
+            "description": "Use CommandMenu as a replacement for every dropdown. Simple choices belong in Select, Menu, or Tabs.",
+            "instead": [
+              "Select",
+              "Menu",
+              "Tabs"
+            ]
           },
           {
             "guidance": "do",
@@ -7368,7 +7831,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Hand-build a palette mock from a search glyph, a row of buttons and a highlight. That is CommandMenuPanel, and the hand-built one has no combobox, no filtering and no keyboard model."
+            "description": "Hand-build a palette mock from a search glyph, a row of buttons and a highlight. That is CommandMenuPanel, and the hand-built one has no combobox, no filtering and no keyboard model.",
+            "instead": [
+              "CommandMenuPanel"
+            ]
           },
           {
             "guidance": "dont",
@@ -7539,6 +8005,44 @@
         "accent",
         "accent-foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "motion-pop",
+          "part": "Dialog",
+          "why": "The palette opens on DialogContent's recipe over a fading backdrop. It is summoned by a keystroke from nowhere on screen, and the short scale-in is what says a layer arrived rather than the page changing. The inline CommandMenuPanel has no entrance: it is part of the page."
+        },
+        {
+          "slot": "arrival",
+          "recipe": "motion-appear",
+          "part": "Clear button",
+          "why": "The clear button mounts on the first keystroke, beside the caret the eye is already on. Fading in, it reads as the field offering a way back instead of a control blinking into the header. Removal is instant, so an emptied query does not wait on its X."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "CommandItem",
+          "why": "The active row follows both the arrow keys and the pointer, and its fill eases between rows, so scanning results while typing reads as one highlight moving rather than rows flashing in turn."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "CommandMenuTrigger",
+          "why": "The search-shaped trigger eases its ink on hover like the field shell it imitates, so it reads as the field it opens."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-pop",
+          "part": "Dialog",
+          "why": "Closing on Enter or Esc shrinks the palette away fast and returns focus where it came from; the exit is the confirmation that the command ran or was dismissed."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "List",
+          "why": "Results are filtered synchronously from the items passed in. Async results are the caller's to mark with a Spinner (motion-spin) in the list, where the person is already looking."
+        }
+      ],
       "a11y": [
         "CommandMenuTrigger is a real <button> named by its visible placeholder, with aria-haspopup=dialog and aria-keyshortcuts (Meta+K on macOS, Control+K elsewhere). Its Kbd hint is aria-hidden, so the shortcut is announced once rather than read as part of the name.",
         "The shortcut never fires from inside a text field, textarea, select or contenteditable (Ctrl+K is delete-to-end-of-line in macOS text views), except the palette's own input.",
@@ -7595,6 +8099,223 @@
         }
       ]
     },
+    {
+      "name": "ConfirmButton",
+      "status": "stable",
+      "group": "Actions",
+      "register": "either",
+      "path": "components/confirm-button",
+      "summary": "An inline two-step confirm for a low-stakes destructive or irreversible action: the first press arms it (\"Delete\" → \"Confirm delete?\", destructive), a second press within a few seconds runs it, and leaving it disarms it.",
+      "keywords": [
+        "confirm",
+        "confirmation",
+        "two-step",
+        "press again",
+        "click again",
+        "arm",
+        "delete",
+        "remove",
+        "destructive",
+        "inline confirm",
+        "hold to confirm"
+      ],
+      "usage": {
+        "description": "Use ConfirmButton when an action deserves one beat of second thought but not a modal: deleting a draft, removing a row, revoking one token, clearing a list that can be rebuilt. The question appears on the button the user is already pressing, so confirming costs one more press in the same place and backing out costs nothing.",
+        "bestPractices": [
+          {
+            "guidance": "do",
+            "description": "Keep the idle label a plain verb (\"Delete\", \"Remove\", \"Revoke\") and let the confirm label ask about it (\"Confirm delete?\" by default, or `confirmLabel`). The user should read the consequence on the very control they are about to press again."
+          },
+          {
+            "guidance": "do",
+            "description": "Leave room for it to grow. The button eases wider to fit the question, so give it space at the end of a row or in a table's action column rather than wedging it between fixed-width neighbours."
+          },
+          {
+            "guidance": "do",
+            "description": "Return the promise from `onConfirm` when the action is async. The button stays armed with a spinner until it settles and refuses further presses, so a slow network cannot run it twice."
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not use it for high-stakes or wide-reaching actions — deleting a project, an account, anything other people depend on. Those need the consequence spelled out and a typed or deliberate confirmation; use DestructiveActionModal.",
+            "instead": [
+              "DestructiveActionModal"
+            ]
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not use it where an undo is possible. If the action can be reversed, run it on the first press and offer Undo in a Toast — no question at all is faster than a good question.",
+            "instead": [
+              "Toast"
+            ]
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not use it for a non-destructive primary action (\"Save\", \"Send\"). Asking twice for something harmless teaches people to press twice without reading, which is what defeats the confirm when it matters; use Button.",
+            "instead": [
+              "Button"
+            ]
+          }
+        ]
+      },
+      "related": {
+        "components": [
+          "Button",
+          "DestructiveActionModal",
+          "Toast",
+          "OverflowMenu"
+        ]
+      },
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "description": "The idle label — the action, e.g. \"Delete\"."
+        },
+        {
+          "name": "confirmLabel",
+          "type": "ReactNode",
+          "default": "\"Confirm <label>?\"",
+          "description": "The label while armed. Defaults to \"Confirm delete?\" for a text label \"Delete\" (first letter lowered) and \"Confirm?\" otherwise. Pass it to localise."
+        },
+        {
+          "name": "onConfirm",
+          "type": "() => unknown",
+          "description": "Runs on the second press while armed. Return a promise to hold the button armed with a spinner until it settles."
+        },
+        {
+          "name": "timeout",
+          "type": "number",
+          "default": "3000",
+          "description": "How long it waits for the second press, in ms. A decision time, so it is not scaled by motion settings."
+        },
+        {
+          "name": "variant",
+          "type": "ButtonVariant",
+          "default": "\"secondary\"",
+          "description": "The idle look — any Button variant."
+        },
+        {
+          "name": "confirmVariant",
+          "type": "ButtonVariant",
+          "default": "\"destructive\"",
+          "description": "The armed look — any Button variant."
+        },
+        {
+          "name": "size",
+          "type": "\"xs\" | \"sm\" | \"md\" | \"cta\"",
+          "default": "\"md\"",
+          "description": "A labelled Button size. Icon-only sizes are excluded: the label is the interaction."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "description": "A leading icon kept through both states, e.g. `<Icon name=\"trash\" />`."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": "false",
+          "description": "Disables it; disabling while armed also disarms."
+        },
+        {
+          "name": "confirmHint",
+          "type": "string",
+          "default": "\"Press again to confirm.\"",
+          "description": "Read to assistive tech after the armed label when it arms. Override to localise."
+        },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The width easing and the draining countdown are the flourish; the label cross-fade and colour change stay."
+        }
+      ],
+      "variants": {
+        "variant": [
+          "primary",
+          "secondary",
+          "ghost",
+          "outline",
+          "destructive",
+          "link",
+          "floating",
+          "field",
+          "on-color",
+          "on-color-outline",
+          "on-color-ghost"
+        ],
+        "confirmVariant": [
+          "destructive",
+          "primary",
+          "secondary",
+          "outline"
+        ],
+        "size": [
+          "xs",
+          "sm",
+          "md",
+          "cta"
+        ]
+      },
+      "tokensUsed": [
+        "secondary",
+        "secondary-foreground",
+        "destructive",
+        "destructive-foreground",
+        "ring"
+      ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It is a button in a row of actions, and arrives with that row. Its moment is the arming, not the mount."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "Root",
+          "why": "Inherited from Button with motion-interactive. The press settle confirms the first press landed even before the label has finished changing — which is what stops a second, accidental press."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-size",
+          "part": "Root",
+          "why": "Arming changes the label, so the button's width changes. Easing it makes the button visibly grow into the question and its neighbours travel, instead of the row jumping under the pointer that is about to press again. useAutoSize measures the content and writes a px width for motion-size to ease between (a content-sized box is width:auto before and after, which cannot transition). The labels cross-fade in one cell so there is never a frame with both or neither."
+        },
+        {
+          "slot": "activity",
+          "recipe": "custom",
+          "part": "Countdown",
+          "why": "While armed, a thin line drains along the foot of the button over the timeout — the only way to see that the question expires. A transition on scale, timed by the `timeout` prop and multiplied by the motion scale and expressive factor, so under reduced motion or `subtle` it is absent rather than frozen full."
+        }
+      ],
+      "a11y": [
+        "A native <button> through Button. Focus stays on it through both presses; Enter and Space confirm exactly as a click does.",
+        "Only the current label is in the accessible name — the other is aria-hidden — so the name changes to the question while armed.",
+        "Arming is also announced through a polite role=status region outside the button (\"Confirm delete? Press again to confirm.\"), because a focused button's name change is not read by every screen reader.",
+        "Escape disarms and is consumed, so it does not also close the dialog or popover around it. Focus leaving, a press elsewhere, or the timeout disarm it too.",
+        "A second press within 300ms of arming is ignored: a double-click is a habit, not a decision.",
+        "Under reduced motion the label still changes and the colour still turns; only the width easing and countdown are dropped."
+      ],
+      "examples": [
+        {
+          "label": "Delete a row",
+          "code": "<ConfirmButton icon={<Icon name=\"trash\" />} onConfirm={() => removeRow(id)}>Delete</ConfirmButton>",
+          "imports": "import { ConfirmButton, Icon } from \"@sableui/react\""
+        },
+        {
+          "label": "Custom question, longer wait",
+          "code": "<ConfirmButton variant=\"ghost\" size=\"sm\" confirmLabel=\"Revoke this key?\" timeout={5000} onConfirm={revokeKey}>Revoke</ConfirmButton>",
+          "imports": "import { ConfirmButton } from \"@sableui/react\""
+        },
+        {
+          "label": "Async confirm",
+          "code": "<ConfirmButton onConfirm={() => api.deleteDraft(draft.id)}>Discard draft</ConfirmButton>",
+          "imports": "import { ConfirmButton } from \"@sableui/react\""
+        }
+      ]
+    },
     {
       "name": "ContextCard",
       "status": "stable",
@@ -7625,7 +8346,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not open it on click. It is a hover/focus preview; making it click-triggered gives you a Popover with no dismiss affordance and no way to reach the content it previews."
+            "description": "Do not open it on click. It is a hover/focus preview; making it click-triggered gives you a Popover with no dismiss affordance and no way to reach the content it previews.",
+            "instead": [
+              "Popover"
+            ]
           }
         ],
         "anatomy": [
@@ -7996,6 +8720,38 @@
         "foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Rows render with the page or the query that produced them. Staggering rows in delays reading a table someone opened to scan."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Row",
+          "why": "Body rows ease to a muted wash under the pointer (TableRow's recipe), which keeps the eye on the right line across a wide row of numbers. Sortable headers are ghost Buttons and answer on Button's recipe."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Sort chevron",
+          "why": "One chevron turns to show direction instead of two glyphs swapping, so ascending to descending reads as the same column reversing. Its opacity rises from the resting 60% as the column becomes the sort."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Row",
+          "why": "A checked row's fill eases in across its cells, so selecting by checkbox reads as the row being picked rather than a band stamped over it."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "DataTable has no loading state. While data is fetched, render Skeleton rows (motion-shimmer) in its place — only the caller knows a fetch is in flight."
+        }
+      ],
       "a11y": [
         "Sorted columns set aria-sort=ascending/descending on the header cell.",
         "Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.",
@@ -8504,7 +9260,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space."
+            "description": "Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space.",
+            "instead": [
+              "Sheet"
+            ]
           },
           {
             "guidance": "do",
@@ -8512,7 +9271,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Use size=\"fullscreen\" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at."
+            "description": "Use size=\"fullscreen\" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at.",
+            "instead": [
+              "Sheet"
+            ]
           },
           {
             "guidance": "dont",
@@ -8520,7 +9282,12 @@
           },
           {
             "guidance": "dont",
-            "description": "Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead."
+            "description": "Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead.",
+            "instead": [
+              "Toast",
+              "Banner",
+              "InlineStatus"
+            ]
           },
           {
             "guidance": "do",
@@ -8770,7 +9537,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job."
+            "description": "Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job.",
+            "instead": [
+              "Select"
+            ]
           },
           {
             "guidance": "dont",
@@ -9244,11 +10014,37 @@
         "muted-foreground",
         "ring"
       ],
-      "a11y": [
-        "Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.",
-        "interactive rows render a real <button> around the leading visual and text, with its ::after stretched over the whole row — native focus, a focus-visible ring, and Enter/Space. The action slot sits outside that button and above the overlay, so a Button there stays valid HTML and keeps its own clicks.",
-        "Give any interactive action an accessible label (e.g. aria-label on a ghost icon Button).",
-        "A selected row announces aria-current=\"true\" on its button, so the current record is spoken, not only shown by its fill."
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Rows arrive with the list they belong to. Entering one at a time is a stagger, and a stagger on a list someone opened to scan is a delay."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "Only the interactive row reacts: its hover fill, a step off the surface it sits on, eases in. A static row never fakes clickability, and an interactive one answers the pointer without flicker as it moves down a list."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "`selected` eases the fill onto the current row of a list–detail view, so opening another record reads as the selection moving rather than two rows flashing."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A record row has nothing of its own to wait for. A row whose action is pending puts a loading Button in `action`."
+        }
+      ],
+      "a11y": [
+        "Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.",
+        "interactive rows render a real <button> around the leading visual and text, with its ::after stretched over the whole row — native focus, a focus-visible ring, and Enter/Space. The action slot sits outside that button and above the overlay, so a Button there stays valid HTML and keeps its own clicks.",
+        "Give any interactive action an accessible label (e.g. aria-label on a ghost icon Button).",
+        "A selected row announces aria-current=\"true\" on its button, so the current record is spoken, not only shown by its fill."
       ],
       "examples": [
         {
@@ -9270,7 +10066,7 @@
       "group": "Overlays",
       "register": "page",
       "path": "components/feedback",
-      "summary": "A compact feedback popover. Composes Popover + Textarea + Button + Toggle into a rating row plus a message field; submitting reports the rating + message and closes the popover.",
+      "summary": "A compact feedback popover. Composes Popover + Textarea + Button + Toggle into a rating row plus a message field; submitting reports the rating + message, shows a brief drawn-check thanks, and closes the popover.",
       "keywords": [
         "feedback",
         "sentiment",
@@ -9339,7 +10135,19 @@
         {
           "name": "onSubmit",
           "type": "(data: { rating?: string; message: string }) => void",
-          "description": "Called with the selected rating + message when the form is submitted."
+          "description": "Called with the selected rating + message when the form is submitted. The thanks shows right away; send the report in the background."
+        },
+        {
+          "name": "successMessage",
+          "type": "string",
+          "default": "\"Thanks for the feedback.\"",
+          "description": "The line shown, and read out, for about 1.2s after sending, before the popover closes on its own."
+        },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The drawn check is the flourish; the thanks line and its dwell stay."
         }
       ],
       "tokensUsed": [
@@ -9352,14 +10160,43 @@
         "muted-foreground",
         "accent",
         "accent-foreground",
-        "ring"
+        "ring",
+        "success"
+      ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "motion-pop",
+          "part": "Popover",
+          "why": "The form opens from its trigger, so the eye goes from the button it pressed to the field it should type in. Popover owns the recipe."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Rating toggles",
+          "why": "The rating row is a choice among a few similar marks. The eased selected fill is what makes the pick read as made, not just hovered."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-tick",
+          "part": "Thanks",
+          "why": "Sending is the one moment the person needs to know their words arrived. The form fades out in place and a check draws itself in over it, then the popover closes. Without it the popover just vanished, which looks the same as the form being dismissed or the message lost."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The thanks shows as soon as the form is sent; delivery is the app's background work. A spinner for a one-line report would make a quick, optional gesture feel heavy."
+        }
       ],
       "a11y": [
         "Trigger opens the popover on press; Base UI manages focus into the form and restores it to the trigger on close.",
         "The rating row is a Base UI ToggleGroup with arrow-key roving focus; each toggle carries an aria-label.",
         "The form is named by its heading (aria-labelledby), so it is announced as \"Send feedback\" rather than an unnamed form.",
         "The message field carries an aria-label matching its placeholder.",
-        "Submit is disabled until there is a rating or a non-whitespace message. Either alone is a complete answer."
+        "Submit is disabled until there is a rating or a non-whitespace message. Either alone is a complete answer.",
+        "On send, focus moves to the thanks line (tabIndex=-1), which reads it out, and the form becomes inert so focus cannot land in invisible fields. The line is not also a live region, which read it twice. When the popover closes, Base UI returns focus to the trigger.",
+        "The thanks dwell (about 1.2s) is a reading time, not motion, so it is the same under reduced motion."
       ],
       "examples": [
         {
@@ -9371,6 +10208,11 @@
           "label": "Custom labels",
           "code": "<Feedback label=\"Tell us\" submitLabel=\"Send it\" placeholder=\"Describe the issue…\" />",
           "imports": "import { Feedback } from \"@sableui/react\""
+        },
+        {
+          "label": "Custom thanks",
+          "code": "<Feedback successMessage=\"Got it — thank you.\" onSubmit={({ rating, message }) => report(rating, message)} />",
+          "imports": "import { Feedback } from \"@sableui/react\""
         }
       ]
     },
@@ -10424,7 +11266,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use InlineStatus for global announcements or page-level alerts."
+            "description": "Do not use InlineStatus for global announcements or page-level alerts.",
+            "instead": [
+              "Banner"
+            ]
           },
           {
             "guidance": "dont",
@@ -10769,6 +11614,32 @@
         "muted-foreground",
         "foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It arrives with the form it belongs to. A field that animated in on its own would be briefly unusable for no stated reason."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "The shell owns one focus ring for the input and its addons and eases it in, so focusing the text, or tabbing to a copy button inside the field, reads as the one field taking focus."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "An invalid value turns the shell's edge destructive on the same ease, so the error lands as the field changing state rather than a red box swapping in."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A field does no work of its own. A pending check (an availability lookup) puts a Spinner in `trailing`, which is where its answer will appear."
+        }
+      ],
       "a11y": [
         "The Input stays the focusable control; the group draws the focus ring around the whole field while it is focused.",
         "Inside a Field, the label, description and error are wired to the Input itself, not the group.",
@@ -10788,7 +11659,7 @@
         },
         {
           "label": "Copy button",
-          "code": "<Field label=\"API key\"><InputGroup trailing={<Button variant=\"ghost\" size=\"icon-sm\" aria-label=\"Copy key\" onClick={copy}><Icon name={copied ? \"check\" : \"copy\"} /></Button>}><Input readOnly value={key} /></InputGroup></Field>",
+          "code": "<Field label=\"API key\"><InputGroup trailing={<Button variant=\"ghost\" size=\"icon-sm\" aria-label=\"Copy key\" onClick={copy}><span aria-hidden=\"true\" className=\"motion-icon-swap\"><span data-active={!copied} className=\"inline-flex\"><Icon name=\"copy\" /></span><span data-active={copied} className=\"inline-flex\"><Icon name=\"check\" /></span></span></Button>}><Input readOnly value={key} /></InputGroup></Field>",
           "imports": "import { Button, Field, Icon, Input, InputGroup } from \"@sableui/react\""
         },
         {
@@ -11127,11 +11998,18 @@
           "default": "false for columns; true for horizontal bars",
           "description": "The vertical axis."
         },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The arrival (lines drawing on) and the data-change morph are the flourish; the gliding cursor, dots and tooltip are the feedback `subtle` keeps."
+        },
         {
           "name": "animate",
           "type": "boolean",
           "default": "true",
-          "description": "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart."
+          "description": "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. `animate={false}` is `motion=\"subtle\"`.",
+          "deprecated": "motion=\"subtle\" (what animate={false} now maps to: no arrival, hover kept) or motion=\"off\""
         },
         {
           "name": "activeIndex",
@@ -11192,7 +12070,7 @@
           "slot": "arrival",
           "recipe": "custom",
           "part": "Line",
-          "why": "Once on screen each line draws on from the first point (stroke-dashoffset), series staggered, then the dots and labels fade in. On the motion tokens; reduced motion shows the finished chart."
+          "why": "Once on screen each line draws on from the first point (stroke-dashoffset), series staggered, then the dots and labels fade in. On the motion tokens; reduced motion shows the finished chart. The arrival is expressive: it plays at the full motion level only, so `motion=\"subtle\"` (or a subtle app policy) shows the finished chart while hover feedback stays."
         },
         {
           "slot": "response",
@@ -11204,7 +12082,7 @@
           "slot": "transition",
           "recipe": "custom",
           "part": "Line + dots",
-          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place. Expressive, like the arrival: under `subtle` new data swaps in place."
         },
         {
           "slot": "activity",
@@ -11966,7 +12844,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not build a Select out of it. A menu fires actions and has no value; a Select holds one and reports changes. Swapping them loses form semantics and keyboard type-ahead."
+            "description": "Do not build a Select out of it. A menu fires actions and has no value; a Select holds one and reports changes. Swapping them loses form semantics and keyboard type-ahead.",
+            "instead": [
+              "Select"
+            ]
           },
           {
             "guidance": "do",
@@ -12162,7 +13043,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use a menubar for site navigation. Its items are commands in menus (role=menuitem), not links between pages."
+            "description": "Do not use a menubar for site navigation. Its items are commands in menus (role=menuitem), not links between pages.",
+            "instead": [
+              "NavigationMenu"
+            ]
           }
         ],
         "anatomy": [
@@ -12654,7 +13538,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Meter for a task in flight — an upload, an install, a step count. That is Progress; Meter tells assistive tech nothing is happening."
+            "description": "Do not use Meter for a task in flight — an upload, an install, a step count. That is Progress; Meter tells assistive tech nothing is happening.",
+            "instead": [
+              "Progress"
+            ]
           },
           {
             "guidance": "dont",
@@ -12937,7 +13824,7 @@
         },
         {
           "label": "Copyable value",
-          "code": "const { copy, copied } = useCopy(commitHash)\n<Row gap={1}><MiddleTruncate text={commitHash} /><Button variant=\"ghost\" size=\"icon-xs\" aria-label=\"Copy commit hash\" onClick={copy}><Icon name={copied ? \"check\" : \"copy\"} /></Button></Row>",
+          "code": "const { copy, copied } = useCopy(commitHash)\n<Row gap={1}><MiddleTruncate text={commitHash} /><Button variant=\"ghost\" size=\"icon-xs\" aria-label=\"Copy commit hash\" onClick={copy}><span aria-hidden=\"true\" className=\"motion-icon-swap\"><span data-active={!copied} className=\"inline-flex\"><Icon name=\"copy\" /></span><span data-active={copied} className=\"inline-flex\"><Icon name=\"check\" /></span></span></Button><span role=\"status\" className=\"sr-only\">{copied ? \"Copied\" : \"\"}</span></Row>",
           "imports": "import { Button, Icon, MiddleTruncate, Row, useCopy } from \"@sableui/react\""
         }
       ]
@@ -13169,7 +14056,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Note for state the whole page or app is in (an outage, an offline session, a blocked account) — that is Banner — or for a message tied to one field, which is the field's own error text."
+            "description": "Do not use Note for state the whole page or app is in (an outage, an offline session, a blocked account) — that is Banner — or for a message tied to one field, which is the field's own error text.",
+            "instead": [
+              "Banner"
+            ]
           },
           {
             "guidance": "dont",
@@ -13230,6 +14120,38 @@
         "success",
         "destructive"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A note is part of the content it annotates and renders with it. A callout that animated in would pull the eye before the reader has reached it in the flow."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Action",
+          "why": "The action's focus ring eases in, and its underline thickens on hover. Inside a block of guidance, that is what separates the one thing to do from the prose around it."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "Action",
+          "why": "A note's action usually navigates or opens something; the small settle on press is the only confirmation before the next surface paints."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A note has no states to move between: its tone is fixed when it renders. A note that changes tone is a new message, and should arrive as one."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Static guidance. Work in progress belongs in a Progress or a Spinner, not in a callout."
+        }
+      ],
       "a11y": [
         "Rendered with role=\"note\" so assistive tech can announce it as an aside.",
         "Color is never the sole signal — the leading icon and optional title reinforce severity."
@@ -13263,7 +14185,7 @@
       "group": "Badges & pills",
       "register": "either",
       "path": "components/notification-badge",
-      "summary": "An unread indicator. Renders a bare dot or a count pill (capped as \"{max}+\"), or nothing when there's nothing to show. overlay pins it to the corner of a relative host; it is aria-hidden, so the host's name carries the count.",
+      "summary": "An unread indicator. Renders a bare dot or a count pill (capped as \"{max}+\"), or nothing when there's nothing to show. A changing count rolls to its new number, and a badge that appears after being empty pops in. overlay pins it to the corner of a relative host; it is aria-hidden, so the host's name carries the count.",
       "keywords": [
         "notification",
         "badge",
@@ -13298,7 +14220,8 @@
       "related": {
         "components": [
           "Badge",
-          "StatusDot"
+          "StatusDot",
+          "NumberTicker"
         ]
       },
       "props": [
@@ -13336,6 +14259,12 @@
           "type": "boolean",
           "default": "false",
           "description": "Pin to the top-end corner of the nearest relative host (an icon button) — one placement for every caller instead of hand-tuned absolute offsets."
+        },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. Under `subtle` the count updates in place and the badge fades in without the pop."
         }
       ],
       "variants": {
@@ -13362,6 +14291,32 @@
         "secondary",
         "secondary-foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "motion-appear",
+          "part": "root",
+          "why": "A badge that shows up after being empty is the news — something just arrived — so it fades and scales in where it sits instead of popping into existence. Never on first paint: a badge that mounts with a count is content, and a page of them popping on load is noise."
+        },
+        {
+          "slot": "response",
+          "recipe": "none",
+          "part": "root",
+          "why": "It is decorative and not interactive; the host it sits on answers the pointer."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "Count",
+          "why": "The count rolls to its new number through NumberTicker (expressive), so 3 → 4 reads as one more arriving rather than a different badge. Past the cap the ticker holds at max with a static \"+\", so a count climbing beyond 99 does not keep rolling a badge that has not changed."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "root",
+          "why": "An unread count has no working state."
+        }
+      ],
       "a11y": [
         "The badge is aria-hidden: a count rendered on a control is not associated with it, so the host needs an accessible name that includes the count — \"Notifications, 3 unread\" — or a screen-reader user hears \"Notifications, button\" and never learns there is anything new. Pass aria-hidden={false} only for a standalone badge whose number is the information.",
         "A dot carries no number and no words: on its own it tells a sighted user only that something changed, and tells everyone else nothing. Pair it with a label that says what is new, and never make its colour the only difference between two states."
@@ -13493,6 +14448,176 @@
         }
       ]
     },
+    {
+      "name": "NumberTicker",
+      "status": "stable",
+      "group": "Data display",
+      "register": "either",
+      "path": "components/number-ticker",
+      "summary": "A number that rolls to its new value digit by digit, like an odometer. Formatted with Intl.NumberFormat (currency, percent, compact, any locale); separators, signs and units hold still while each digit column turns, and a digit that appears or goes away eases its width so nothing around it jumps. At rest on first paint; under subtle or reduced motion the value simply updates.",
+      "keywords": [
+        "number",
+        "counter",
+        "odometer",
+        "rolling number",
+        "animated number",
+        "ticker",
+        "count up",
+        "stat",
+        "kpi",
+        "metric",
+        "price"
+      ],
+      "usage": {
+        "description": "Use NumberTicker for a figure that changes in place while someone is looking at it — a dashboard total after a filter changes, a live count, a price as a plan's options change, a score. The roll says \"this number moved, and by roughly this much\"; the reader sees the change happen instead of noticing, later, that a number is different.",
+        "bestPractices": [
+          {
+            "guidance": "do",
+            "description": "Use it for the headline figure that a control on the same screen changes — the total above a chart, the price beside a quantity stepper — so cause and effect are seen together."
+          },
+          {
+            "guidance": "do",
+            "description": "Format through `format` (currency, percent, compact) rather than pre-formatting a string, so separators and units stay put while only the digits roll."
+          },
+          {
+            "guidance": "do",
+            "description": "Pass `aria-live=\"polite\"` only when the change itself is news the reader would otherwise miss; most tickers sit beside the control that changed them and need no announcement."
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not use it for values that change many times a second (a stopwatch, a stock tick, a progress percentage) — the rolls never land and read as a blur. Render the number as plain tabular text."
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not use it for numbers that are names rather than amounts — an order ID, a phone number, a year, a version. Rolling implies a quantity going up or down."
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not animate a number on page load to make it feel alive. The first paint is at rest on purpose; for an entrance, reveal the card it sits in (the Reveal motion primitive)."
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not use it for a value inside a known range that needs a picture of how full it is — show a Meter, with the number beside it.",
+            "instead": [
+              "Meter"
+            ]
+          }
+        ]
+      },
+      "related": {
+        "components": [
+          "Meter",
+          "NotificationBadge",
+          "PieChart",
+          "RadialChart",
+          "Sparkline"
+        ]
+      },
+      "props": [
+        {
+          "name": "value",
+          "type": "number",
+          "description": "The number to show. When it changes, the digits roll to it."
+        },
+        {
+          "name": "format",
+          "type": "Intl.NumberFormatOptions",
+          "description": "How to write the number — `{ style: \"currency\", currency: \"USD\" }`, `{ style: \"percent\" }`, `{ notation: \"compact\" }`, fraction digits. Passed to Intl.NumberFormat; an inline object is fine (it is compared by value)."
+        },
+        {
+          "name": "locales",
+          "type": "string | string[]",
+          "default": "runtime locale",
+          "description": "BCP 47 locale(s) for the formatting. Digits roll through the locale's own numbering system."
+        },
+        {
+          "name": "prefix",
+          "type": "ReactNode",
+          "description": "Before the number. A string becomes part of the number's text (and rolls in or out with it); an element is rendered as given."
+        },
+        {
+          "name": "suffix",
+          "type": "ReactNode",
+          "description": "After the number (\"+\", \" pts\"). A string becomes part of the number's text; an element is rendered as given."
+        },
+        {
+          "name": "trend",
+          "type": "\"auto\" | \"up\" | \"down\"",
+          "default": "\"auto\"",
+          "description": "Which way the digits roll. `auto` rolls up as the value grows and down as it shrinks; `up` / `down` fix it (a countdown, a score that only climbs)."
+        },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The roll is expressive, so `subtle` updates the value in place."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Merged onto the root span. Set the type tier here (`text-heading-2`, `text-display-lg`); the ticker adds tabular figures so widths hold still."
+        },
+        {
+          "name": "...span props",
+          "type": "Omit<ComponentPropsWithRef<\"span\">, \"children\" | \"prefix\">",
+          "description": "Remaining span attributes pass through to the root — `aria-live` to announce changes, `id`, data attributes."
+        }
+      ],
+      "tokensUsed": [],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The first paint is at rest. A number counting up on page load is decoration that delays the reading; the roll is kept for the moment the value actually changes."
+        },
+        {
+          "slot": "response",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It is a reading, not a control; the control that changes it gives the feedback."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "Digit",
+          "why": "Each digit column turns to its new place on the expressive roll (the slower token, emphasized easing, staggered from the ones column), and arriving or departing columns ease their width. The roll is what shows a change happened and how big it was — the hundreds turning reads as a bigger move than the ones. No recipe can translate per-digit columns, so it is custom; it is multiplied by --motion-expressive, so `subtle` and reduced motion land the value at once."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A number has no working state; show a Skeleton while it loads."
+        }
+      ],
+      "a11y": [
+        "The whole written number (with any string prefix or suffix) is real text in a visually hidden span; the rolling columns are aria-hidden and draw their glyphs as generated content, so screen readers, find-in-page and copy all get \"$1,234.50\", never a stack of digits.",
+        "It is not a live region by default — a figure that changes because the reader moved a control is already where their attention is. Pass `aria-live=\"polite\"` when a change elsewhere should be announced.",
+        "Tabular figures keep every digit the same width, so a roll never shifts the text around it."
+      ],
+      "examples": [
+        {
+          "label": "Basic",
+          "code": "<NumberTicker value={1284} className=\"text-heading-2\" />",
+          "imports": "import { NumberTicker } from \"@sableui/react\""
+        },
+        {
+          "label": "Currency",
+          "code": "<NumberTicker value={4280.5} format={{ style: \"currency\", currency: \"USD\" }} className=\"text-display-lg\" />",
+          "imports": "import { NumberTicker } from \"@sableui/react\""
+        },
+        {
+          "label": "Percent, announced",
+          "code": "<NumberTicker value={0.428} format={{ style: \"percent\", maximumFractionDigits: 1 }} aria-live=\"polite\" />",
+          "imports": "import { NumberTicker } from \"@sableui/react\""
+        },
+        {
+          "label": "Subtle",
+          "code": "<NumberTicker value={92} suffix=\" pts\" motion=\"subtle\" />",
+          "imports": "import { NumberTicker } from \"@sableui/react\""
+        }
+      ]
+    },
     {
       "name": "OtpField",
       "status": "stable",
@@ -13531,6 +14656,10 @@
             "guidance": "dont",
             "description": "Do not use OtpField for a password, an arbitrary-length PIN, or anything the user types from memory. Slots promise a fixed length; use Input with `type=\"password\"` and `autocomplete=\"current-password\"` instead."
           },
+          {
+            "guidance": "do",
+            "description": "Clear the error as soon as the user edits the code (`onValueChange` → reset the error), and set it again when the next code is refused. Each refusal is then a fresh change to invalid, so the field shakes for every wrong code, not only the first."
+          },
           {
             "guidance": "dont",
             "description": "Do not intercept paste or clear the field on a wrong code before the user has seen the error. Blocking paste breaks SMS autofill and password managers, and wiping the slots erases the evidence of which digit was wrong."
@@ -13624,7 +14753,13 @@
         {
           "name": "aria-invalid",
           "type": "boolean",
-          "description": "Marks every slot invalid (destructive border). `<Field error>` sets it for you."
+          "description": "Marks every slot invalid (destructive border and digits). Turning it on after mount shakes the field once. `<Field error>` sets it for you."
+        },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The shake is the flourish; the destructive colour stays at every level."
         },
         {
           "name": "disabled / readOnly / required / name / id / form",
@@ -13661,6 +14796,12 @@
           "part": "Slot",
           "why": "A filled slot strengthens its border, so a pasted code visibly lands in every slot at once. Easing it reads as the code arriving rather than the field flickering."
         },
+        {
+          "slot": "transition",
+          "recipe": "motion-shake",
+          "part": "Root",
+          "why": "A refused code shakes the field once as it turns invalid — the short horizontal no that makes a second wrong code feel noticed rather than ignored. It never carries the refusal alone: the digits and borders turn destructive and the Field says why. It plays on the change to invalid, not on mount, and is expressive, so `subtle` keeps only the colour."
+        },
         {
           "slot": "activity",
           "recipe": "none",
@@ -13672,7 +14813,8 @@
         "The root is a role=group named by the field label; the first slot shares the label through `id`/`htmlFor`, and later slots are announced by position (\"Character 2 of 6\").",
         "Only one slot is in the tab order. Arrow keys, Home/End and Backspace move between slots; Tab leaves the whole field.",
         "The first slot carries autocomplete=\"one-time-code\" and the numeric virtual keyboard, so iOS and Android offer the SMS code above the keyboard.",
-        "Slots render at 20px (`text-mono-lg`), above the 16px floor that stops iOS Safari zooming on focus."
+        "Slots render at 20px (`text-mono-lg`), above the 16px floor that stops iOS Safari zooming on focus.",
+        "An invalid code is never signalled by motion alone: every slot carries aria-invalid, the digits and borders turn destructive, and the Field's error message is wired through aria-describedby. The shake resolves instantly under reduced motion and `subtle`."
       ],
       "examples": [
         {
@@ -13690,6 +14832,11 @@
           "code": "<Field label=\"Verification code\" error=\"That code has expired. Request a new code and try again.\"><OtpField length={6} groupSize={3} defaultValue=\"482913\" /></Field>",
           "imports": "import { Field, OtpField } from \"@sableui/react\""
         },
+        {
+          "label": "Verify on completion, shake on a wrong code",
+          "code": "const [code, setCode] = useState(\"\")\nconst [wrong, setWrong] = useState(false)\n<Field label=\"Verification code\" error={wrong ? \"That code does not match. Check the message and try again.\" : undefined}><OtpField length={6} groupSize={3} value={code} onValueChange={(next) => { setCode(next); setWrong(false) }} onValueComplete={(value) => setWrong(value !== expected)} /></Field>",
+          "imports": "import { Field, OtpField } from \"@sableui/react\""
+        },
         {
           "label": "Alphanumeric",
           "code": "<Field label=\"Pairing code\"><OtpField length={8} groupSize={4} validationType=\"alphanumeric\" /></Field>",
@@ -13936,7 +15083,12 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton."
+            "description": "Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton.",
+            "instead": [
+              "Spinner",
+              "Progress",
+              "Skeleton"
+            ]
           },
           {
             "guidance": "dont",
@@ -14275,11 +15427,37 @@
         "hairline",
         "hairline-strong"
       ],
-      "a11y": [
-        "PanelResizer is a role=separator with aria-orientation, aria-valuenow/min/max, and is focusable — a pointer-only resizer is a keyboard trap.",
-        "Arrow keys resize by `step`; Home and End jump to the minimum and maximum.",
-        "Each Panel renders an <aside> with an accessible name from `label`, so panels are navigable landmarks."
-      ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Panels are the app's frame, present from first paint. A dock that slid in on load would make the workspace look like it is still assembling."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "PanelResizer",
+          "why": "The hairline widens into a visible bar on hover and turns primary on keyboard focus, eased, so a 1px edge says it can be grabbed before the pointer commits."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Panel",
+          "why": "Width tracks the pointer one-to-one while dragging, and keyboard steps land at once. An eased width would trail the cursor, and resizing is a layout change: easing it would reflow the canvas beside the panel on every frame."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Layout chrome has no working state."
+        }
+      ],
+      "a11y": [
+        "PanelResizer is a role=separator with aria-orientation, aria-valuenow/min/max, and is focusable — a pointer-only resizer is a keyboard trap.",
+        "Arrow keys resize by `step`; Home and End jump to the minimum and maximum.",
+        "Each Panel renders an <aside> with an accessible name from `label`, so panels are navigable landmarks."
+      ],
       "examples": [
         {
           "label": "Tool body with a resizable left panel",
@@ -14415,6 +15593,38 @@
         "muted-foreground",
         "hairline"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Sections are part of the inspector they sit in and arrive with it. Animating each in would make a panel switch look like a page load."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "PropertyGroup trigger",
+          "why": "The fold row eases its focus ring, so arrowing down a dense inspector shows where the keyboard is without the ring flickering from row to row."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-disclosure",
+          "part": "PropertyGroup panel",
+          "why": "The group opens by easing its height, so the rows below slide down to make room instead of jumping. In an inspector, the next section moving is otherwise how you lose your place."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-icon-swap",
+          "part": "PropertyGroup indicator",
+          "why": "The + collapses into − as the group opens, both glyphs stacked as one mark, so the indicator reads as this row changing state rather than a different icon landing."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The inspector edits values in place; nothing in it loads."
+        }
+      ],
       "a11y": [
         "PropertyGroup's row is a real button with aria-expanded (Collapsible); its summary is part of the button's name, so a closed group still announces its value.",
         "PropertyRow renders a real <label>; pass htmlFor with the control's id so clicking the label focuses it.",
@@ -14660,11 +15870,18 @@
           "default": "runtime locale",
           "description": "BCP 47 locale for default number and date formatting."
         },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The sweep, the slice morph and the rolling centre number are the flourish; the hover pull-out and dim are the feedback `subtle` keeps."
+        },
         {
           "name": "animate",
           "type": "boolean",
           "default": "true",
-          "description": "Sweep the slices in clockwise when the chart scrolls into view."
+          "description": "Sweep the slices in clockwise when the chart scrolls into view. `animate={false}` is `motion=\"subtle\"`.",
+          "deprecated": "motion=\"subtle\" (what animate={false} now maps to: no arrival, hover kept) or motion=\"off\""
         },
         {
           "name": "activeIndex",
@@ -14701,19 +15918,25 @@
           "slot": "arrival",
           "recipe": "custom",
           "part": "Slices",
-          "why": "Once on screen the slices are revealed by a mask that sweeps clockwise from 12 o'clock — the whole is read as it fills. On the motion tokens; reduced motion shows the finished chart."
+          "why": "Once on screen the slices are revealed by a mask that sweeps clockwise from 12 o'clock — the whole is read as it fills. On the motion tokens; reduced motion shows the finished chart. The arrival is expressive: it plays at the full motion level only, so `motion=\"subtle\"` (or a subtle app policy) shows the finished chart while hover feedback stays."
         },
         {
           "slot": "response",
           "recipe": "none",
           "part": "Active slice",
-          "why": "The hovered slice pulls outward and the rest dim at once; the geometry change itself eases (see transition)."
+          "why": "The hovered slice pulls outward and the rest dim at once (mixed toward the surface, not faded); the geometry change itself eases (see transition). Essential: `subtle` keeps it."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "Centre value",
+          "why": "A numeric centre value rolls to its new total digit by digit (NumberTicker) when the data changes, so the headline is seen moving with the slices instead of being found different afterwards. Expressive: under `subtle` it updates in place."
         },
         {
           "slot": "transition",
           "recipe": "custom",
           "part": "Slices",
-          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place. Expressive, like the arrival: under `subtle` new data swaps in place."
         },
         {
           "slot": "activity",
@@ -14768,7 +15991,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row — that is a Badge."
+            "description": "Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row — that is a Badge.",
+            "instead": [
+              "Badge"
+            ]
           },
           {
             "guidance": "dont",
@@ -14860,6 +16086,38 @@
         "muted-foreground",
         "foreground"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Pills arrive with the filter row or the content they annotate. A chip that animated in alone would read as a filter someone just added."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "The hover wash eases, so sweeping the pointer along a filter row reads as one cursor moving rather than chips flashing in turn."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "Root",
+          "why": "A pill often toggles a filter that takes a moment to reach the results; the settle on press confirms the click landed before they change."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "`selected` lifts the chip onto its selected surface on the same ease, so toggling reads as this chip changing state, not a different chip appearing in its place."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A chip is a choice, not a process. If applying it is slow, the results show it."
+        }
+      ],
       "a11y": [
         "Renders a native <button type=\"button\"> for focus and keyboard activation.",
         "Selected state is exposed via aria-pressed."
@@ -14913,11 +16171,17 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Popover for blocking confirmations, long forms, or critical information."
+            "description": "Do not use Popover for blocking confirmations, long forms, or critical information.",
+            "instead": [
+              "Dialog"
+            ]
           },
           {
             "guidance": "dont",
-            "description": "Do not put a form that can fail validation inside one. A popover dismisses on outside click, which discards what the user typed with no warning — that is a Dialog."
+            "description": "Do not put a form that can fail validation inside one. A popover dismisses on outside click, which discards what the user typed with no warning — that is a Dialog.",
+            "instead": [
+              "Dialog"
+            ]
           }
         ],
         "anatomy": [
@@ -15054,7 +16318,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use a determinate Progress for an unknown duration. A bar that sits at 90% is worse than a Spinner, because it makes a promise about time that you cannot keep."
+            "description": "Do not use a determinate Progress for an unknown duration. A bar that sits at 90% is worse than a Spinner, because it makes a promise about time that you cannot keep.",
+            "instead": [
+              "Spinner"
+            ]
           }
         ],
         "anatomy": [
@@ -15331,11 +16598,18 @@
           "default": "runtime locale",
           "description": "BCP 47 locale for default number and date formatting."
         },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The polygons growing in and morphing are the flourish; the hover highlight is the feedback `subtle` keeps."
+        },
         {
           "name": "animate",
           "type": "boolean",
           "default": "true",
-          "description": "Grow the polygons from the centre when the chart scrolls into view."
+          "description": "Grow the polygons from the centre when the chart scrolls into view. `animate={false}` is `motion=\"subtle\"`.",
+          "deprecated": "motion=\"subtle\" (what animate={false} now maps to: no arrival, hover kept) or motion=\"off\""
         },
         {
           "name": "activeIndex",
@@ -15372,7 +16646,7 @@
           "slot": "arrival",
           "recipe": "custom",
           "part": "Polygon",
-          "why": "Once on screen each polygon grows from the centre and fades in, series staggered, on the emphasized easing. On the motion tokens; reduced motion shows the finished chart."
+          "why": "Once on screen each polygon grows from the centre and fades in, series staggered, on the emphasized easing. On the motion tokens; reduced motion shows the finished chart. The arrival is expressive: it plays at the full motion level only, so `motion=\"subtle\"` (or a subtle app policy) shows the finished chart while hover feedback stays."
         },
         {
           "slot": "response",
@@ -15384,7 +16658,7 @@
           "slot": "transition",
           "recipe": "custom",
           "part": "Polygon",
-          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place. Expressive, like the arrival: under `subtle` new data swaps in place."
         },
         {
           "slot": "activity",
@@ -15548,11 +16822,18 @@
           "default": "runtime locale",
           "description": "BCP 47 locale for default number and date formatting."
         },
+        {
+          "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 — it never overrides a reader's reduce-motion setting. The draw-on, the ring morph and the rolling centre number are the flourish; the hover dim is the feedback `subtle` keeps."
+        },
         {
           "name": "animate",
           "type": "boolean",
           "default": "true",
-          "description": "Draw the rings round from their start when the chart scrolls into view."
+          "description": "Draw the rings round from their start when the chart scrolls into view. `animate={false}` is `motion=\"subtle\"`.",
+          "deprecated": "motion=\"subtle\" (what animate={false} now maps to: no arrival, hover kept) or motion=\"off\""
         },
         {
           "name": "activeIndex",
@@ -15589,19 +16870,25 @@
           "slot": "arrival",
           "recipe": "custom",
           "part": "Ring",
-          "why": "Once on screen each ring draws round from its start (stroke-dashoffset on a round-capped arc), staggered outside in. On the motion tokens; reduced motion shows the finished chart."
+          "why": "Once on screen each ring draws round from its start (stroke-dashoffset on a round-capped arc), staggered outside in. On the motion tokens; reduced motion shows the finished chart. The arrival is expressive: it plays at the full motion level only, so `motion=\"subtle\"` (or a subtle app policy) shows the finished chart while hover feedback stays."
         },
         {
           "slot": "response",
           "recipe": "none",
           "part": "Active ring",
-          "why": "The hovered ring stays full strength and the others dim at once."
+          "why": "The hovered ring stays full strength and the others dim at once — mixed toward the surface rather than faded, so a dimmed ring stays solid over its track instead of turning muddy. Essential: `subtle` keeps it."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "Centre value",
+          "why": "A numeric centre value rolls to its new total digit by digit (NumberTicker) when the data changes, so the headline is seen moving with the rings instead of being found different afterwards. Expressive: under `subtle` it updates in place."
         },
         {
           "slot": "transition",
           "recipe": "custom",
           "part": "Ring",
-          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+          "why": "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place. Expressive, like the arrival: under `subtle` new data swaps in place."
         },
         {
           "slot": "activity",
@@ -15654,7 +16941,11 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch."
+            "description": "Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch.",
+            "instead": [
+              "Checkbox",
+              "Switch"
+            ]
           },
           {
             "guidance": "dont",
@@ -15703,6 +16994,32 @@
         "primary",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Radios arrive with the form they belong to. Animating each one in turns a question into a title sequence."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "The ring's edge and focus ring ease, so arrowing through a group — which moves the selection with focus — reads as one choice moving down the list."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Indicator",
+          "why": "The dot grows from the centre on a spring and shrinks out of the radio being left. A group's selection moves from one option to another, and the paired grow and shrink is what makes it read as moving rather than two dots blinking."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A radio commits instantly. A slow write belongs to the surrounding form's pending state, not the control."
+        }
+      ],
       "a11y": [
         "Base UI provides the radiogroup/radio roles, aria-checked, hidden native inputs, and roving tabindex.",
         "Arrow keys move and select between items; Space selects the focused item; Tab enters/leaves the group.",
@@ -15855,6 +17172,44 @@
         "tone-info",
         "tone-warning"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Cards arrive with the form. A plan picker that animated each card in would delay the choice it exists to make."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "The edge steps toward the ring colour on hover, eased. On a card-sized target a hard snap across the whole border reads as the layout flickering."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "Root",
+          "why": "The settle on press confirms a click anywhere in the card — the radio is small, and without it a click in the card's body can feel like it missed the control."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "Checking eases the tone ring and wash onto the new card as the old one releases, so the choice reads as moving between cards rather than two cards repainting."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Indicator",
+          "why": "The radio dot grows in on a spring, the same mark as Radio, so a card and a plain radio confirm a choice the same way."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A choice commits instantly. A slow write belongs to the surrounding form's pending state."
+        }
+      ],
       "a11y": [
         "Base UI provides the radiogroup/radio roles, aria-checked, hidden native inputs, and roving tabindex.",
         "Arrow keys move and select between cards; Space selects the focused card; Tab enters/leaves the group.",
@@ -15943,6 +17298,38 @@
         "border",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It is a word in a line of text and arrives with that line."
+        },
+        {
+          "slot": "response",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The only hover change on the timestamp is a dotted underline, and text-decoration-line is discrete: CSS cannot tween it, so a transition here would animate nothing and imply the snap had been handled."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-pop",
+          "part": "Tooltip",
+          "why": "The pointer's real answer is the absolute time, which arrives in a Tooltip on its own fast pop. That short entrance is what makes the full date read as belonging to the word under the cursor."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The label does not tick: it is computed when the component renders, so it never changes in front of the reader. A timestamp rolling from one minute to two would pull the eye off the content it dates."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A timestamp has nothing to wait for."
+        }
+      ],
       "a11y": [
         "Renders a semantic <time> element with a machine-readable dateTime (ISO) attribute.",
         "The <time> carries tabIndex=0 (it is not focusable natively), so the absolute time — exposed via Base UI's Tooltip, which opens on keyboard focus as well as hover and wires aria-describedby — is reachable from the keyboard.",
@@ -16067,6 +17454,38 @@
       "tokensUsed": [
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It is a region, not an event; its content arrives with whatever fills it."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Viewport",
+          "why": "The region is focusable so the keyboard can scroll it, and its focus ring eases in like any control's. It is the one sign the region, not the page, now takes the arrow keys."
+        },
+        {
+          "slot": "response",
+          "recipe": "custom",
+          "part": "Scrollbar",
+          "why": "The vertical bar (`scrollbar-quiet`) stays hidden until the region is hovered, focused or scrolled, then fades its thumb in on the motion tokens. A bar that appeared in one frame would flash every time the pointer crossed the list."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Edge fade",
+          "why": "The edge fades switch on and off as you scroll, in the frame the content is already moving, so the change is carried by the scroll itself. They are a mask gradient, which CSS cannot interpolate without registered custom properties."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "A scroll region does no work of its own. Content still loading inside it brings its own Skeleton or Spinner."
+        }
+      ],
       "a11y": [
         "The edge fades are a CSS mask-image on the scrolling element, not overlay elements — there is nothing in the DOM to intercept a pointer or be read by assistive tech, and the content under a fade stays fully interactive.",
         "Two boxes: a chrome box carrying `className` (border, background, radius, sizing) and, inside it, the element that actually scrolls and carries the fade mask. They are split because a `mask-image` applies to its element's own border — so with both on one box, a bordered Scroller watched its frame dissolve at the scrolling edge. The axis is published as `data-orientation`, not `aria-orientation`, which is invalid on `role=\"group\"`.",
@@ -16234,6 +17653,38 @@
         "panel-field",
         "panel-field-hover"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It arrives with the inspector row it sits in."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Root",
+          "why": "The shell eases its focus ring like every field, so tabbing through a column of numbers shows where the keyboard is without flicker."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Handle",
+          "why": "The handle's ink brightens while the field is hovered. It is the only sign that the icon or prefix can be dragged, which nobody would guess from a label."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Value",
+          "why": "The number follows the drag pixel for pixel. Easing it — or rolling it with a NumberTicker — would show a value the pointer has already left, in a control whose whole point is precision."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Scrubbing is synchronous; there is nothing to wait for."
+        }
+      ],
       "a11y": [
         "The input carries the accessible name via `label`; the glyph is aria-hidden because it is decorative.",
         "Every scrub gesture is reachable from the keyboard: ArrowUp/ArrowDown step by `step`, Shift+Arrow by ten steps.",
@@ -16364,6 +17815,32 @@
         "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 — 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\"> — keyboard and form semantics come for free.",
         "Associate a <label htmlFor> (or wrap) — the magnifier glyph is decorative, not a label.",
@@ -16611,7 +18088,10 @@
           },
           {
             "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",
@@ -16772,11 +18252,18 @@
           },
           {
             "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",
@@ -17257,11 +18744,17 @@
           },
           {
             "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": [
@@ -17507,23 +19000,61 @@
         "foreground",
         "ring"
       ],
-      "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.",
-        "Collapsed content stays in the DOM, so screen readers can still reach it."
-      ],
-      "examples": [
+      "motion": [
         {
-          "label": "Long paragraph",
-          "code": "<ShowMore><p className=\"text-body-md text-foreground\">A long paragraph that exceeds the collapsed height…</p></ShowMore>",
-          "imports": "import { ShowMore } from \"@sableui/react\""
+          "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."
         },
         {
-          "label": "Collapsed to a line count",
-          "code": "<ShowMore collapsedLines={6}><p className=\"text-body-md text-foreground\">{post.description}</p></ShowMore>",
-          "imports": "import { ShowMore } from \"@sableui/react\""
-        }
-      ]
+          "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° 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.",
+        "Collapsed content stays in the DOM, so screen readers can still reach it."
+      ],
+      "examples": [
+        {
+          "label": "Long paragraph",
+          "code": "<ShowMore><p className=\"text-body-md text-foreground\">A long paragraph that exceeds the collapsed height…</p></ShowMore>",
+          "imports": "import { ShowMore } from \"@sableui/react\""
+        },
+        {
+          "label": "Collapsed to a line count",
+          "code": "<ShowMore collapsedLines={6}><p className=\"text-body-md text-foreground\">{post.description}</p></ShowMore>",
+          "imports": "import { ShowMore } from \"@sableui/react\""
+        }
+      ]
     },
     {
       "name": "Sidebar",
@@ -17606,6 +19137,12 @@
           "type": "\"rail\" | \"page\"",
           "default": "\"rail\"",
           "description": "Which surface the rail is painted on. \"rail\" is its own --sidebar-* surface with a border — 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 — 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 — it never overrides a reader's reduce-motion setting."
         }
       ],
       "subcomponents": [
@@ -17639,6 +19176,38 @@
         "sidebar-accent-foreground",
         "sidebar-ring"
       ],
+      "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 — a collapsed row's centred icon and an expanded row's inset icon sit on the same column — 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\".",
@@ -17701,7 +19270,10 @@
           },
           {
             "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",
@@ -17755,6 +19327,12 @@
           "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 — it never overrides a reader's reduce-motion setting."
         }
       ],
       "subcomponents": [
@@ -17781,6 +19359,32 @@
         "sidebar-accent-foreground",
         "sidebar-ring"
       ],
+      "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 — 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\".",
@@ -17841,7 +19445,10 @@
           },
           {
             "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",
@@ -18090,6 +19697,32 @@
         "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).",
@@ -18206,11 +19839,18 @@
           "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 — 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",
@@ -18242,7 +19882,7 @@
           "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",
@@ -18306,7 +19946,11 @@
           },
           {
             "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",
@@ -18697,11 +20341,17 @@
           },
           {
             "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",
@@ -19042,7 +20692,11 @@
           },
           {
             "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",
@@ -19197,7 +20851,11 @@
           },
           {
             "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",
@@ -19289,6 +20947,32 @@
         "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.",
@@ -19323,7 +21007,7 @@
       "group": "Navigation",
       "register": "either",
       "path": "components/tabs",
-      "summary": "Tabs over Base UI Tabs (roving focus, arrow-key nav, ARIA tablist wiring) in two styles: underline (page sections) or pill (compact switchers). Tabs (Root) + TabsList + TabsTrigger + TabsPanel.",
+      "summary": "Tabs over Base UI Tabs (roving focus, arrow-key nav, ARIA tablist wiring) in two styles: underline (page sections) or pill (compact switchers), with one indicator that glides to the active tab. Tabs (Root) + TabsList + TabsTrigger + TabsPanel.",
       "keywords": [
         "tabs",
         "tablist",
@@ -19347,11 +21031,18 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs."
+            "description": "Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs.",
+            "instead": [
+              "SideNav",
+              "NavigationMenu"
+            ]
           },
           {
             "guidance": "dont",
-            "description": "Do not use tabs for sequential steps. Tabs are peer views the user returns to in any order; a process with an order needs a stepper, or the user will skip ahead."
+            "description": "Do not use tabs for sequential steps. Tabs are peer views the user returns to in any order; a process with an order needs a stepper, or the user will skip ahead.",
+            "instead": [
+              "Stepper"
+            ]
           }
         ],
         "anatomy": [
@@ -19390,13 +21081,19 @@
           "type": "Base UI Tabs.Root props (value, defaultValue, onValueChange, orientation)",
           "default": "defaultValue: 0",
           "description": "Controls the active tab. Uncontrolled via defaultValue; controlled via value + onValueChange."
+        },
+        {
+          "name": "motion",
+          "type": "\"full\" | \"subtle\" | \"off\"",
+          "default": "\"full\"",
+          "description": "On Tabs: how much motion this component uses: `full` (default) inherits the app's policy, `subtle` keeps feedback and drops the glide, `off` stills it. It can only turn motion down — it never overrides a reader's reduce-motion setting."
         }
       ],
       "subcomponents": [
         {
           "name": "TabsList",
           "type": "Base UI Tabs.List props (activateOnFocus, loopFocus) + variant?: \"underline\" | \"pill\" + className",
-          "description": "The tablist row. variant=\"underline\" (default) draws a divider rule beneath the triggers; variant=\"pill\" drops the rule and fills the active trigger, which takes the theme's button shape (--button-radius). Triggers inherit the variant."
+          "description": "The tablist row. variant=\"underline\" (default) draws a divider rule beneath the triggers; variant=\"pill\" drops the rule and fills the active trigger, which takes the theme's button shape (--button-radius). Triggers inherit the variant. It renders the gliding indicator (Base UI Tabs.Indicator) itself, so do not add one."
         },
         {
           "name": "TabsTrigger",
@@ -19421,11 +21118,44 @@
         "foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Tabs arrive with the section they organise. An entrance of their own would announce navigation chrome louder than the content it navigates."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "TabsTrigger",
+          "why": "The label steps from muted to foreground under the pointer; the ease is what makes that read as an answer rather than a repaint."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-glide",
+          "part": "Indicator",
+          "why": "One underline (or pill) travels to the new tab and stretches to its width. A mark that teleports makes the reader re-find the selection on every click; one that moves is tracked without looking. Expressive: motion=\"subtle\" lands it in place. Each tab's own mark is the fallback until the indicator has measured, so the server render is already right."
+        },
+        {
+          "slot": "transition",
+          "recipe": "animate-fade-in",
+          "part": "TabsPanel",
+          "why": "The incoming panel fades in, opacity only, so a switch between two similar panels still registers. Skipped on first render (activation direction \"none\") so a page of tabs does not fade in on load, and the outgoing panel leaves layout at once so a quick second click never stacks both."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Switching tabs is synchronous. A panel that loads data shows its own Skeleton or Spinner inside the panel, where the wait is."
+        }
+      ],
       "a11y": [
         "Base UI provides the tablist/tab/tabpanel roles, aria-selected, and roving tabindex.",
         "Arrow keys move between tabs; Home/End jump to first/last; panels are linked via aria-controls.",
         "Active tab styling reads from the data-active attribute; disabled tabs from data-disabled. Disabled tabs are skipped by arrow-key navigation.",
-        "Keyboard focus shows a ring on the focused trigger in both variants; the panel remains focusable."
+        "Keyboard focus shows a ring on the focused trigger in both variants; the panel remains focusable.",
+        "The gliding indicator is role=\"presentation\" decoration; aria-selected on the tab carries the state."
       ],
       "examples": [
         {
@@ -19442,6 +21172,11 @@
           "label": "With a disabled tab",
           "code": "<Tabs defaultValue=\"overview\"><TabsList><TabsTrigger value=\"overview\">Overview</TabsTrigger><TabsTrigger value=\"billing\" disabled>Billing</TabsTrigger></TabsList><TabsPanel value=\"overview\">Overview content</TabsPanel></Tabs>",
           "imports": "import { Tabs, TabsList, TabsPanel, TabsTrigger } from \"@sableui/react\""
+        },
+        {
+          "label": "Subtle motion",
+          "code": "<Tabs defaultValue=\"table\" motion=\"subtle\"><TabsList><TabsTrigger value=\"table\">Table</TabsTrigger><TabsTrigger value=\"chart\">Chart</TabsTrigger></TabsList><TabsPanel value=\"table\">Rows</TabsPanel><TabsPanel value=\"chart\">Trend</TabsPanel></Tabs>",
+          "imports": "import { Tabs, TabsList, TabsPanel, TabsTrigger } from \"@sableui/react\""
         }
       ]
     },
@@ -19692,6 +21427,38 @@
         "muted-foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It sits in a settings panel or a popover, which owns the entrance."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Option (list)",
+          "why": "List rows ease their hover fill like Menu and Select rows, so a theme list beside a menu reads as the same kind of row."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Name (grid)",
+          "why": "In the grid, the theme's name brightens on hover, eased. The preview tile's outline steps rather than easing — outline is not in the recipe's transition list — so the name carries the motion."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Check (list)",
+          "why": "The check fades into the chosen row and out of the old one, so the choice reads as moving, at the same moment the whole interface repaints in the new theme."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Applying a theme is synchronous: the whole interface repaints at once, and that repaint is the feedback."
+        }
+      ],
       "a11y": [
         "The container is role=\"radiogroup\" with an aria-label; each card is a role=\"radio\" button with aria-checked reflecting the selected theme.",
         "Standard radio keyboard: arrow keys move the check — calling onValueChange on each press — and Space checks the focused option. That instant switching is right for a free, reversible choice; where a switch has a cost, use a DisclosurePicker list (a listbox: arrows move, Enter commits) with ThemePreview tiles instead.",
@@ -19789,6 +21556,12 @@
           "default": "\"Theme\"",
           "description": "Accessible label for the radiogroup."
         },
+        {
+          "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 glide, `off` stills it. It can only turn motion down — it never overrides a reader's reduce-motion setting."
+        },
         {
           "name": "className",
           "type": "string",
@@ -19804,6 +21577,38 @@
         "accent-foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "It arrives with the header or settings row it lives in; a theme control that announces itself competes with the page it themes."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Option",
+          "why": "The icon steps from muted to foreground under the pointer, which is what tells an icon-only segment it is a control."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "Option",
+          "why": "A settle under the press confirms the tap on a 28px target before the theme change repaints the page around it."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-glide",
+          "part": "Active pill",
+          "why": "One pill slides to the chosen mode, stepping by option + gap on the spacing scale, so light → dark reads as the same control moving, not three icons trading a fill. Expressive: motion=\"subtle\" lands it in place."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Changing the theme is synchronous; the repaint is the feedback."
+        }
+      ],
       "a11y": [
         "The container is role=\"radiogroup\" with an aria-label; each option is role=\"radio\" with aria-checked reflecting the selected value.",
         "Each icon button carries an aria-label (Light / Dark / System) plus a title tooltip, since the visual is icon-only.",
@@ -19825,6 +21630,11 @@
           "label": "Light selected",
           "code": "<ThemeSwitcher value=\"light\" onValueChange={setTheme} />",
           "imports": "import { ThemeSwitcher } from \"@sableui/react\""
+        },
+        {
+          "label": "Subtle motion",
+          "code": "<ThemeSwitcher value={theme} onValueChange={setTheme} motion=\"subtle\" />",
+          "imports": "import { ThemeSwitcher } from \"@sableui/react\""
         }
       ]
     },
@@ -19863,11 +21673,18 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not put one on every row of a list or in a repeated skeleton. Each orb runs its own animation frame loop painting hundreds of arcs; use Skeleton for content-shaped waits and Spinner inside buttons."
+            "description": "Do not put one on every row of a list or in a repeated skeleton. Each orb runs its own animation frame loop painting hundreds of arcs; use Skeleton for content-shaped waits and Spinner inside buttons.",
+            "instead": [
+              "Skeleton",
+              "Spinner"
+            ]
           },
           {
             "guidance": "dont",
-            "description": "Do not use it for a determinate wait. It carries no sense of how far along anything is — reach for Progress when a percentage exists."
+            "description": "Do not use it for a determinate wait. It carries no sense of how far along anything is — reach for Progress when a percentage exists.",
+            "instead": [
+              "Progress"
+            ]
           },
           {
             "guidance": "dont",
@@ -20023,7 +21840,11 @@
           },
           {
             "guidance": "dont",
-            "description": "Use Toast for critical blockers or persistent outages. Use Banner or Dialog when the user must notice and act."
+            "description": "Use Toast for critical blockers or persistent outages. Use Banner or Dialog when the user must notice and act.",
+            "instead": [
+              "Banner",
+              "Dialog"
+            ]
           },
           {
             "guidance": "dont",
@@ -20295,7 +22116,10 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use Toggle for persistent application settings; use Switch."
+            "description": "Do not use Toggle for persistent application settings; use Switch.",
+            "instead": [
+              "Switch"
+            ]
           },
           {
             "guidance": "dont",
@@ -20332,7 +22156,7 @@
           "name": "appearance",
           "type": "\"default\" | \"segmented\"",
           "default": "\"default\"",
-          "description": "On ToggleGroup: `default` is a loose row of toggles; `segmented` draws the capsule segmented control (one track, the pressed option filled) shared with ThemeSwitcher. Toggles inside inherit it."
+          "description": "On ToggleGroup: `default` is a loose row of toggles; `segmented` draws the capsule segmented control (one track, the pressed option filled) shared with ThemeSwitcher. Single-select segmented draws ONE fill that glides to the pressed option and resizes to its label; multi-select keeps a fill per pressed option. Toggles inside inherit it."
         },
         {
           "name": "multiple",
@@ -20340,6 +22164,12 @@
           "default": "false",
           "description": "On ToggleGroup: allow several toggles pressed at once. The default is single-select, which behaves like a radio group."
         },
+        {
+          "name": "motion",
+          "type": "\"full\" | \"subtle\" | \"off\"",
+          "default": "\"full\"",
+          "description": "On ToggleGroup: how much motion this component uses: `full` (default) inherits the app's policy, `subtle` keeps feedback and drops the glide, `off` stills it. It can only turn motion down — it never overrides a reader's reduce-motion setting."
+        },
         {
           "name": "Toggle",
           "type": "Base UI Toggle props (pressed, defaultPressed, onPressedChange, disabled, value) + className",
@@ -20350,7 +22180,7 @@
       "subcomponents": [
         {
           "name": "ToggleGroup",
-          "type": "Base UI ToggleGroup props (value, defaultValue, onValueChange, multiple, disabled, orientation, loopFocus) + appearance?: \"default\" | \"segmented\" + className",
+          "type": "Base UI ToggleGroup props (value, defaultValue, onValueChange, multiple, disabled, orientation, loopFocus) + appearance?: \"default\" | \"segmented\" + motion?: \"full\" | \"subtle\" | \"off\" + className",
           "description": "Groups child Toggles and shares pressed state across them — each Toggle inside carries a value. Defaults to multiple: false (single-select) — the fit for view-mode switches and segmented controls; pass multiple to allow several pressed at once, e.g. a row of formatting toggles."
         },
         {
@@ -20374,6 +22204,38 @@
         "border",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Toggle",
+          "why": "Toggles arrive with the toolbar or header they sit in. Animating each one in would make a row of controls ripple for no reason."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Toggle",
+          "why": "Hover and the pressed fill ease rather than flip, so pressing reads as the same button changing state, not a different button appearing."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "Toggle",
+          "why": "The small settle under the finger confirms the press landed before the state change is read — the difference matters most on touch, where there is no hover."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-glide",
+          "part": "Segmented fill",
+          "why": "In a single-select segmented group one fill travels to the chosen option and stretches to its label, so a view switch reads as one control now pointing elsewhere. Measured, because labels differ in width. Expressive: motion=\"subtle\" lands it in place."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Toggle",
+          "why": "A toggle commits instantly. Work that follows from the new state shows where its result appears, not on the control."
+        }
+      ],
       "a11y": [
         "Base UI sets aria-pressed on each Toggle and manages the pressed/disabled states.",
         "ToggleGroup provides arrow-key roving focus across its items; loopFocus wraps at the ends.",
@@ -20396,6 +22258,11 @@
           "code": "<ToggleGroup appearance=\"segmented\" defaultValue={[\"list\"]} aria-label=\"View\"><Toggle value=\"list\" aria-label=\"List view\"><Icon name=\"list\" /></Toggle><Toggle value=\"grid\" aria-label=\"Grid view\"><Icon name=\"grid\" /></Toggle></ToggleGroup>",
           "imports": "import { Icon, Toggle, ToggleGroup } from \"@sableui/react\""
         },
+        {
+          "label": "Segmented with labels, subtle motion",
+          "code": "<ToggleGroup appearance=\"segmented\" motion=\"subtle\" defaultValue={[\"week\"]} aria-label=\"Range\"><Toggle value=\"day\">Day</Toggle><Toggle value=\"week\">Week</Toggle><Toggle value=\"month\">Month</Toggle></ToggleGroup>",
+          "imports": "import { Toggle, ToggleGroup } from \"@sableui/react\""
+        },
         {
           "label": "Multi-select group",
           "code": "<ToggleGroup multiple defaultValue={[\"bold\"]}><Toggle value=\"bold\">Bold</Toggle><Toggle value=\"italic\">Italic</Toggle></ToggleGroup>",
@@ -20450,7 +22317,12 @@
           },
           {
             "guidance": "dont",
-            "description": "Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help."
+            "description": "Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help.",
+            "instead": [
+              "Tabs",
+              "SideNav",
+              "Breadcrumbs"
+            ]
           },
           {
             "guidance": "dont",
@@ -20583,73 +22455,302 @@
       },
       "tokensUsed": [
         "foreground",
-        "accent",
-        "accent-foreground",
-        "ring",
-        "hairline-strong",
-        "input",
-        "card"
+        "accent",
+        "accent-foreground",
+        "ring",
+        "hairline-strong",
+        "input",
+        "card"
+      ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Toolbar",
+          "why": "A toolbar is fixed chrome. It is present when its surface is; animating it in would leave the tools briefly unusable for no reason the user can see."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "ToolbarButton",
+          "why": "Inherited from buttonVariants: hover fill, focus ring and disabled dim ease together, so the item under the arrow keys reads as the one that moved."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "ToolbarButton",
+          "why": "Inherited from buttonVariants. Many toolbar actions change something off to the side (the canvas, the selection), so the settle on press is the confirmation that lands where the pointer is."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Toolbar",
+          "why": "The toolbar has no state of its own. Pressed state belongs to a Toggle rendered through ToolbarButton, which carries its own transition."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Toolbar",
+          "why": "A toolbar never works on its own. Pending work belongs to the surface the action targets, or to a Spinner in the button that started it."
+        }
+      ],
+      "a11y": [
+        "Base UI renders role=\"toolbar\" with aria-orientation, and a roving tabindex: the toolbar is one tab stop, the arrow keys move between items, Home/End jump to the ends.",
+        "Disabled items stay focusable by default and announce as disabled (aria-disabled), so arrowing along the row never silently skips a control. Set focusableWhenDisabled={false} on an item to opt out.",
+        "ToolbarSeparator is role=\"separator\" with the orientation opposite the toolbar's, and is not a focus stop.",
+        "ToolbarInput lets the arrow keys move the caret and only leaves the field at either end of its text.",
+        "Always set aria-label on the Toolbar, and on every icon-only ToolbarButton.",
+        "A Toggle rendered through ToolbarButton keeps aria-pressed; a MenuTrigger keeps aria-haspopup/aria-expanded."
+      ],
+      "examples": [
+        {
+          "label": "Formatting toolbar",
+          "code": "<Toolbar aria-label=\"Text formatting\">\n  <ToolbarGroup aria-label=\"History\">\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Undo\">\n      <Icon name=\"arrow-left\" />\n    </ToolbarButton>\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Redo\">\n      <Icon name=\"arrow-right\" />\n    </ToolbarButton>\n  </ToolbarGroup>\n  <ToolbarSeparator />\n  <ToggleGroup multiple aria-label=\"Style\">\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Bold\" render={<Toggle value=\"bold\" />}>\n      <Icon name=\"bold\" />\n    </ToolbarButton>\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Italic\" render={<Toggle value=\"italic\" />}>\n      <Icon name=\"italic\" />\n    </ToolbarButton>\n  </ToggleGroup>\n  <ToolbarSeparator />\n  <ToolbarLink href=\"/help\">Help</ToolbarLink>\n</Toolbar>",
+          "imports": "import { Icon, Toggle, ToggleGroup, Toolbar, ToolbarButton, ToolbarGroup, ToolbarLink, ToolbarSeparator } from \"@sableui/react\""
+        },
+        {
+          "label": "With a menu trigger and a search field",
+          "code": "<Toolbar aria-label=\"Table\">\n  <ToolbarButton>Export</ToolbarButton>\n  <Menu>\n    <ToolbarButton render={<MenuTrigger />}>View</ToolbarButton>\n    <MenuContent>\n      <MenuItem>Compact rows</MenuItem>\n      <MenuItem>Comfortable rows</MenuItem>\n    </MenuContent>\n  </Menu>\n  <ToolbarSeparator />\n  <ToolbarInput aria-label=\"Search rows\" placeholder=\"Search\" />\n</Toolbar>",
+          "imports": "import { Menu, MenuContent, MenuItem, MenuTrigger, Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from \"@sableui/react\""
+        },
+        {
+          "label": "Vertical tool rail",
+          "code": "<Toolbar orientation=\"vertical\" aria-label=\"Tools\">\n  <ToolbarButton size=\"icon-sm\" aria-label=\"Select\">\n    <Icon name=\"arrow-up\" />\n  </ToolbarButton>\n  <ToolbarButton size=\"icon-sm\" aria-label=\"Draw\">\n    <Icon name=\"edit\" />\n  </ToolbarButton>\n  <ToolbarSeparator />\n  <ToolbarButton size=\"icon-sm\" aria-label=\"Delete\" disabled>\n    <Icon name=\"trash\" />\n  </ToolbarButton>\n</Toolbar>",
+          "imports": "import { Icon, Toolbar, ToolbarButton, ToolbarSeparator } from \"@sableui/react\""
+        },
+        {
+          "label": "In a workspace bar",
+          "code": "<WorkspaceBar>\n  <Toolbar aria-label=\"Document\" className=\"flex-1\">\n    <ToolbarButton size=\"xs\">File</ToolbarButton>\n    <ToolbarButton size=\"xs\">Edit</ToolbarButton>\n    <ToolbarButton size=\"icon-xs\" aria-label=\"Share\" className=\"ms-auto\">\n      <Icon name=\"share\" />\n    </ToolbarButton>\n  </Toolbar>\n</WorkspaceBar>",
+          "imports": "import { Icon, Toolbar, ToolbarButton, WorkspaceBar } from \"@sableui/react\""
+        }
+      ]
+    },
+    {
+      "name": "ToolCall",
+      "status": "stable",
+      "group": "Chat & AI",
+      "register": "either",
+      "path": "components/tool-call",
+      "summary": "One tool an agent called, as a quiet row inside its turn: a status glyph, what it did, the tool's name and where it is — with the arguments and result behind a disclosure.",
+      "keywords": [
+        "tool call",
+        "function call",
+        "tool use",
+        "agent step",
+        "mcp",
+        "ai",
+        "tool result",
+        "agent activity"
+      ],
+      "usage": {
+        "description": "Use it for each tool call in an assistant's turn, so the person can see what the agent did and check any step. The row is the summary — glyph, a plain-words title, the tool's name, the status — and stays one line, so a turn with ten calls is still scannable. Input and output sit behind the disclosure, because they are read rarely and, when they are, in full.",
+        "bestPractices": [
+          {
+            "guidance": "do",
+            "description": "Give it a `title` in plain words, in the tense of the status: \"Searching the docs\" while running, \"Searched the docs\" once done. The `name` stays beside it in mono for the person who wants to know exactly which tool ran."
+          },
+          {
+            "guidance": "do",
+            "description": "Drive `status` from the call's real state and keep the same element mounted as it changes. The spinner swaps for the outcome in place, and the change is announced to screen readers once."
+          },
+          {
+            "guidance": "do",
+            "description": "Pass `error` with `status=\"error\"`. It shows under the row without opening anything, because a failure is the one result everyone needs to read."
+          },
+          {
+            "guidance": "do",
+            "description": "Pass a rendered result as `children` when the output is something to look at — a list of hits, a diff — rather than data to inspect. It replaces the output's code view, and `input` still shows above it."
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not put the approve and deny buttons in a ToolCall. A call held for permission is `status=\"awaiting\"` here, and the decision itself is ApprovalBlock, which says what will happen and asks once."
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not use it for the agent's thinking or a progress note. A wait with no tool behind it is ThinkingOrb or a Spinner with a status line, and a row that claims a tool ran when none did makes every other row less trustworthy.",
+            "instead": [
+              "ThinkingOrb",
+              "Spinner"
+            ]
+          },
+          {
+            "guidance": "dont",
+            "description": "Do not open every call by default. A turn whose calls all show their JSON buries the answer; leave `defaultOpen` for the one call the person is likely to check, if any."
+          }
+        ],
+        "anatomy": [
+          {
+            "name": "Status glyph",
+            "required": true,
+            "description": "Spinner while running, then the outcome: check, warning, clock (awaiting approval) or ×. The only part that moves."
+          },
+          {
+            "name": "Title",
+            "required": false,
+            "description": "What the call does, in plain words. Without one, the tool's name leads."
+          },
+          {
+            "name": "Name",
+            "required": true,
+            "description": "The tool's own name in mono, after the title. Hidden below the sm breakpoint when a title is present."
+          },
+          {
+            "name": "Status",
+            "required": true,
+            "description": "One word for where the call is: Running, Needs approval, Done, Failed, Denied."
+          },
+          {
+            "name": "Error line",
+            "required": false,
+            "description": "The failure message, under the row and always visible."
+          },
+          {
+            "name": "Details",
+            "required": false,
+            "description": "Input and output as code, or a rendered result. A disclosure; the row is its trigger."
+          }
+        ]
+      },
+      "related": {
+        "components": [
+          "Message",
+          "ThinkingOrb",
+          "StreamingText",
+          "CodeBlock",
+          "Collapsible",
+          "InlineStatus"
+        ]
+      },
+      "props": [
+        {
+          "name": "name",
+          "type": "string",
+          "description": "The tool's own name, as the model called it (`search_docs`). Shown in mono."
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "description": "What the call does, in words a person reads. Leads the row; omit it and `name` leads."
+        },
+        {
+          "name": "status",
+          "type": "\"running\" | \"awaiting\" | \"complete\" | \"error\" | \"denied\"",
+          "default": "\"running\"",
+          "description": "Where the call is. `awaiting` is held for the person's approval; `denied` is one they declined."
+        },
+        {
+          "name": "statusLabel",
+          "type": "string",
+          "description": "Overrides the status word, for another language or a more specific phrase."
+        },
+        {
+          "name": "input",
+          "type": "unknown",
+          "description": "The arguments. A string shows as is; anything else as formatted JSON."
+        },
+        {
+          "name": "output",
+          "type": "unknown",
+          "description": "The result, shown the same way as `input`."
+        },
+        {
+          "name": "error",
+          "type": "ReactNode",
+          "description": "What went wrong, for `status=\"error\"`. Always visible under the row."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "description": "A rendered result in place of `output`'s code view."
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "default": "false",
+          "description": "Open the details on mount."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "description": "Controlled open state of the details."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "(open: boolean) => void",
+          "description": "Called when the details open or close."
+        }
+      ],
+      "variants": {
+        "status": [
+          "running",
+          "awaiting",
+          "complete",
+          "error",
+          "denied"
+        ]
+      },
+      "tokensUsed": [
+        "card",
+        "border",
+        "destructive",
+        "muted",
+        "muted-foreground",
+        "foreground",
+        "tone-warning",
+        "ring"
       ],
       "motion": [
         {
           "slot": "arrival",
           "recipe": "none",
-          "part": "Toolbar",
-          "why": "A toolbar is fixed chrome. It is present when its surface is; animating it in would leave the tools briefly unusable for no reason the user can see."
+          "part": "Root",
+          "why": "It arrives as part of the assistant's turn, and the turn's own arrival covers it. A second entrance per call would make a busy turn twitch."
         },
         {
           "slot": "response",
           "recipe": "motion-interactive",
-          "part": "ToolbarButton",
-          "why": "Inherited from buttonVariants: hover fill, focus ring and disabled dim ease together, so the item under the arrow keys reads as the one that moved."
+          "part": "Header",
+          "why": "The header is the disclosure trigger but reads as a status row. The hover step is what tells the person it opens."
         },
         {
-          "slot": "response",
-          "recipe": "motion-press",
-          "part": "ToolbarButton",
-          "why": "Inherited from buttonVariants. Many toolbar actions change something off to the side (the canvas, the selection), so the settle on press is the confirmation that lands where the pointer is."
+          "slot": "transition",
+          "recipe": "motion-icon-swap",
+          "part": "Status glyph",
+          "why": "The spinner becoming a check or a warning is the moment the call settles, and it is the one change in the row worth catching from the corner of the eye. The swap reads as one mark replaced, not a flicker."
         },
         {
           "slot": "transition",
-          "recipe": "none",
-          "part": "Toolbar",
-          "why": "The toolbar has no state of its own. Pressed state belongs to a Toggle rendered through ToolbarButton, which carries its own transition."
+          "recipe": "motion-disclosure",
+          "part": "Details",
+          "why": "The height change connects the code that appears to the row that was pressed, in a thread where several rows look alike."
         },
         {
           "slot": "activity",
-          "recipe": "none",
-          "part": "Toolbar",
-          "why": "A toolbar never works on its own. Pending work belongs to the surface the action targets, or to a Spinner in the button that started it."
+          "recipe": "motion-spin",
+          "part": "Status glyph",
+          "why": "While the call runs, the spinner is what separates working from stuck. It pauses once the call settles, so a long thread of finished calls costs nothing."
         }
       ],
       "a11y": [
-        "Base UI renders role=\"toolbar\" with aria-orientation, and a roving tabindex: the toolbar is one tab stop, the arrow keys move between items, Home/End jump to the ends.",
-        "Disabled items stay focusable by default and announce as disabled (aria-disabled), so arrowing along the row never silently skips a control. Set focusableWhenDisabled={false} on an item to opt out.",
-        "ToolbarSeparator is role=\"separator\" with the orientation opposite the toolbar's, and is not a focus stop.",
-        "ToolbarInput lets the arrow keys move the caret and only leaves the field at either end of its text.",
-        "Always set aria-label on the Toolbar, and on every icon-only ToolbarButton.",
-        "A Toggle rendered through ToolbarButton keeps aria-pressed; a MenuTrigger keeps aria-haspopup/aria-expanded."
+        "With details, the header is a button with aria-expanded (Base UI Collapsible); its name is the title, the tool name and the status word, so it reads as one sentence.",
+        "A status change after mount is announced once through a polite role=status region (\"Searched the docs: Done\"). The status a call mounts with is not announced, so a thread restored from history stays quiet.",
+        "The glyph is aria-hidden: the status word beside it carries the meaning, so colour and shape are never the only signal."
       ],
       "examples": [
         {
-          "label": "Formatting toolbar",
-          "code": "<Toolbar aria-label=\"Text formatting\">\n  <ToolbarGroup aria-label=\"History\">\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Undo\">\n      <Icon name=\"arrow-left\" />\n    </ToolbarButton>\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Redo\">\n      <Icon name=\"arrow-right\" />\n    </ToolbarButton>\n  </ToolbarGroup>\n  <ToolbarSeparator />\n  <ToggleGroup multiple aria-label=\"Style\">\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Bold\" render={<Toggle value=\"bold\" />}>\n      <Icon name=\"bold\" />\n    </ToolbarButton>\n    <ToolbarButton size=\"icon-sm\" aria-label=\"Italic\" render={<Toggle value=\"italic\" />}>\n      <Icon name=\"italic\" />\n    </ToolbarButton>\n  </ToggleGroup>\n  <ToolbarSeparator />\n  <ToolbarLink href=\"/help\">Help</ToolbarLink>\n</Toolbar>",
-          "imports": "import { Icon, Toggle, ToggleGroup, Toolbar, ToolbarButton, ToolbarGroup, ToolbarLink, ToolbarSeparator } from \"@sableui/react\""
-        },
-        {
-          "label": "With a menu trigger and a search field",
-          "code": "<Toolbar aria-label=\"Table\">\n  <ToolbarButton>Export</ToolbarButton>\n  <Menu>\n    <ToolbarButton render={<MenuTrigger />}>View</ToolbarButton>\n    <MenuContent>\n      <MenuItem>Compact rows</MenuItem>\n      <MenuItem>Comfortable rows</MenuItem>\n    </MenuContent>\n  </Menu>\n  <ToolbarSeparator />\n  <ToolbarInput aria-label=\"Search rows\" placeholder=\"Search\" />\n</Toolbar>",
-          "imports": "import { Menu, MenuContent, MenuItem, MenuTrigger, Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from \"@sableui/react\""
+          "label": "A finished call",
+          "code": "<ToolCall\n\tname=\"search_docs\"\n\ttitle=\"Searched the docs\"\n\tstatus=\"complete\"\n\tinput={{ query: \"date range picker\" }}\n\toutput={{ hits: [\"DatePicker\", \"Calendar\", \"DateTile\"] }}\n/>",
+          "imports": "import { ToolCall } from \"@sableui/react\""
         },
         {
-          "label": "Vertical tool rail",
-          "code": "<Toolbar orientation=\"vertical\" aria-label=\"Tools\">\n  <ToolbarButton size=\"icon-sm\" aria-label=\"Select\">\n    <Icon name=\"arrow-up\" />\n  </ToolbarButton>\n  <ToolbarButton size=\"icon-sm\" aria-label=\"Draw\">\n    <Icon name=\"edit\" />\n  </ToolbarButton>\n  <ToolbarSeparator />\n  <ToolbarButton size=\"icon-sm\" aria-label=\"Delete\" disabled>\n    <Icon name=\"trash\" />\n  </ToolbarButton>\n</Toolbar>",
-          "imports": "import { Icon, Toolbar, ToolbarButton, ToolbarSeparator } from \"@sableui/react\""
+          "label": "Running, then failed",
+          "code": "<div className=\"flex flex-col gap-2\">\n\t<ToolCall name=\"read_file\" title=\"Reading package.json\" status=\"running\" input={{ path: \"package.json\" }} />\n\t<ToolCall\n\t\tname=\"run_tests\"\n\t\ttitle=\"Ran the tests\"\n\t\tstatus=\"error\"\n\t\terror=\"3 of 412 tests failed in date-picker.test.tsx.\"\n\t\tinput={{ filter: \"date-picker\" }}\n\t/>\n</div>",
+          "imports": "import { ToolCall } from \"@sableui/react\""
         },
         {
-          "label": "In a workspace bar",
-          "code": "<WorkspaceBar>\n  <Toolbar aria-label=\"Document\" className=\"flex-1\">\n    <ToolbarButton size=\"xs\">File</ToolbarButton>\n    <ToolbarButton size=\"xs\">Edit</ToolbarButton>\n    <ToolbarButton size=\"icon-xs\" aria-label=\"Share\" className=\"ms-auto\">\n      <Icon name=\"share\" />\n    </ToolbarButton>\n  </Toolbar>\n</WorkspaceBar>",
-          "imports": "import { Icon, Toolbar, ToolbarButton, WorkspaceBar } from \"@sableui/react\""
+          "label": "Waiting for approval",
+          "code": "<ToolCall name=\"send_email\" title=\"Send the invoice to Ada\" status=\"awaiting\" input={{ to: \"ada@example.com\", subject: \"INV-1042\" }} />",
+          "imports": "import { ToolCall } from \"@sableui/react\""
         }
       ]
     },
@@ -20679,7 +22780,11 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not put critical instructions, errors, or interactive content inside Tooltip."
+            "description": "Do not put critical instructions, errors, or interactive content inside Tooltip.",
+            "instead": [
+              "Popover",
+              "InlineStatus"
+            ]
           },
           {
             "guidance": "dont",
@@ -20757,7 +22862,12 @@
         {
           "name": "SimpleTooltip",
           "type": "Base UI Tooltip.Root props + content: ReactNode + children: ReactElement + side | align | sideOffset",
-          "description": "Shorthand wrapping Root + Trigger + Content for the common case. The single child becomes the trigger (via Base UI render); content sets the body; side / align / sideOffset forward to the content with the same defaults. Composition parts remain for advanced use."
+          "description": "Shorthand wrapping Root + Trigger + Content for the common case. The single child becomes the trigger (via Base UI render); content sets the body; side / align / sideOffset forward to the content with the same defaults. Composition parts remain for advanced use. Inside a TooltipGroup it becomes a trigger of the group's shared tooltip instead."
+        },
+        {
+          "name": "TooltipGroup",
+          "type": "{ children: ReactNode; motion?: \"full\" | \"subtle\" | \"off\" }",
+          "description": "One tooltip shared by every SimpleTooltip inside it — for a toolbar or a row of icon buttons. Moving the pointer along the row glides the tooltip to the next trigger and swaps its label (old fades out, new fades in, each sliding toward the direction of travel), instead of closing one tooltip and opening another a few pixels away. Renders no element. Each SimpleTooltip keeps its own content / side / align / sideOffset and `disabled`; root props such as open / onOpenChange belong to the shared tooltip and are ignored inside a group. `motion` turns it down: `subtle` jumps between triggers and only cross-fades the label. The composable Tooltip parts are unaffected."
         }
       ],
       "tokensUsed": [
@@ -20789,6 +22899,12 @@
           "recipe": "none",
           "part": "Content",
           "why": "Tooltip copy is resident before the tooltip opens. Anything that has to be fetched is a Popover with its own loading state."
+        },
+        {
+          "slot": "transition",
+          "recipe": "custom",
+          "part": "TooltipGroup",
+          "why": "Moving between triggers in a group, the one tooltip glides to the next trigger, resizes to its label and cross-fades the text with a short slide toward the direction of travel. Separate tooltips would close here and open there, two surfaces blinking side by side; the glide says it is the same hint following the pointer. Base UI's handle + Viewport supply the shared popup and the previous/current content; the timing is the expressive glide (slow, emphasized), so `subtle` keeps only the cross-fade."
         }
       ],
       "a11y": [
@@ -20812,6 +22928,11 @@
           "label": "Shorthand (SimpleTooltip)",
           "code": "<SimpleTooltip content=\"Saved to your workspace.\"><Button variant=\"ghost\" size=\"icon-sm\" aria-label=\"Info\"><Icon name=\"info\" /></Button></SimpleTooltip>",
           "imports": "import { Button, Icon, SimpleTooltip } from \"@sableui/react\""
+        },
+        {
+          "label": "One tooltip gliding along a toolbar (TooltipGroup)",
+          "code": "<TooltipGroup><Toolbar aria-label=\"Formatting\"><SimpleTooltip content=\"Bold\"><ToolbarButton size=\"icon-sm\" aria-label=\"Bold\"><Icon name=\"bold\" /></ToolbarButton></SimpleTooltip><SimpleTooltip content=\"Italic\"><ToolbarButton size=\"icon-sm\" aria-label=\"Italic\"><Icon name=\"italic\" /></ToolbarButton></SimpleTooltip><SimpleTooltip content=\"Insert link\"><ToolbarButton size=\"icon-sm\" aria-label=\"Insert link\"><Icon name=\"link\" /></ToolbarButton></SimpleTooltip></Toolbar></TooltipGroup>",
+          "imports": "import { Icon, SimpleTooltip, Toolbar, ToolbarButton, TooltipGroup } from \"@sableui/react\""
         }
       ]
     },
@@ -20992,6 +23113,12 @@
           "name": "label",
           "type": "ReactNode",
           "description": "TreeAddRow's visible label. Name what gets added — 'Add effect', not 'Add'."
+        },
+        {
+          "name": "motion",
+          "type": "\"full\" | \"subtle\" | \"off\"",
+          "default": "\"full\"",
+          "description": "On Tree. 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 — it never overrides a reader's reduce-motion setting. Under `subtle` expanded rows appear at once instead of unfolding; the chevron still turns."
         }
       ],
       "subcomponents": [
@@ -21029,6 +23156,32 @@
         "primary",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "motion-arrive",
+          "part": "TreeRow",
+          "why": "Rows a user's expand reveals fade down into place in document order (a capped 18ms stagger), so the eye can follow where the children came from. An animation (motion-arrive) rather than a transition, because the rows already wear motion-interactive and a second transition list would fight it. Only on a user expand of a `subtree` — a tree that mounts open shows its rows at once, and rows added later to an open folder do not cascade. Expressive: `subtle` shows them at once."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "TreeRow",
+          "why": "Hover and selection fills ease, so sweeping the pointer down a dense panel reads as a highlight following it rather than rows flickering."
+        },
+        {
+          "slot": "transition",
+          "recipe": "motion-interactive",
+          "part": "Disclosure",
+          "why": "The chevron turns with the rows arriving under it; motion-interactive lists `rotate`, which is what -rotate-90 writes, so it no longer flips in one frame."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Tree",
+          "why": "A tree has no indeterminate state of its own; a branch that loads its children should render a TreeEmpty or a loading row inside it."
+        }
+      ],
       "a11y": [
         "Tree implements the ARIA tree view pattern: Tree is role=\"tree\", each TreeRow and TreeAddRow is role=\"treeitem\" with aria-level, expandable rows carry aria-expanded, and a TreeSection is a role=\"group\" labelled by its heading. Rows stay flat in the DOM — hierarchy is aria-level — so the fills span the panel's full width.",
         "Keyboard: exactly one row is in the tab order (roving tabindex, seeded on the selected row, else the first). ArrowUp/Down move between visible rows; ArrowRight expands a collapsed row, then steps to its first child; ArrowLeft collapses an expanded row, else steps to its parent; Home/End jump to the ends; Enter/Space activate the row — its onClick, or toggling it when it has none. Keys pressed inside a row's own controls (an action button, a rename field) are left to that control.",
@@ -21143,6 +23296,38 @@
         "overlay-foreground",
         "ring"
       ],
+      "motion": [
+        {
+          "slot": "arrival",
+          "recipe": "none",
+          "part": "Root",
+          "why": "The frame arrives with its page. Once there is a source, the poster and controls are the browser's."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-interactive",
+          "part": "Play button",
+          "why": "With `onRequestPlay`, the play disc firms its scrim on hover, eased, so the mark reads as pressable over any image."
+        },
+        {
+          "slot": "response",
+          "recipe": "motion-press",
+          "part": "Play button",
+          "why": "Loading a source can take a moment; the settle on press confirms the tap before the player appears."
+        },
+        {
+          "slot": "transition",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Placeholder to player is a swap of elements: the native video mounts where the poster was. Animating the swap would delay the playback the person just asked for."
+        },
+        {
+          "slot": "activity",
+          "recipe": "none",
+          "part": "Root",
+          "why": "Buffering belongs to the native controls, which draw their own indicator. A second loader over the frame would compete with the browser's."
+        }
+      ],
       "a11y": [
         "Mounts a native <video> element, preserving built-in keyboard controls when controls is enabled.",
         "Without onRequestPlay the placeholder play mark is decorative (aria-hidden) — nothing on the frame pretends to be pressable. With it, the mark is a native button named \"Play video\"."
@@ -21576,6 +23761,31 @@
         "imports": "import { Button, Card, CardAction, CardDescription, CardHeader, CardList, CardTitle, cn, Code, Entity, Icon, MenuItem, MenuSeparator, OverflowMenu } from \"@sableui/react\"",
         "code": "const keys = [\n\t{ id: \"k1\", name: \"Production\", hint: \"sk_live_••••4f2a\", detail: \"Created Mar 2 · used 4 minutes ago\" },\n\t{ id: \"k2\", name: \"Staging\", hint: \"sk_test_••••91cd\", detail: \"Created Feb 11 · used yesterday\" },\n\t{ id: \"k3\", name: \"CI deploys\", hint: \"sk_live_••••0b7e\", detail: \"Created Jan 5 · never used\" },\n]\n\nexport interface ApiKeysBlockProps {\n\tclassName?: string\n\t/** false drops the card's surface and border — for a muted section that already frames it. */\n\tframed?: boolean\n\tonCreate?: () => void\n\t/** Called with the key's id and the action chosen from its menu. */\n\tonKeyAction?: (id: string, action: \"rename\" | \"roll\" | \"revoke\") => void\n}\n\nexport function ApiKeysBlock({ className, framed = true, onCreate, onKeyAction }: ApiKeysBlockProps) {\n\treturn (\n\t\t<Card variant={framed ? \"default\" : \"flat\"} className={cn(\"w-full max-w-2xl\", className)}>\n\t\t\t<CardHeader>\n\t\t\t\t<CardTitle render={<h2 />}>API keys</CardTitle>\n\t\t\t\t<CardDescription>A key is shown once, when you create it. Store it somewhere safe.</CardDescription>\n\t\t\t\t<CardAction>\n\t\t\t\t\t<Button size=\"sm\" variant=\"outline\" iconStart={<Icon name=\"key\" />} onClick={onCreate}>\n\t\t\t\t\t\tCreate key\n\t\t\t\t\t</Button>\n\t\t\t\t</CardAction>\n\t\t\t</CardHeader>\n\t\t\t<CardList>\n\t\t\t\t{keys.map((k) => (\n\t\t\t\t\t<Entity\n\t\t\t\t\t\tkey={k.id}\n\t\t\t\t\t\ttitle={\n\t\t\t\t\t\t\t<span className=\"flex flex-wrap items-center gap-x-2\">\n\t\t\t\t\t\t\t\t{k.name}\n\t\t\t\t\t\t\t\t<Code>{k.hint}</Code>\n\t\t\t\t\t\t\t</span>\n\t\t\t\t\t\t}\n\t\t\t\t\t\tsubtitle={k.detail}\n\t\t\t\t\t\taction={\n\t\t\t\t\t\t\t<OverflowMenu label={`Manage the ${k.name} key`} size=\"icon-sm\">\n\t\t\t\t\t\t\t\t<MenuItem onClick={() => onKeyAction?.(k.id, \"rename\")}>Rename</MenuItem>\n\t\t\t\t\t\t\t\t<MenuItem onClick={() => onKeyAction?.(k.id, \"roll\")}>Roll key</MenuItem>\n\t\t\t\t\t\t\t\t<MenuSeparator />\n\t\t\t\t\t\t\t\t<MenuItem variant=\"destructive\" onClick={() => onKeyAction?.(k.id, \"revoke\")}>\n\t\t\t\t\t\t\t\t\tRevoke\n\t\t\t\t\t\t\t\t</MenuItem>\n\t\t\t\t\t\t\t</OverflowMenu>\n\t\t\t\t\t\t}\n\t\t\t\t\t/>\n\t\t\t\t))}\n\t\t\t</CardList>\n\t\t</Card>\n\t)\n}"
       },
+      {
+        "name": "ApprovalBlock",
+        "path": "blocks/approval-block.tsx",
+        "summary": "An agent asking permission for one tool call: the question, what will happen and what can't be undone, the call's details, an \"allow for the rest of this chat\" Checkbox, and Deny / Allow.",
+        "intent": "Reach for this in a chat or agent run when a tool call waits on the person — sending, paying, deleting, publishing. The call itself, before and after the decision, is a ToolCall with status=\"awaiting\", then \"complete\" or \"denied\". A destructive action outside an agent is DestructiveActionModal.",
+        "family": "AI & agents",
+        "kind": "card",
+        "width": {
+          "min": "18rem",
+          "max": "28rem"
+        },
+        "notes": [
+          "The title is the question in plain words (\"Send the invoice to Ada?\"), not the tool's name; the tool's name is one row of the details, for the person who wants to know exactly what runs.",
+          "The description says what can't be undone. That sentence is what the person is deciding on.",
+          "Deny comes first and Allow is the primary on the end, the same order as every Sable confirmation. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.",
+          "After a decision the buttons give way to one InlineStatus line saying what happened, so the thread keeps a record of the answer."
+        ],
+        "a11y": [
+          "Focus moves to the outcome line when the buttons leave, instead of dropping to the page; the line is a role=status region, so the decision is announced.",
+          "The details are a dl, so each value is read with its label.",
+          "The remember Checkbox has its own Label, so the tool name inside it is part of its accessible name."
+        ],
+        "imports": "import { useState, useEffect, useRef, useId } from \"react\"\nimport { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, cn, Code, InlineStatus, Label } from \"@sableui/react\"",
+        "code": "const request = {\n\ttool: \"send_email\",\n\ttitle: \"Send the invoice to Ada?\",\n\tdescription: \"The agent wants to email invoice INV-1042. An email can't be unsent.\",\n\tdetails: [\n\t\t{ label: \"To\", value: \"ada@example.com\" },\n\t\t{ label: \"Subject\", value: \"INV-1042 for October\" },\n\t\t{ label: \"Attached\", value: \"INV-1042.pdf\" },\n\t],\n\tallowed: \"Allowed. Sending the email.\",\n\tdenied: \"Denied. The agent won't send it.\",\n}\n\nexport interface ApprovalBlockProps {\n\tclassName?: string\n\t/** false drops the card's surface and border — for a chat column that already frames it. */\n\tframed?: boolean\n\t/** The person allowed the call. `remember` is the \"for the rest of this chat\" choice. */\n\tonApprove?: (options: { remember: boolean }) => void\n\t/** The person declined the call. */\n\tonDeny?: () => void\n}\n\nexport function ApprovalBlock({ className, framed = true, onApprove, onDeny }: ApprovalBlockProps) {\n\tconst [decision, setDecision] = useState<\"allowed\" | \"denied\" | null>(null)\n\tconst [remember, setRemember] = useState(false)\n\tconst id = useId()\n\tconst outcome = useRef<HTMLDivElement>(null)\n\t// The buttons leave with the decision, so focus moves to the line that\n\t// replaces them instead of falling back to the top of the page.\n\tuseEffect(() => {\n\t\tif (decision) outcome.current?.focus()\n\t}, [decision])\n\n\treturn (\n\t\t<Card variant={framed ? \"default\" : \"flat\"} className={cn(\"w-full max-w-md\", className)}>\n\t\t\t<CardHeader>\n\t\t\t\t<CardTitle>{request.title}</CardTitle>\n\t\t\t\t<CardDescription>{request.description}</CardDescription>\n\t\t\t</CardHeader>\n\t\t\t<CardContent className=\"flex flex-col gap-4\">\n\t\t\t\t<dl className=\"grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1.5 text-body-sm\">\n\t\t\t\t\t{request.details.map((d) => (\n\t\t\t\t\t\t<div key={d.label} className=\"contents\">\n\t\t\t\t\t\t\t<dt className=\"text-muted-foreground\">{d.label}</dt>\n\t\t\t\t\t\t\t<dd className=\"truncate text-foreground\">{d.value}</dd>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t))}\n\t\t\t\t\t<div className=\"contents\">\n\t\t\t\t\t\t<dt className=\"text-muted-foreground\">Tool</dt>\n\t\t\t\t\t\t<dd className=\"min-w-0\">\n\t\t\t\t\t\t\t<Code>{request.tool}</Code>\n\t\t\t\t\t\t</dd>\n\t\t\t\t\t</div>\n\t\t\t\t</dl>\n\t\t\t\t{decision ? null : (\n\t\t\t\t\t<div className=\"flex items-center gap-2\">\n\t\t\t\t\t\t<Checkbox id={`${id}-remember`} checked={remember} onCheckedChange={(v: boolean) => setRemember(v)} />\n\t\t\t\t\t\t<Label htmlFor={`${id}-remember`} className=\"text-body-sm\">\n\t\t\t\t\t\t\tAllow <Code>{request.tool}</Code> for the rest of this chat\n\t\t\t\t\t\t</Label>\n\t\t\t\t\t</div>\n\t\t\t\t)}\n\t\t\t</CardContent>\n\t\t\t<CardFooter actions className=\"justify-end\">\n\t\t\t\t{decision ? (\n\t\t\t\t\t<InlineStatus\n\t\t\t\t\t\tref={outcome}\n\t\t\t\t\t\ttabIndex={-1}\n\t\t\t\t\t\trole=\"status\"\n\t\t\t\t\t\ttone={decision === \"allowed\" ? \"success\" : \"neutral\"}\n\t\t\t\t\t\tclassName=\"me-auto outline-none\"\n\t\t\t\t\t>\n\t\t\t\t\t\t{decision === \"allowed\" ? request.allowed : request.denied}\n\t\t\t\t\t</InlineStatus>\n\t\t\t\t) : (\n\t\t\t\t\t<>\n\t\t\t\t\t\t<Button\n\t\t\t\t\t\t\tvariant=\"outline\"\n\t\t\t\t\t\t\tonClick={() => {\n\t\t\t\t\t\t\t\tsetDecision(\"denied\")\n\t\t\t\t\t\t\t\tonDeny?.()\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\tDeny\n\t\t\t\t\t\t</Button>\n\t\t\t\t\t\t<Button\n\t\t\t\t\t\t\tonClick={() => {\n\t\t\t\t\t\t\t\tsetDecision(\"allowed\")\n\t\t\t\t\t\t\t\tonApprove?.({ remember })\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\tAllow\n\t\t\t\t\t\t</Button>\n\t\t\t\t\t</>\n\t\t\t\t)}\n\t\t\t</CardFooter>\n\t\t</Card>\n\t)\n}"
+      },
       {
         "name": "ChatThreadBlock",
         "path": "blocks/chat-thread-block.tsx",
@@ -23059,8 +25269,8 @@
     {
       "slug": "motion",
       "title": "Motion",
-      "summary": "Motion explains a change: where something came from, what responded, and that work is happening. It is subtle by default, built from named recipes, and one switch turns it off.",
-      "headline": "4 slots · 3 speeds · enter-only overshoot · 1 kill switch",
+      "summary": "Motion explains a change: where something came from, what responded, and that work is happening. Components ship crafted by default: one indicator travels instead of two blinking, numbers roll, ticks draw, a refused answer shakes. It is built from named recipes, comes in two levels, and one switch turns it off.",
+      "headline": "4 slots · 3 speeds · 2 levels · enter-only overshoot · 1 kill switch",
       "retrieve": "sable docs motion",
       "vocabularies": [
         {
@@ -23121,7 +25331,37 @@
             {
               "name": "motion-icon-swap",
               "value": "enter · emphasized cross-fade",
-              "use": "Two icons of one control trading places: play/pause, outline/fill."
+              "use": "Two icons of one control trading places: play/pause, outline/fill, copy/check."
+            },
+            {
+              "name": "motion-glide",
+              "value": "slow · emphasized · expressive",
+              "use": "ONE indicator travelling to the selected option: tabs, segmented thumb, active dot."
+            },
+            {
+              "name": "motion-shake",
+              "value": "~400ms decaying · expressive",
+              "use": "A refused answer: wrong code, invalid submit. Plays while data-shake is set (useShake). Never the only signal."
+            },
+            {
+              "name": "motion-tick",
+              "value": "fast fade + base wipe · expressive",
+              "use": "A check mark that draws itself in. Exits only fade."
+            },
+            {
+              "name": "motion-appear",
+              "value": "fast fade + base scale",
+              "use": "A small control mounting in place: a clear button, a send arrow, a badge. @starting-style, no JS."
+            },
+            {
+              "name": "motion-arrive",
+              "value": "base · decelerate · staggered · expressive",
+              "use": "Items a user action brings into a list: a folder's children on expand, a row just added. Never on every render."
+            },
+            {
+              "name": "motion-size",
+              "value": "base · emphasized · expressive",
+              "use": "An element easing between intrinsic sizes when its label changes: a two-step confirm, Copy → Copied."
             },
             {
               "name": "motion-draw",
@@ -23165,6 +25405,42 @@
             }
           ]
         },
+        {
+          "title": "Two levels",
+          "note": "Essential motion answers the user; expressive motion narrates continuity. Expressive durations are also multiplied by --motion-expressive, which `subtle` sets to 0. Each level can only turn motion down from what surrounds it.",
+          "terms": [
+            {
+              "name": "essential",
+              "value": "always, unless off",
+              "use": "Colour and focus feedback, press, overlay arrival, disclosure height, loaders, chart hover."
+            },
+            {
+              "name": "expressive",
+              "value": "full only",
+              "use": "Glides, rolling numbers (NumberTicker), drawn ticks, shakes, staggers, chart arrival and morph, scroll reveals, spring overshoot."
+            },
+            {
+              "name": "full",
+              "value": "default",
+              "use": "Both levels play. The crafted default."
+            },
+            {
+              "name": "subtle",
+              "value": "data-motion=\"subtle\"",
+              "use": "Essential only; nothing overshoots. For dense tools, embedded widgets, readers who want calm without stillness."
+            },
+            {
+              "name": "off",
+              "value": "data-motion=\"off\" · reduce-motion",
+              "use": "Nothing moves; every state still changes."
+            },
+            {
+              "name": "where",
+              "value": "provider · scope · prop",
+              "use": "<MotionProvider policy> for the app, <MotionScope level> for a region, `motion` on a component that owns a flourish."
+            }
+          ]
+        },
         {
           "title": "The four slots",
           "note": "Every interactive component answers all four, by filling the slot or declining it with a reason in meta.motion.",
@@ -23223,6 +25499,22 @@
         {
           "rule": "JS motion reads useMotion().enabled and does nothing when it is false.",
           "why": "Reduced motion is an accessibility setting, not a style preference."
+        },
+        {
+          "rule": "One thing travels; two things do not blink. When a selection, a value or a mark changes in place, move the one element that represents it.",
+          "why": "A fill switching off here and on there is two events the eye has to connect. A glide, a roll or a draw is one, and it is most of what makes an interface feel made rather than assembled."
+        },
+        {
+          "rule": "Flourishes are expressive: multiply their durations by --motion-expressive and gate JS ones on useMotion().expressive.",
+          "why": "`subtle` promises the answers without the choreography. A glide on a plain token keeps playing after someone asked for calm."
+        },
+        {
+          "rule": "A state change finishes its story: refused shakes and says why, success confirms in place, armed asks again.",
+          "why": "Motion that starts a change and leaves the outcome to a snap reads as unfinished. ConfirmButton, OtpField's invalid shake and the copy-to-check swap are the reference cases."
+        },
+        {
+          "rule": "Component motion props and MotionScope only turn motion down.",
+          "why": "`full` on a component means inherit. Nothing below the provider can switch motion back on for a reader who asked for it off."
         }
       ],
       "noGos": [
@@ -24300,6 +26592,126 @@
           "motion-interactive"
         ]
       },
+      {
+        "name": "motion-glide",
+        "kind": "utility",
+        "family": "motion",
+        "intent": "Timing for ONE element that travels to the selected option — position and size ease on the emphasized curve at the slow step. Expressive: `data-motion=\"subtle\"` makes it snap.",
+        "whenToUse": "A selection indicator you position yourself: a custom nav's current-page bar, a segmented control's thumb, an active dot. Tabs, ToggleGroup `segmented`, ThemeSwitcher and Carousel already glide.",
+        "insteadOf": "A fill or border on each option that switches on and off (two things blink instead of one thing moving), or a hand-written transition with a literal duration.",
+        "example": "<span aria-hidden className=\"motion-glide absolute bottom-0 h-0.5 bg-foreground\" style={{ left: x, width: w }} />",
+        "keywords": [
+          "sliding indicator",
+          "tab indicator",
+          "segmented thumb",
+          "active indicator",
+          "glide",
+          "underline animation",
+          "selection animation"
+        ],
+        "pairsWith": [
+          "motion-interactive"
+        ]
+      },
+      {
+        "name": "motion-shake",
+        "kind": "utility",
+        "family": "motion",
+        "intent": "A short decaying horizontal shake that plays while `data-shake` is set. `useShake()` sets and clears the attribute and restarts it on a repeat refusal. Expressive: under `subtle` only the error colour remains.",
+        "whenToUse": "An answer the system refused: a wrong one-time code, a submit with invalid fields, a rejected password. Always alongside the error colour and message, never instead of them. OtpField's `invalid` already shakes.",
+        "insteadOf": "A keyframe shake with a literal duration, which keeps moving under reduced motion, or a shake with no error text.",
+        "example": "const { shake, shakeProps } = useShake()\n<form className=\"motion-shake\" {...shakeProps} onSubmit={(e) => { if (!valid) { e.preventDefault(); shake() } }}>…</form>",
+        "keywords": [
+          "shake",
+          "error animation",
+          "wrong password",
+          "invalid",
+          "refuse",
+          "wiggle",
+          "nope"
+        ],
+        "pairsWith": [
+          "motion-interactive"
+        ]
+      },
+      {
+        "name": "motion-tick",
+        "kind": "utility",
+        "family": "motion",
+        "intent": "A selection mark that draws itself in from its leading edge (a clip-path wipe, so it works on any icon set) with an essential fade, keyed to Base UI's starting/ending style. Exits only fade. The wipe is expressive.",
+        "whenToUse": "A check or success glyph that mounts with its state: a custom selection card's tick, a completed step. Checkbox and CheckboxCard already use it.",
+        "insteadOf": "A scale-from-zero pop on a check mark, which reads as a stamp rather than a tick, or a path-length draw that needs to own the SVG.",
+        "example": "<Base.Indicator className=\"motion-tick\"><Icon name=\"check\" /></Base.Indicator>",
+        "keywords": [
+          "check animation",
+          "tick",
+          "draw check",
+          "success mark",
+          "checkbox animation",
+          "selection mark"
+        ]
+      },
+      {
+        "name": "motion-appear",
+        "kind": "utility",
+        "family": "motion",
+        "intent": "Fades and scales a small control in on first render through `@starting-style` — no data attribute, no JS. The fade is essential, the scale is expressive. Removal is instant.",
+        "whenToUse": "A control that mounts in place as state changes: a search field's clear button, a send button replacing a mic, a count badge that appears. Put it on a wrapper around a Sable Button or anything carrying `motion-interactive`, so the two do not fight over `transition-property`.",
+        "insteadOf": "Conditionally rendering a control so it pops in on one frame, or wrapping a single icon button in Presence.",
+        "example": "{value && <span className=\"flex motion-appear\"><Button size=\"icon-xs\" variant=\"ghost\" aria-label=\"Clear\"><Icon name=\"xmark\" /></Button></span>}",
+        "keywords": [
+          "appear",
+          "mount animation",
+          "pop in",
+          "enter",
+          "starting style",
+          "clear button"
+        ],
+        "pairsWith": [
+          "motion-icon-swap"
+        ]
+      },
+      {
+        "name": "motion-arrive",
+        "kind": "utility",
+        "family": "motion",
+        "intent": "Items a user action brings into a list settle into place one after another: a short fade down from 0.25rem. Stagger with `--motion-arrive-delay` (raw ms; the recipe scales it). Expressive.",
+        "whenToUse": "Only on items that are NEW because of something the user did: a folder's children on expand, a row just added, results that load in. Tree's expand already uses it.",
+        "insteadOf": "A staggered entrance on every render of a list, which turns a list into a loading delay, or an inline keyframe animation with literal durations.",
+        "example": "<li className=\"motion-arrive\" style={{ \"--motion-arrive-delay\": \"36ms\" } as CSSProperties}>{row.name}</li>",
+        "keywords": [
+          "stagger",
+          "list animation",
+          "arrival",
+          "cascade",
+          "new item",
+          "expand children",
+          "enter list"
+        ],
+        "pairsWith": [
+          "motion-interactive"
+        ]
+      },
+      {
+        "name": "motion-size",
+        "kind": "utility",
+        "family": "motion",
+        "intent": "Eases an element between sizes: between a keyword and a length (0 ↔ auto) through `interpolate-size: allow-keywords`, and between measured pixel sizes when paired with `useAutoSize()`, so a button whose label changes stretches to the new width instead of jumping. A superset of motion-interactive's transition list, so it can sit on a Button. The size is expressive.",
+        "whenToUse": "A control whose content changes length in place: a two-step confirm button, a Copy → Copied label, a chip that gains a count. ConfirmButton already uses it.",
+        "insteadOf": "A hand-written width transition, or a fixed width that clips the longer label. A content-sized box computes `width: auto` before and after its label changes, so on its own the recipe has nothing to ease — that is what `useAutoSize()` is for.",
+        "example": "const size = useAutoSize<HTMLButtonElement, HTMLSpanElement>()\n<button type=\"button\" ref={size.outerRef} className=\"motion-size\">\n\t<span ref={size.innerRef} className=\"inline-flex w-max\">{copied ? \"Copied\" : \"Copy link\"}</span>\n</button>",
+        "keywords": [
+          "width animation",
+          "auto width",
+          "label change",
+          "resize animation",
+          "interpolate size",
+          "morph button"
+        ],
+        "pairsWith": [
+          "motion-icon-swap"
+        ]
+      },
       {
         "name": "motion-spin",
         "kind": "utility",
@@ -24785,6 +27197,7 @@
         "label",
         "legend",
         "locale",
+        "motion",
         "onActiveIndexChange",
         "series",
         "stacked",
@@ -24889,6 +27302,7 @@
         "labels",
         "legend",
         "locale",
+        "motion",
         "negativeTone",
         "onActiveIndexChange",
         "orientation",
@@ -24983,6 +27397,7 @@
         "modifiersClassNames",
         "modifiersStyles",
         "month",
+        "motion",
         "navLayout",
         "nonce",
         "noonSafe",
@@ -25070,6 +27485,7 @@
         "index",
         "label",
         "loop",
+        "motion",
         "onIndexChange",
         "slideClassName",
         "slidesToShow"
@@ -25089,6 +27505,7 @@
         "invalid",
         "label",
         "leading",
+        "motion",
         "onAttach",
         "onSend",
         "onStop",
@@ -25108,6 +27525,7 @@
         "id",
         "indeterminate",
         "inputRef",
+        "motion",
         "name",
         "nativeButton",
         "onCheckedChange",
@@ -25130,6 +27548,7 @@
         "id",
         "indeterminate",
         "inputRef",
+        "motion",
         "name",
         "nativeButton",
         "onCheckedChange",
@@ -25390,6 +27809,21 @@
         "shortcut",
         "size"
       ],
+      "ConfirmButton": [
+        "badge",
+        "bleed",
+        "children",
+        "confirmHint",
+        "confirmLabel",
+        "confirmVariant",
+        "icon",
+        "iconEnd",
+        "motion",
+        "onConfirm",
+        "size",
+        "timeout",
+        "variant"
+      ],
       "ContextCard": [
         "actionsRef",
         "children",
@@ -25686,10 +28120,12 @@
       "Feedback": [
         "heading",
         "label",
+        "motion",
         "onSubmit",
         "placeholder",
         "ratings",
-        "submitLabel"
+        "submitLabel",
+        "successMessage"
       ],
       "Field": [
         "children",
@@ -25841,6 +28277,7 @@
         "labels",
         "legend",
         "locale",
+        "motion",
         "onActiveIndexChange",
         "series",
         "tooltip",
@@ -26146,6 +28583,10 @@
         "policy",
         "target"
       ],
+      "MotionScope": [
+        "children",
+        "level"
+      ],
       "NavigationMenu": [
         "actionsRef",
         "align",
@@ -26202,6 +28643,7 @@
         "count",
         "dot",
         "max",
+        "motion",
         "overlay",
         "size",
         "tone"
@@ -26232,6 +28674,15 @@
         "style",
         "value"
       ],
+      "NumberTicker": [
+        "format",
+        "locales",
+        "motion",
+        "prefix",
+        "suffix",
+        "trend",
+        "value"
+      ],
       "OtpField": [
         "aria-invalid",
         "autoComplete",
@@ -26246,6 +28697,7 @@
         "inputMode",
         "length",
         "mask",
+        "motion",
         "name",
         "normalizeValue",
         "onValueChange",
@@ -26333,6 +28785,7 @@
         "labels",
         "legend",
         "locale",
+        "motion",
         "onActiveIndexChange",
         "separator",
         "tooltip",
@@ -26489,6 +28942,7 @@
         "label",
         "legend",
         "locale",
+        "motion",
         "onActiveIndexChange",
         "radiusAxis",
         "series",
@@ -26509,6 +28963,7 @@
         "legend",
         "locale",
         "max",
+        "motion",
         "onActiveIndexChange",
         "stacked",
         "sweep",
@@ -26833,6 +29288,7 @@
       "Sidebar": [
         "collapsed",
         "icons",
+        "motion",
         "surface",
         "variant"
       ],
@@ -26850,6 +29306,7 @@
       ],
       "SideNav": [
         "activeVariant",
+        "motion",
         "size"
       ],
       "SideNavGroup": [
@@ -26975,6 +29432,7 @@
         "data",
         "label",
         "locale",
+        "motion",
         "tone",
         "variant"
       ],
@@ -27050,6 +29508,7 @@
       "Tabs": [
         "className",
         "defaultValue",
+        "motion",
         "onValueChange",
         "orientation",
         "render",
@@ -27114,6 +29573,7 @@
       ],
       "ThemeSwitcher": [
         "label",
+        "motion",
         "onValueChange",
         "value"
       ],
@@ -27191,6 +29651,7 @@
         "defaultValue",
         "disabled",
         "loopFocus",
+        "motion",
         "multiple",
         "onValueChange",
         "orientation",
@@ -27254,6 +29715,19 @@
         "render",
         "style"
       ],
+      "ToolCall": [
+        "children",
+        "defaultOpen",
+        "error",
+        "input",
+        "name",
+        "onOpenChange",
+        "open",
+        "output",
+        "status",
+        "statusLabel",
+        "title"
+      ],
       "Tooltip": [
         "actionsRef",
         "children",
@@ -27281,6 +29755,10 @@
         "sideOffset",
         "style"
       ],
+      "TooltipGroup": [
+        "children",
+        "motion"
+      ],
       "TooltipPortal": [
         "className",
         "container",
@@ -27305,6 +29783,9 @@
         "render",
         "style"
       ],
+      "Tree": [
+        "motion"
+      ],
       "TreeAddRow": [
         "depth",
         "icon",
@@ -27449,19 +29930,19 @@
       },
       {
         "name": "MotionProvider",
-        "summary": "Holds the app's motion policy and writes it as `data-motion` on <html>, which drives the `--motion-scale` switch every Sable motion recipe reads. Lets an app offer its own reduce-motion setting.",
+        "summary": "Holds the app's motion policy and writes it as `data-motion` on <html>, which drives the `--motion-scale` and `--motion-expressive` switches every Sable motion recipe reads. Lets an app offer its own motion setting: full, subtle (feedback without flourishes) or off.",
         "required": "Optional. Without it, motion follows the visitor's OS `prefers-reduced-motion` setting, and useMotion() still works (its setPolicy does nothing).",
         "placement": "Once, at the app root, when the app has an in-app motion setting.",
         "props": [
           {
             "name": "defaultPolicy",
-            "type": "\"system\" | \"full\" | \"reduced\" | \"off\"",
+            "type": "\"system\" | \"full\" | \"subtle\" | \"reduced\" | \"off\"",
             "default": "\"system\"",
-            "description": "Initial policy when uncontrolled. \"system\" defers to the OS preference."
+            "description": "Initial policy when uncontrolled. \"system\" defers to the OS preference. \"subtle\" keeps essential motion (feedback, overlays, disclosure, loaders) and drops expressive motion (glides, rolling numbers, drawn ticks, shakes, staggers, overshoot)."
           },
           {
             "name": "policy",
-            "type": "\"system\" | \"full\" | \"reduced\" | \"off\"",
+            "type": "\"system\" | \"full\" | \"subtle\" | \"reduced\" | \"off\"",
             "description": "Controlled policy. Pair with onPolicyChange."
           },
           {
@@ -27478,13 +29959,17 @@
         ],
         "companions": [
           "useMotion",
-          "useReducedMotion"
+          "useMotionLevel",
+          "useReducedMotion",
+          "MotionScope"
         ],
         "notes": [
-          "JavaScript motion must read useMotion().enabled and do nothing when it is false; CSS recipes stop on their own."
+          "JavaScript motion must read useMotion().enabled and do nothing when it is false; JavaScript flourishes read useMotion().expressive, which is also false under \"subtle\". CSS recipes follow on their own.",
+          "Mapping the app's \"full\" choice back to \"system\" keeps honouring the OS reduce-motion preference; \"full\" itself forces motion on."
         ],
         "related": [
-          "Switch"
+          "Switch",
+          "ToggleGroup"
         ],
         "import": "import { MotionProvider } from \"@sableui/react\"",
         "examples": [
@@ -27497,6 +29982,42 @@
             "label": "A reduce-motion setting",
             "code": "function ReduceMotionSetting() {\n\tconst { policy, setPolicy } = useMotion()\n\treturn (\n\t\t<Switch\n\t\t\tchecked={policy === \"reduced\"}\n\t\t\tonCheckedChange={(on) => setPolicy(on ? \"reduced\" : \"system\")}\n\t\t\taria-label=\"Reduce motion\"\n\t\t/>\n\t)\n}",
             "imports": "import { Switch, useMotion } from \"@sableui/react\""
+          },
+          {
+            "label": "A three-way motion setting",
+            "code": "function MotionSetting() {\n\tconst { policy, setPolicy } = useMotion()\n\treturn (\n\t\t<ToggleGroup\n\t\t\tappearance=\"segmented\"\n\t\t\tvalue={[policy === \"system\" ? \"full\" : policy]}\n\t\t\tonValueChange={(next) => next[0] && setPolicy(next[0] === \"full\" ? \"system\" : (next[0] as \"subtle\" | \"off\"))}\n\t\t\taria-label=\"Motion\"\n\t\t>\n\t\t\t<Toggle value=\"full\">Full</Toggle>\n\t\t\t<Toggle value=\"subtle\">Subtle</Toggle>\n\t\t\t<Toggle value=\"off\">Off</Toggle>\n\t\t</ToggleGroup>\n\t)\n}",
+            "imports": "import { Toggle, ToggleGroup, useMotion } from \"@sableui/react\""
+          }
+        ]
+      },
+      {
+        "name": "MotionScope",
+        "summary": "Turns motion down for one region — a dense data view, an embedded widget, a screen a test captures — by writing `data-motion` on a box-less wrapper and passing the same level to useMotion() below it.",
+        "required": "Optional. Reach for it when a whole region should be calmer than the app; for one component, use that component's `motion` prop.",
+        "placement": "Around the region. It renders a `display: contents` element, so it adds no box to the layout.",
+        "props": [
+          {
+            "name": "level",
+            "type": "\"subtle\" | \"off\"",
+            "description": "\"subtle\" keeps feedback, overlays, disclosure and loaders and drops glides, rolling numbers, drawn ticks, shakes and staggers. \"off\" stills everything. A scope can only turn motion down."
+          }
+        ],
+        "companions": [
+          "useMotionLevel",
+          "MotionProvider"
+        ],
+        "notes": [
+          "Overlays portal out of the DOM subtree, so their CSS follows the app-level policy; set it on MotionProvider to cover them too."
+        ],
+        "related": [
+          "MotionProvider"
+        ],
+        "import": "import { MotionScope } from \"@sableui/react\"",
+        "examples": [
+          {
+            "label": "A calm data view",
+            "code": "export function Dashboard({ children }: { children: ReactNode }) {\n\treturn <MotionScope level=\"subtle\">{children}</MotionScope>\n}",
+            "imports": "import type { ReactNode } from \"react\"\nimport { MotionScope } from \"@sableui/react\""
           }
         ]
       },