@sableui/react 0.13.1 → 0.14.0

package/dist/styles.css

@@ -1201,7 +1201,8 @@
    drops the hiding rule entirely and the action simply stays visible. */
 @utility reveal-on-hover {
 	transition-property: color, background-color, border-color, box-shadow,
-		opacity, fill, stroke, scale, translate;
+		opacity, fill, stroke, scale, translate, rotate, outline-color, outline-width,
+		outline-offset;
 	transition-duration: var(--motion-duration-fast);
 	transition-timing-function: var(--motion-ease-standard);
 
@@ -1844,8 +1845,18 @@
       collapse --motion-scale to 0 — one switch makes all token-driven motion
       static (transitions resolve instantly; loaders hold their first frame).
 
-   Keep motion subtle: opacity + transform only (compositor-friendly), short
-   durations, no spring/overshoot. See DESIGN.md → Motion.
+   Two LEVELS sit under the switch. ESSENTIAL motion answers the user: colour
+   and focus feedback, press, overlay arrival, disclosure height, loaders.
+   EXPRESSIVE motion narrates continuity: an indicator that travels between
+   options (motion-glide), digits that roll (NumberTicker), a tick that draws
+   (motion-tick), a shake on a wrong answer (motion-shake), staggered arrivals
+   and spring overshoot. Expressive durations are multiplied by a second
+   factor, --motion-expressive, which `data-motion="subtle"` sets to 0 (and
+   which also takes the overshoot out of ease-spring/ease-bounce). So "subtle"
+   keeps every answer and drops every flourish; "off" drops both.
+
+   Opacity + transform only (compositor-friendly), short durations, overshoot on
+   enter only. See DESIGN.md → Motion.
    ========================================================================== */
 
 @keyframes sable-spin {
@@ -2009,10 +2020,22 @@
    `motion-press` and the hover/active surface — the flash is a second, worse
    answer. Both are inert on pointer devices, and neither is motion, so
    --motion-scale: 0 and prefers-reduced-motion leave them untouched: the delay
-   fix keeps working when animation is off, which is when it matters most. */
+   fix keeps working when animation is off, which is when it matters most.
+
+   `rotate` is in the list because Tailwind v4's `rotate-*` utilities write the
+   standalone `rotate` property, not `transform`. Without it every disclosure
+   chevron carrying this recipe (Accordion, Collapsible, Tree) jumped 180° in a
+   single frame while the panel beside it eased open.
+
+   The outline properties are there for focus rings drawn with `outline-*`
+   (the box-shadow `ring-*` ones were already covered). An outline's computed
+   width is 0 while its style is `none`, so on focus the ring grows from the
+   element's edge to its full width at the fast step instead of appearing in
+   one frame; on blur it shrinks back. Under reduced motion it is instant. */
 @utility motion-interactive {
 	transition-property: color, background-color, border-color, box-shadow,
-		opacity, fill, stroke, scale, translate;
+		opacity, fill, stroke, scale, translate, rotate, outline-color, outline-width,
+		outline-offset;
 	transition-duration: var(--motion-duration-fast);
 	transition-timing-function: var(--motion-ease-standard);
 	touch-action: manipulation;
@@ -2196,6 +2219,262 @@
 	}
 }
 
+/* --------------------------------------------------------------------------
+   Expressive recipes — continuity and choreography. Each duration is a token
+   multiplied by --motion-expressive, so `data-motion="subtle"` resolves them
+   instantly while the essential recipes above keep answering. Under the
+   off/reduced policy the token itself is already 0.
+   -------------------------------------------------------------------------- */
+
+/* Glide — ONE element that travels to the selected option, instead of each
+   option blinking its own fill: a tab's underline or pill, a segmented thumb,
+   a carousel's active dot, a nav's current-page bar. The component positions it
+   (Base UI's --active-tab-* vars, a measured box, or an index step); this
+   recipe carries the timing.
+
+   Width and height are in the list on purpose. The glider is absolutely
+   positioned, so resizing it lays out nothing else, and a pill that stretches
+   to its new option's label width cannot be a scale without distorting its
+   corners. Emphasized easing: it leaves quickly and settles, which is what
+   reads as "one thing moved" rather than "two things swapped". */
+@utility motion-glide {
+	transition-property: translate, width, height, inset, left, top, opacity, background-color;
+	/* The travel is expressive; the glider fading in or out and its colour
+	   answering a hover are essential, so "subtle" keeps those. One duration
+	   per property — a shorter list repeats from the start. */
+	transition-duration:
+		calc(var(--motion-duration-slow) * var(--motion-expressive, 1)),
+		calc(var(--motion-duration-slow) * var(--motion-expressive, 1)),
+		calc(var(--motion-duration-slow) * var(--motion-expressive, 1)),
+		calc(var(--motion-duration-slow) * var(--motion-expressive, 1)),
+		calc(var(--motion-duration-slow) * var(--motion-expressive, 1)),
+		calc(var(--motion-duration-slow) * var(--motion-expressive, 1)),
+		var(--motion-duration-fast),
+		var(--motion-duration-fast);
+	transition-timing-function: var(--motion-ease-emphasized), var(--motion-ease-emphasized),
+		var(--motion-ease-emphasized), var(--motion-ease-emphasized), var(--motion-ease-emphasized),
+		var(--motion-ease-emphasized), var(--motion-ease-standard), var(--motion-ease-standard);
+}
+
+/* Shake — a short horizontal no, for an answer that was refused: a wrong
+   one-time code, a submit with invalid fields. Plays while `data-shake` is set;
+   `useShake()` (src/motion) sets it, clears it on animationend, and restarts it
+   when the next refusal lands mid-shake. Decaying amplitude, about a fifth of a
+   second per swing — anything longer reads as a tantrum.
+
+   Never the only signal. The field turns destructive and says why; the shake
+   is what makes a repeated mistake feel noticed. Under "subtle" the duration
+   is 0 and only the colour remains. */
+@keyframes sable-shake {
+	0%,
+	100% {
+		translate: 0 0;
+	}
+	20% {
+		translate: -0.375rem 0;
+	}
+	40% {
+		translate: 0.3rem 0;
+	}
+	60% {
+		translate: -0.2rem 0;
+	}
+	80% {
+		translate: 0.1rem 0;
+	}
+}
+@utility motion-shake {
+	&[data-shake] {
+		animation: sable-shake calc(var(--motion-duration-slower) * 0.8 * var(--motion-expressive, 1))
+			var(--motion-ease-standard);
+	}
+}
+
+/* Tick — a selection mark that draws itself in rather than appearing: the
+   check in a Checkbox, a success glyph. The mark wipes in from its leading
+   stroke (clip-path, so it works on any injected icon set — a path-length draw
+   would need to own the SVG) while its opacity takes the essential fade.
+   Keyed to Base UI's starting/ending style like the overlay recipes; exits only
+   fade, at the exit speed, so un-checking is not a performance.
+
+   Two durations: the fade is essential (fast), the wipe is expressive, so
+   "subtle" keeps a clean fade and drops the draw. */
+@utility motion-tick {
+	/* Both ends of the wipe must be inset() so they interpolate: from the
+	   default `none` the clip-path flipped in one frame and only the fade and
+	   scale played. Outset by 2px so the resting clip never shaves an injected
+	   glyph's round caps. */
+	clip-path: inset(-2px);
+	transition-property: opacity, clip-path, scale;
+	transition-duration: var(--motion-duration-fast),
+		calc(var(--motion-duration-base) * var(--motion-expressive, 1)),
+		calc(var(--motion-duration-base) * var(--motion-expressive, 1));
+	transition-timing-function: var(--motion-ease-standard), var(--motion-ease-decelerate),
+		var(--motion-ease-spring);
+	&[data-starting-style] {
+		opacity: 0;
+		clip-path: inset(-2px 100% -2px -2px);
+		scale: 0.6;
+	}
+	&[data-ending-style] {
+		opacity: 0;
+		transition-duration: var(--motion-duration-exit), 0s, 0s;
+	}
+}
+
+/* Appear — a small control that mounts in place and should not pop into
+   existence: a search field's clear button, a send button replacing a mic, a
+   count badge. Uses @starting-style, so it needs no data attribute and no JS;
+   the element simply transitions in from its starting style on first render.
+   The fade is essential, the scale is expressive. Removal is instant — an
+   unmounted element has nothing to animate, and a control leaving should get
+   out of the way. It declares its own transition-property, so put it on a
+   WRAPPER around a Button or anything carrying motion-interactive — on the
+   same element one of the two lists would silently win. */
+@utility motion-appear {
+	transition-property: opacity, scale;
+	transition-duration: var(--motion-duration-fast),
+		calc(var(--motion-duration-base) * var(--motion-expressive, 1));
+	transition-timing-function: var(--motion-ease-standard), var(--motion-ease-spring);
+	@starting-style {
+		opacity: 0;
+		scale: 0.6;
+	}
+}
+
+/* Arrive — items that a user action brings into a list settle into place one
+   after another, so the eye can follow where they came from: a tree folder's
+   children on expand, results that load in, a row that was just added.
+   A CSS animation rather than a transition, so it composes with the
+   motion-interactive every row already carries. Set the item's stagger as a
+   raw delay in --motion-arrive-delay (index x ~18ms, capped around ten items so
+   a long list settles as fast as a short one); the recipe scales it, so
+   "subtle" and reduced motion show the items at once with no dead wait.
+   `backwards` holds the start pose through the delay and then lets go, so a
+   later opacity (a dimmed row) is never pinned.
+
+   Only on a user action. A list that arrives this way every time it renders is
+   a title sequence: mount the class only on items that are new. */
+@keyframes sable-arrive {
+	from {
+		opacity: 0;
+		translate: 0 -0.25rem;
+	}
+}
+@utility motion-arrive {
+	animation: sable-arrive calc(var(--motion-duration-base) * var(--motion-expressive, 1))
+		var(--motion-ease-decelerate)
+		calc(var(--motion-arrive-delay, 0ms) * var(--motion-scale, 1) * var(--motion-expressive, 1))
+		backwards;
+}
+
+/* Calendar month paging — react-day-picker's `animate` mode, which Calendar
+   turns on only while motion is expressive. RDP keeps the outgoing month as a
+   snapshot laid over the incoming one and adds ONE class to each part (so
+   these are plain classes, not utilities: a class list would not survive
+   classList.add). The months trade places over a short travel with a fade,
+   not RDP's default full-width slide, which drags a whole grid across the
+   card. Enter at the slow step on the emphasized curve; exit at the exit step,
+   so the old month is out of the way before the new one settles.
+
+   Naming follows RDP: "after" means the month that arrives is AFTER the one
+   leaving (paging forward), so it comes in from the end and the old one leaves
+   toward the start. Mirrored under [dir=rtl]. */
+@keyframes sable-month-from-start {
+	from {
+		opacity: 0;
+		translate: -1.5rem 0;
+	}
+}
+@keyframes sable-month-from-end {
+	from {
+		opacity: 0;
+		translate: 1.5rem 0;
+	}
+}
+@keyframes sable-month-to-start {
+	to {
+		opacity: 0;
+		translate: -1.5rem 0;
+	}
+}
+@keyframes sable-month-to-end {
+	to {
+		opacity: 0;
+		translate: 1.5rem 0;
+	}
+}
+@keyframes sable-fade-out {
+	to {
+		opacity: 0;
+	}
+}
+.sable-month-enter-after,
+.sable-month-enter-before {
+	animation: sable-month-from-end calc(var(--motion-duration-slow) * var(--motion-expressive, 1))
+		var(--motion-ease-emphasized) both;
+}
+.sable-month-enter-before,
+[dir="rtl"] .sable-month-enter-after {
+	animation-name: sable-month-from-start;
+}
+[dir="rtl"] .sable-month-enter-before {
+	animation-name: sable-month-from-end;
+}
+.sable-month-exit-after,
+.sable-month-exit-before {
+	animation: sable-month-to-start calc(var(--motion-duration-exit) * var(--motion-expressive, 1))
+		var(--motion-ease-standard) both;
+}
+.sable-month-exit-after,
+[dir="rtl"] .sable-month-exit-before {
+	animation-name: sable-month-to-end;
+}
+[dir="rtl"] .sable-month-exit-after {
+	animation-name: sable-month-to-start;
+}
+.sable-caption-enter {
+	animation: sable-fade-in calc(var(--motion-duration-slow) * var(--motion-expressive, 1))
+		var(--motion-ease-decelerate) both;
+}
+.sable-caption-exit {
+	animation: sable-fade-out calc(var(--motion-duration-exit) * var(--motion-expressive, 1))
+		var(--motion-ease-standard) both;
+}
+
+/* Size — eases an element between sizes: a button whose label changes
+   ("Delete" → "Confirm delete?"), a chip that gains a count, a panel going from
+   0 to its natural height.
+
+   A transition needs the computed size to CHANGE. Between a keyword and a
+   length (0 ↔ auto) `interpolate-size: allow-keywords` supplies that. A
+   content-sized box whose content changes computes `auto` both times, so pair
+   the recipe with `useAutoSize()` (src/motion), which writes the content's
+   measured size as pixels for this transition to ease between. Where
+   interpolate-size is unsupported the keyword case simply snaps, which is the
+   old behaviour. Expressive: under "subtle" the size snaps and the label still
+   changes. */
+@utility motion-size {
+	interpolate-size: allow-keywords;
+	/* A superset of motion-interactive's list, in the same order after the two
+	   sizes, so it can sit on a Button (which carries motion-interactive) and
+	   whichever declaration wins the cascade, nothing the other animated stops
+	   animating. Only the two sizes are expressive. */
+	transition-property: width, height, color, background-color, border-color, box-shadow,
+		opacity, fill, stroke, scale, translate, rotate, outline-color, outline-width,
+		outline-offset;
+	/* One entry per property: a shorter list would REPEAT from the start. */
+	transition-duration: calc(var(--motion-duration-base) * var(--motion-expressive, 1)),
+		calc(var(--motion-duration-base) * var(--motion-expressive, 1)),
+		var(--motion-duration-fast), var(--motion-duration-fast), var(--motion-duration-fast), var(--motion-duration-fast), var(--motion-duration-fast),
+		var(--motion-duration-fast), var(--motion-duration-fast), var(--motion-duration-fast), var(--motion-duration-fast), var(--motion-duration-fast),
+		var(--motion-duration-fast), var(--motion-duration-fast), var(--motion-duration-fast);
+	transition-timing-function: var(--motion-ease-emphasized), var(--motion-ease-emphasized),
+		var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-standard),
+		var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-standard),
+		var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-standard);
+}
+
 /* --------------------------------------------------------------------------
    Loader recipes — looping indicators. Durations scale with --motion-scale, so
    the policy switch freezes them to a static first frame.
@@ -2459,3 +2738,17 @@
 [data-motion="off"] [data-sable-theme] {
 	--motion-scale: 0 !important;
 }
+
+/* "subtle": essential motion plays, expressive motion resolves instantly and
+   nothing overshoots. It never touches --motion-scale, so it can only turn
+   motion DOWN: nested inside "off", or under the OS reduce preference, the
+   scale is still 0. That is what makes it safe as a per-component prop and on
+   <MotionScope> — neither can switch motion back on for a reader who asked for
+   it off. The easings are re-pointed rather than zeroed: a spring pop becomes a
+   clean decelerate, which is still an answer. */
+[data-motion="subtle"],
+[data-motion="subtle"] [data-sable-theme] {
+	--motion-expressive: 0 !important;
+	--motion-ease-spring: var(--motion-ease-decelerate) !important;
+	--motion-ease-bounce: var(--motion-ease-decelerate) !important;
+}

package/llms/blocks/approval-block.md

@@ -0,0 +1,128 @@
+# ApprovalBlock
+
+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.
+
+**Block:** AI & agents · card · designed for 18rem–28rem wide (fills its container up to the max)
+
+## 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.
+
+## Accessibility
+
+- 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.
+
+## Source
+
+```tsx
+import { useState, useEffect, useRef, useId } from "react"
+import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, cn, Code, InlineStatus, Label } from "@sableui/react"
+
+const request = {
+	tool: "send_email",
+	title: "Send the invoice to Ada?",
+	description: "The agent wants to email invoice INV-1042. An email can't be unsent.",
+	details: [
+		{ label: "To", value: "ada@example.com" },
+		{ label: "Subject", value: "INV-1042 for October" },
+		{ label: "Attached", value: "INV-1042.pdf" },
+	],
+	allowed: "Allowed. Sending the email.",
+	denied: "Denied. The agent won't send it.",
+}
+
+export interface ApprovalBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a chat column that already frames it. */
+	framed?: boolean
+	/** The person allowed the call. `remember` is the "for the rest of this chat" choice. */
+	onApprove?: (options: { remember: boolean }) => void
+	/** The person declined the call. */
+	onDeny?: () => void
+}
+
+export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: ApprovalBlockProps) {
+	const [decision, setDecision] = useState<"allowed" | "denied" | null>(null)
+	const [remember, setRemember] = useState(false)
+	const id = useId()
+	const outcome = useRef<HTMLDivElement>(null)
+	// The buttons leave with the decision, so focus moves to the line that
+	// replaces them instead of falling back to the top of the page.
+	useEffect(() => {
+		if (decision) outcome.current?.focus()
+	}, [decision])
+
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-md", className)}>
+			<CardHeader>
+				<CardTitle>{request.title}</CardTitle>
+				<CardDescription>{request.description}</CardDescription>
+			</CardHeader>
+			<CardContent className="flex flex-col gap-4">
+				<dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1.5 text-body-sm">
+					{request.details.map((d) => (
+						<div key={d.label} className="contents">
+							<dt className="text-muted-foreground">{d.label}</dt>
+							<dd className="truncate text-foreground">{d.value}</dd>
+						</div>
+					))}
+					<div className="contents">
+						<dt className="text-muted-foreground">Tool</dt>
+						<dd className="min-w-0">
+							<Code>{request.tool}</Code>
+						</dd>
+					</div>
+				</dl>
+				{decision ? null : (
+					<div className="flex items-center gap-2">
+						<Checkbox id={`${id}-remember`} checked={remember} onCheckedChange={(v: boolean) => setRemember(v)} />
+						<Label htmlFor={`${id}-remember`} className="text-body-sm">
+							Allow <Code>{request.tool}</Code> for the rest of this chat
+						</Label>
+					</div>
+				)}
+			</CardContent>
+			<CardFooter actions className="justify-end">
+				{decision ? (
+					<InlineStatus
+						ref={outcome}
+						tabIndex={-1}
+						role="status"
+						tone={decision === "allowed" ? "success" : "neutral"}
+						className="me-auto outline-none"
+					>
+						{decision === "allowed" ? request.allowed : request.denied}
+					</InlineStatus>
+				) : (
+					<>
+						<Button
+							variant="outline"
+							onClick={() => {
+								setDecision("denied")
+								onDeny?.()
+							}}
+						>
+							Deny
+						</Button>
+						<Button
+							onClick={() => {
+								setDecision("allowed")
+								onApprove?.({ remember })
+							}}
+						>
+							Allow
+						</Button>
+					</>
+				)}
+			</CardFooter>
+		</Card>
+	)
+}
+```

package/llms/components/accordion.md

@@ -15,7 +15,7 @@ Use Accordion to reveal a vertical set of related sections while keeping the sur
 - Do: Use concise trigger text that describes the content revealed below it.
 - Do: Keep section content focused so expanding one item does not feel like navigating to a new page.
 - Don't: Do not hide required fields, primary actions, or critical errors inside collapsed sections.
-- Don't: 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.
+- Don't: 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. → use **Tree**
 
 ### Anatomy
 
@@ -52,6 +52,7 @@ Use Accordion to reveal a vertical set of related sections while keeping the sur
 - **arrival** · Root · _no motion_ — An accordion is page furniture that is present from first paint. Animating it in would stage content the reader is already scanning past.
 - **response** · AccordionTrigger · `motion-interactive` — The whole header row is the hit target, and it looks like a heading rather than a control. The hover shift is what tells the reader it can be clicked before they click it.
 - **transition** · AccordionPanel · `motion-disclosure` — 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.
+- **transition** · Chevron · `motion-interactive` — 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.
 - **activity** · Root · _no motion_ — Nothing here is indeterminate — the panel content is already resident. A panel that loads on expand should put its own loader inside the panel.
 
 ## Accessibility
@@ -60,7 +61,7 @@ Use Accordion to reveal a vertical set of related sections while keeping the sur
 - 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.
 
 ## Related
 
@@ -89,5 +90,5 @@ import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger } from "@sab
 ```tsx
 import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, Icon } from "@sableui/react"
 
-<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>
+<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>
 ```

package/llms/components/area-chart.md

@@ -34,7 +34,8 @@ Use AreaChart for volume over time — visitors, revenue, usage — where the fi
 | grid | boolean | true (false for horizontal bars) | Hairline gridlines along the value axis. |
 | xAxis | boolean | true for columns; false for horizontal bars | The horizontal axis. |
 | yAxis | boolean | false for columns; true for horizontal bars | The vertical axis. |
-| animate | boolean | true | Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. |
+| motion | "full" \| "subtle" \| "off" | "full" | 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. |
+| animate | boolean | true | Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. `animate={false}` is `motion="subtle"`. |
 | activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
 | defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
 | onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
@@ -48,9 +49,9 @@ Use AreaChart for volume over time — visitors, revenue, usage — where the fi
 
 ## Motion
 
-- **arrival** · Area + line · _custom (outside the recipe layer)_ — 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.
+- **arrival** · Area + line · _custom (outside the recipe layer)_ — 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.
 - **response** · Cursor + tooltip · _no motion_ — Hover and focus move the cursor and tooltip instantly — a lagging cursor reads as a slow chart.
-- **transition** · Area + line · _custom (outside the recipe layer)_ — 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.
+- **transition** · Area + line · _custom (outside the recipe layer)_ — 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.
 - **activity** · AreaChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
 
 ## Accessibility

package/llms/components/attachment.md

@@ -54,6 +54,13 @@ The card a file takes in a conversation — in the composer while it uploads, an
 
 `card`, `border`, `border-strong`, `muted`, `muted-foreground`, `foreground`, `destructive`, `overlay`, `overlay-foreground`, `ring`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · Root · `motion-interactive` — 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.
+- **transition** · Root · `motion-interactive` — 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.
+- **activity** · Progress · `motion-pulse` — 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.
+
 ## Accessibility
 
 - 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.

package/llms/components/badge.md

@@ -16,7 +16,7 @@ Use Badge for any short static label: metadata, categories, tone-coded labels, a
 - Do: Use tone variants when the badge carries meaning, such as success, warning or destructive, or a decorative tone for a category or plan.
 - Do: Pair icons with text; the icon reinforces meaning but should not be the only cue.
 - Do: Choose appearance and tone separately: appearance is how loud it is (soft by default, solid for emphasis, overlay on images, plain for a status line); tone is what it means.
-- Don't: Use a Badge as a button. If it triggers an action, use Button, Toggle, or a menu item.
+- Don't: Use a Badge as a button. If it triggers an action, use Button, Toggle, or a menu item. → use **Button**, **Toggle**
 - Don't: Stack many loud tone badges in one row; too many semantic colors compete with the actual content.
 
 ### Anatomy

package/llms/components/banner.md

@@ -16,8 +16,8 @@ Use Banner for page-level or app-level messages that affect the current experien
 - Do: Set live='polite' or live='assertive' only when the banner appears or changes dynamically.
 - Do: Include one clear action when the user can resolve or inspect the state.
 - Don't: Use multiple stacked solid banners unless the page is genuinely blocked by multiple independent states.
-- Don't: Use Banner for field-level validation, row status, or small local hints; use Field, InlineStatus, or Badge instead.
-- Don't: 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.
+- Don't: Use Banner for field-level validation, row status, or small local hints; use Field, InlineStatus, or Badge instead. → use **InlineStatus**, **Badge**
+- Don't: 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. → use **Note**
 
 ### Anatomy
 

package/llms/components/bar-chart.md

@@ -34,7 +34,8 @@ Use BarChart to compare amounts across categories — the default chart for "how
 | grid | boolean | true (false for horizontal bars) | Hairline gridlines along the value axis. |
 | xAxis | boolean | true for columns; false for horizontal bars | The horizontal axis. |
 | yAxis | boolean | false for columns; true for horizontal bars | The vertical axis. |
-| animate | boolean | true | Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. |
+| motion | "full" \| "subtle" \| "off" | "full" | 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. |
+| animate | boolean | true | Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. `animate={false}` is `motion="subtle"`. |
 | activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
 | defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
 | onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
@@ -52,9 +53,9 @@ Use BarChart to compare amounts across categories — the default chart for "how
 
 ## Motion
 
-- **arrival** · Bar · _custom (outside the recipe layer)_ — 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.
-- **response** · Cursor + tooltip · _no motion_ — The hovered category gets a band behind it and the other bars dim at once — a lagging highlight reads as a slow chart.
-- **transition** · Bar · _custom (outside the recipe layer)_ — 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.
+- **arrival** · Bar · _custom (outside the recipe layer)_ — 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.
+- **response** · Cursor + tooltip · _no motion_ — 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.
+- **transition** · Bar · _custom (outside the recipe layer)_ — 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.
 - **activity** · BarChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
 
 ## Accessibility

package/llms/components/bottom-nav.md

@@ -34,6 +34,14 @@ Use BottomNav for a small set of top-level mobile destinations that should remai
 
 `background`, `border`, `muted-foreground`, `foreground`, `ring`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · BottomNavItem · `motion-interactive` — 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.
+- **response** · BottomNavItem · `motion-press` — 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.
+- **transition** · BottomNavItem · `motion-interactive` — 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.
+- **activity** · Root · _no motion_ — 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.
+
 ## Accessibility
 
 - BottomNav renders a <nav> landmark.

package/llms/components/breadcrumbs.md

@@ -45,6 +45,13 @@ Use Breadcrumbs to show the user's location inside a hierarchy and provide light
 
 `muted-foreground`, `foreground`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · BreadcrumbLink · `motion-interactive` — 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.
+- **transition** · Root · _no motion_ — 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.
+- **activity** · Root · _no motion_ — It never works in the background. A route that is still loading says so in the page, not in its address.
+
 ## Accessibility
 
 - The <nav> carries aria-label="Breadcrumb" so assistive tech announces the landmark.

package/llms/components/button-group.md

@@ -16,7 +16,7 @@ Use ButtonGroup when one action has close alternatives (Copy page, with Open in
 - Do: For a split button, put the main action first and a Menu whose trigger is the chevron Button second, with an aria-label on the trigger ("More page actions").
 - Do: Name the group with aria-label when the buttons alone do not say what they act on.
 - Don't: Do not round or border the children yourself to make them meet; that is the group's job, and an override breaks under a theme's button shape.
-- Don't: Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state.
+- Don't: Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state. → use **ToggleGroup**
 
 ## Props