@sableui/react 0.13.2 → 0.15.0

package/llms/components/confirm-button.md

@@ -0,0 +1,92 @@
+# ConfirmButton
+
+**Status:** stable
+
+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
+
+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.
+
+### Best practices
+
+- Do: 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.
+- Do: 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.
+- Do: 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.
+- Don't: 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. → use **DestructiveActionModal**
+- Don't: 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. → use **Toast**
+- Don't: 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. → use **Button**
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| children | ReactNode | — | The idle label — the action, e.g. "Delete". |
+| confirmLabel | ReactNode | "Confirm <label>?" | The label while armed. Defaults to "Confirm delete?" for a text label "Delete" (first letter lowered) and "Confirm?" otherwise. Pass it to localise. |
+| onConfirm | () => unknown | — | Runs on the second press while armed. Return a promise to hold the button armed with a spinner until it settles. |
+| timeout | number | 3000 | How long it waits for the second press, in ms. A decision time, so it is not scaled by motion settings. |
+| variant | ButtonVariant | "secondary" | The idle look — any Button variant. |
+| confirmVariant | ButtonVariant | "destructive" | The armed look — any Button variant. |
+| size | "xs" \| "sm" \| "md" \| "cta" | "md" | A labelled Button size. Icon-only sizes are excluded: the label is the interaction. |
+| icon | ReactNode | — | A leading icon kept through both states, e.g. `<Icon name="trash" />`. |
+| disabled | boolean | false | Disables it; disabling while armed also disarms. |
+| confirmHint | string | "Press again to confirm." | Read to assistive tech after the armed label when it arms. Override to localise. |
+| 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 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
+
+## Tokens used
+
+`secondary`, `secondary-foreground`, `destructive`, `destructive-foreground`, `ring`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — It is a button in a row of actions, and arrives with that row. Its moment is the arming, not the mount.
+- **response** · Root · `motion-press` — 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.
+- **transition** · Root · `motion-size` — 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.
+- **activity** · Countdown · _custom (outside the recipe layer)_ — 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.
+
+## Accessibility
+
+- 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.
+
+## Related
+
+- Components: Button, DestructiveActionModal, Toast, OverflowMenu
+
+## Examples
+
+### Delete a row
+
+```tsx
+import { ConfirmButton, Icon } from "@sableui/react"
+
+<ConfirmButton icon={<Icon name="trash" />} onConfirm={() => removeRow(id)}>Delete</ConfirmButton>
+```
+
+### Custom question, longer wait
+
+```tsx
+import { ConfirmButton } from "@sableui/react"
+
+<ConfirmButton variant="ghost" size="sm" confirmLabel="Revoke this key?" timeout={5000} onConfirm={revokeKey}>Revoke</ConfirmButton>
+```
+
+### Async confirm
+
+```tsx
+import { ConfirmButton } from "@sableui/react"
+
+<ConfirmButton onConfirm={() => api.deleteDraft(draft.id)}>Discard draft</ConfirmButton>
+```

package/llms/components/data-table.md

@@ -50,6 +50,14 @@ Use DataTable when a data array and column definition should render a sortable,
 
 `muted-foreground`, `foreground`, `ring`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — Rows render with the page or the query that produced them. Staggering rows in delays reading a table someone opened to scan.
+- **response** · Row · `motion-interactive` — 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.
+- **transition** · Sort chevron · `motion-interactive` — 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.
+- **transition** · Row · `motion-interactive` — 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.
+- **activity** · Root · _no motion_ — 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.
+
 ## Accessibility
 
 - Sorted columns set aria-sort=ascending/descending on the header cell.

package/llms/components/entity.md

@@ -39,6 +39,13 @@ Use Entity to show a compact identity block for a person, organization, file, pr
 
 `accent`, `accent-foreground`, `foreground`, `muted-foreground`, `ring`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · Root · `motion-interactive` — 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.
+- **transition** · Root · `motion-interactive` — `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.
+- **activity** · Root · _no motion_ — A record row has nothing of its own to wait for. A row whose action is pending puts a loading Button in `action`.
+
 ## Accessibility
 
 - Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.

package/llms/components/feedback.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-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.
+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, rating, prompt
 
@@ -26,11 +26,21 @@ Use Feedback to collect lightweight sentiment, usefulness, or quality signals fr
 | placeholder | string | "What can we improve?" | Placeholder for the message field. |
 | submitLabel | string | "Send" | Submit button text. |
 | ratings | FeedbackRating[] | 🙁 / 😐 / 🙂 | The rating options shown as a row of toggles. Each is { value, label }. |
-| onSubmit | (data: { rating?: string; message: string }) => void | — | Called with the selected rating + message when the form is submitted. |
+| onSubmit | (data: { rating?: string; message: string }) => void | — | Called with the selected rating + message when the form is submitted. The thanks shows right away; send the report in the background. |
+| successMessage | string | "Thanks for the feedback." | The line shown, and read out, for about 1.2s after sending, before the popover closes on its own. |
+| 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 drawn check is the flourish; the thanks line and its dwell stay. |
 
 ## Tokens used
 
-`popover`, `popover-foreground`, `border`, `input`, `card`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`, `ring`
+`popover`, `popover-foreground`, `border`, `input`, `card`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`, `ring`, `success`
+
+## Motion
+
+- **arrival** · Popover · `motion-pop` — 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.
+- **response** · Rating toggles · `motion-interactive` — 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.
+- **response** · Chosen rating mark · `motion-bloom` — The mark itself answers the pick: it blooms past its size and settles, so choosing reads as a small decision landing rather than a fill changing. Only the chosen mark, only on choosing — nothing blooms when the form opens or a pick is let go. Expressive: under subtle the fill alone answers.
+- **transition** · Thanks · `motion-tick` — 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.
+- **activity** · Root · _no motion_ — 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.
 
 ## Accessibility
 
@@ -39,6 +49,8 @@ Use Feedback to collect lightweight sentiment, usefulness, or quality signals fr
 - 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.
+- 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.
 
 ## Related
 
@@ -61,3 +73,11 @@ import { Feedback } from "@sableui/react"
 
 <Feedback label="Tell us" submitLabel="Send it" placeholder="Describe the issue…" />
 ```
+
+### Custom thanks
+
+```tsx
+import { Feedback } from "@sableui/react"
+
+<Feedback successMessage="Got it — thank you." onSubmit={({ rating, message }) => report(rating, message)} />
+```

package/llms/components/input-group.md

@@ -32,6 +32,13 @@ Use InputGroup when something belongs inside the field with the text: a unit, a
 
 `input`, `card`, `ring`, `destructive`, `muted-foreground`, `foreground`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — It arrives with the form it belongs to. A field that animated in on its own would be briefly unusable for no stated reason.
+- **response** · Root · `motion-interactive` — 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.
+- **transition** · Root · `motion-interactive` — 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.
+- **activity** · Root · _no motion_ — 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.
+
 ## Accessibility
 
 - The Input stays the focusable control; the group draws the focus ring around the whole field while it is focused.
@@ -66,7 +73,7 @@ import { Field, Icon, Input, InputGroup } from "@sableui/react"
 ```tsx
 import { Button, Field, Icon, Input, InputGroup } from "@sableui/react"
 
-<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>
+<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>
 ```
 
 ### Password with reveal

package/llms/components/like-button.md

@@ -0,0 +1,91 @@
+# LikeButton
+
+**Status:** stable
+
+A pressed-or-not toggle for a like, a star or a save, with its count. Pressing it on fills the glyph, which blooms while a ring and a spray of dots burst from it and the count rolls up; pressing it off is quiet.
+
+**Keywords:** like, heart, favorite, favourite, love, star, bookmark, save, upvote, reaction, count, toggle
+
+## Usage
+
+Use LikeButton for a personal, reversible endorsement that other people can see the tally of: liking a post, starring a repository, saving a recipe. It is the one place in Sable that celebrates, because the person chose it and it costs nothing to undo.
+
+### Best practices
+
+- Do: Pass the server's total as `count` and update it when the save lands. The button shows the viewer's own like at once, before the save, and goes back to `count` exactly whenever it changes, so a failed save that leaves `count` alone can also turn `pressed` back off.
+- Do: Match the glyph, family and label to the meaning: `icon="star" tone="yellow" label="Star"` for a star. The label is the accessible name, so it must say what pressing does.
+- Do: Use `format={{ notation: "compact" }}` once counts pass a few thousand, so a feed of buttons keeps one width.
+- Don't: Do not use it for a setting or a view switch (bold, mute, grid or list). Those are tools, not endorsements, and a burst on every press of a formatting control is noise; use Toggle. → use **Toggle**
+- Don't: Do not use it for a rating or a verdict on an answer (helpful, not helpful). That is a question with two sides; use Feedback. → use **Feedback**
+- Don't: Do not press it for the user. A burst is a reply to a person's choice — liking something on their behalf, or on load, turns delight into a notification.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| count | number | — | The total, rolled when it changes. Pressing adds or removes the viewer's like at once; the button shows `count` exactly again whenever `count` changes. Omit it for a bare glyph (an icon-size button). |
+| pressed | boolean | — | Controlled pressed state. |
+| defaultPressed | boolean | false | Initial pressed state when uncontrolled. |
+| onPressedChange | (pressed: boolean, event) => void | — | Called when the user presses it, with the new state. |
+| icon | string | "heart" | The glyph, by icon name. Its `solid` variant is shown while pressed. |
+| tone | PaletteColor | "red" | The palette family the glyph fills with while pressed, and the burst blooms from. A family, so it follows the theme. |
+| label | string | "Like" | The accessible name, read before the count. |
+| format | Intl.NumberFormatOptions | — | How to write the count, e.g. `{ notation: "compact" }`. |
+| variant | "ghost" \| "outline" \| "secondary" | "ghost" | The Button surface. |
+| size | "xs" \| "sm" \| "md" | "sm" | A Button size; without a count, the matching icon size. |
+| disabled | boolean | false | Disables it. |
+| 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 bloom and the burst are the flourish; the fill and the count changing stay. |
+
+## Variants
+
+- **variant**: ghost, outline, secondary
+- **size**: xs, sm, md
+- **tone**: red, orange, yellow, green, teal, blue, purple, pink
+
+## Tokens used
+
+`palette-dot`, `accent`, `ring`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — It arrives with the post or row it belongs to. A page that loads with likes already given must be still: nothing blooms on mount.
+- **response** · Glyph · `motion-bloom` — Pressing it on is the moment. The glyph is 16px, so it needs real amplitude to read as an event: it grows from nothing past its size and settles, after a 90ms beat in which the ring leads. Inherits Button's motion-press for the press itself. Pressing off has no bloom — taking a like back is not a celebration.
+- **transition** · Burst · _custom (outside the recipe layer)_ — The follow-through: <Burst> draws a disc that hollows into a ring and shifts colour, then dots thrown outward in the theme's palette families. Expressive only — under `subtle` or reduced motion it renders nothing and the fill alone answers the press. The count rolls with NumberTicker.
+- **activity** · Root · _no motion_ — There is no in-between state to show: the like is shown at once, before it is saved.
+
+## Accessibility
+
+- A native <button> through Button, with `aria-pressed`. Enter and Space press it.
+- The accessible name is the label then the count ("Like 1,301"); the burst is aria-hidden and the rolling digits are hidden behind the count's real text.
+- The pressed state is carried by the filled glyph and `aria-pressed`, never by colour alone.
+- Under reduced motion the glyph fills and the count changes at once; the bloom and the burst are dropped.
+
+## Related
+
+- Components: Toggle, Feedback, NumberTicker, Button
+
+## Examples
+
+### A post's likes
+
+```tsx
+import { LikeButton } from "@sableui/react"
+
+<LikeButton count={post.likes} defaultPressed={post.liked} onPressedChange={(on) => api.like(post.id, on)} />
+```
+
+### Star a repository
+
+```tsx
+import { LikeButton } from "@sableui/react"
+
+<LikeButton icon="star" tone="yellow" label="Star" variant="outline" count={repo.stars} format={{ notation: "compact" }} />
+```
+
+### Bare glyph
+
+```tsx
+import { LikeButton } from "@sableui/react"
+
+<LikeButton label="Save recipe" />
+```

package/llms/components/line-chart.md

@@ -34,7 +34,8 @@ Use LineChart to compare how two or more measures change over the same sequence,
 | 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 (lines drawing on) and the data-change morph are the flourish; the gliding cursor, dots 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. |
@@ -49,9 +50,9 @@ Use LineChart to compare how two or more measures change over the same sequence,
 
 ## Motion
 
-- **arrival** · Line · _custom (outside the recipe layer)_ — 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.
+- **arrival** · Line · _custom (outside the recipe layer)_ — 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.
 - **response** · Cursor + tooltip · _no motion_ — Hover and focus move the cursor and tooltip instantly — a lagging cursor reads as a slow chart.
-- **transition** · Line + dots · _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** · Line + dots · _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** · LineChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
 
 ## Accessibility

package/llms/components/middle-truncate.md

@@ -58,5 +58,5 @@ import { MiddleTruncate } from "@sableui/react"
 import { Button, Icon, MiddleTruncate, Row, useCopy } from "@sableui/react"
 
 const { copy, copied } = useCopy(commitHash)
-<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>
+<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>
 ```

package/llms/components/note.md

@@ -37,6 +37,14 @@ Use Note for helpful supporting information that should sit near the relevant co
 
 `foreground`, `border`, `muted`, `muted-foreground`, `tone-info`, `tone-warning`, `success`, `destructive`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · Action · `motion-interactive` — 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.
+- **response** · Action · `motion-press` — A note's action usually navigates or opens something; the small settle on press is the only confirmation before the next surface paints.
+- **transition** · Root · _no motion_ — 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.
+- **activity** · Root · _no motion_ — Static guidance. Work in progress belongs in a Progress or a Spinner, not in a callout.
+
 ## Accessibility
 
 - Rendered with role="note" so assistive tech can announce it as an aside.

package/llms/components/notification-badge.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-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.
+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, count, unread
 
@@ -28,6 +28,7 @@ Use NotificationBadge to show a compact unread count, alert count, or attention
 | tone | "destructive" \| "primary" \| "neutral" | "destructive" | Fill color. destructive for alarming counts; primary/neutral for non-alarming ones. |
 | size | "sm" \| "md" \| "lg" | "md" | Scales the dot/pill on the spacing scale (count pill: sm 16px, md 18px, lg 20px at the default density). |
 | overlay | boolean | false | 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. |
+| 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. Under `subtle` the count updates in place and the badge fades in without the pop. |
 
 ## Variants
 
@@ -39,6 +40,13 @@ Use NotificationBadge to show a compact unread count, alert count, or attention
 
 `destructive`, `destructive-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`
 
+## Motion
+
+- **arrival** · root · `motion-appear` — 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.
+- **response** · root · _no motion_ — It is decorative and not interactive; the host it sits on answers the pointer.
+- **transition** · Count · _custom (outside the recipe layer)_ — 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.
+- **activity** · root · _no motion_ — An unread count has no working state.
+
 ## Accessibility
 
 - 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.
@@ -46,7 +54,7 @@ Use NotificationBadge to show a compact unread count, alert count, or attention
 
 ## Related
 
-- Components: Badge, StatusDot
+- Components: Badge, StatusDot, NumberTicker
 
 ## Examples
 

package/llms/components/number-ticker.md

@@ -0,0 +1,86 @@
+# NumberTicker
+
+**Status:** stable
+
+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
+
+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.
+
+### Best practices
+
+- Do: 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.
+- Do: Format through `format` (currency, percent, compact) rather than pre-formatting a string, so separators and units stay put while only the digits roll.
+- Do: 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.
+- Don't: 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.
+- Don't: 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.
+- Don't: 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).
+- Don't: 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. → use **Meter**
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number | — | The number to show. When it changes, the digits roll to it. |
+| format | Intl.NumberFormatOptions | — | 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). |
+| locales | string \| string[] | runtime locale | BCP 47 locale(s) for the formatting. Digits roll through the locale's own numbering system. |
+| prefix | ReactNode | — | 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. |
+| suffix | ReactNode | — | After the number ("+", " pts"). A string becomes part of the number's text; an element is rendered as given. |
+| trend | "auto" \| "up" \| "down" | "auto" | 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). |
+| 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 roll is expressive, so `subtle` updates the value in place. |
+| className | string | — | 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. |
+| ...span props | Omit<ComponentPropsWithRef<"span">, "children" \| "prefix"> | — | Remaining span attributes pass through to the root — `aria-live` to announce changes, `id`, data attributes. |
+
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · Root · _no motion_ — It is a reading, not a control; the control that changes it gives the feedback.
+- **transition** · Digit · _custom (outside the recipe layer)_ — 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.
+- **activity** · Root · _no motion_ — A number has no working state; show a Skeleton while it loads.
+
+## Accessibility
+
+- 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.
+
+## Related
+
+- Components: Meter, NotificationBadge, PieChart, RadialChart, Sparkline
+
+## Examples
+
+### Basic
+
+```tsx
+import { NumberTicker } from "@sableui/react"
+
+<NumberTicker value={1284} className="text-heading-2" />
+```
+
+### Currency
+
+```tsx
+import { NumberTicker } from "@sableui/react"
+
+<NumberTicker value={4280.5} format={{ style: "currency", currency: "USD" }} className="text-display-lg" />
+```
+
+### Percent, announced
+
+```tsx
+import { NumberTicker } from "@sableui/react"
+
+<NumberTicker value={0.428} format={{ style: "percent", maximumFractionDigits: 1 }} aria-live="polite" />
+```
+
+### Subtle
+
+```tsx
+import { NumberTicker } from "@sableui/react"
+
+<NumberTicker value={92} suffix=" pts" motion="subtle" />
+```

package/llms/components/otp-field.md

@@ -15,6 +15,7 @@ Use OtpField for a short, fixed-length code the user copies from somewhere else
 - Do: Set `length` to the exact length the server sends, and verify in `onValueComplete` (or with `autoSubmit` inside a form). Most users paste or autofill the whole code at once, so the moment of completion is the natural submit.
 - Do: Label it through a `Field` ("Verification code") and say where the code was sent in the description. The first slot takes the field's name; the rest are announced by position.
 - Do: Use `groupSize` for codes of 6 or more so the user can check the code in chunks against the message they are reading from.
+- Do: 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.
 - Don't: 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.
 - Don't: 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.
 - Don't: Do not swap it for NumberField because the code is digits. A code is an identifier, not a quantity: NumberField strips leading zeros and offers steppers that make no sense here.
@@ -41,7 +42,8 @@ Use OtpField for a short, fixed-length code the user copies from somewhere else
 | autoSubmit | boolean | false | Submit the owning form when the code becomes complete. |
 | mask | boolean | false | Render slots as password inputs. Only for codes that are secret on screen, such as a card PIN. |
 | getSlotLabel | (index: number, length: number) => string | Character N of L | Accessible name for slots after the first. Override to localize. |
-| aria-invalid | boolean | — | Marks every slot invalid (destructive border). `<Field error>` sets it for you. |
+| aria-invalid | boolean | — | Marks every slot invalid (destructive border and digits). Turning it on after mount shakes the field once. `<Field error>` sets it for you. |
+| 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 shake is the flourish; the destructive colour stays at every level. |
 | disabled / readOnly / required / name / id / form | — | — | Standard form-control props. `id` lands on the first slot, so `<Field>` and `<label htmlFor>` name the field. |
 
 ## Tokens used
@@ -53,6 +55,7 @@ Use OtpField for a short, fixed-length code the user copies from somewhere else
 - **arrival** · Root · _no motion_ — A code field is part of the form it sits in and appears with it. Animating it in would delay the one thing the user arrived to do — paste the code they just copied.
 - **response** · Slot · `motion-interactive` — Focus moves between slots on every keystroke. The eased ring and border are what let the eye follow the cursor across six identical boxes instead of hunting for it after each digit.
 - **transition** · Slot · `motion-interactive` — 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.
+- **transition** · Root · `motion-shake` — 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.
 - **activity** · Root · _no motion_ — Verifying the code is the form's work, not the field's. Show it on the submit Button's `loading` state, where the user expects the answer to appear.
 
 ## Accessibility
@@ -61,6 +64,7 @@ Use OtpField for a short, fixed-length code the user copies from somewhere else
 - 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.
+- 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`.
 
 ## Related
 
@@ -92,6 +96,16 @@ import { Field, OtpField } from "@sableui/react"
 <Field label="Verification code" error="That code has expired. Request a new code and try again."><OtpField length={6} groupSize={3} defaultValue="482913" /></Field>
 ```
 
+### Verify on completion, shake on a wrong code
+
+```tsx
+import { Field, OtpField } from "@sableui/react"
+
+const [code, setCode] = useState("")
+const [wrong, setWrong] = useState(false)
+<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>
+```
+
 ### Alphanumeric
 
 ```tsx

package/llms/components/panel-group.md

@@ -39,6 +39,13 @@ Use PanelGroup for the body of a tool workspace: fixed-width Panels docked left
 
 `primary`, `panel`, `hairline`, `hairline-strong`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · PanelResizer · `motion-interactive` — 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.
+- **transition** · Panel · _no motion_ — 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.
+- **activity** · Root · _no motion_ — Layout chrome has no working state.
+
 ## Accessibility
 
 - PanelResizer is a role=separator with aria-orientation, aria-valuenow/min/max, and is focusable — a pointer-only resizer is a keyboard trap.

package/llms/components/panel-section.md

@@ -48,6 +48,14 @@ Use PanelSection to group properties inside an inspector or docked panel, with P
 
 `foreground`, `muted-foreground`, `hairline`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · PropertyGroup trigger · `motion-interactive` — 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.
+- **transition** · PropertyGroup panel · `motion-disclosure` — 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.
+- **transition** · PropertyGroup indicator · `motion-icon-swap` — 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.
+- **activity** · Root · _no motion_ — The inspector edits values in place; nothing in it loads.
+
 ## Accessibility
 
 - 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.

package/llms/components/pie-chart.md

@@ -36,7 +36,8 @@ Use PieChart for a share of one total across two to six categories — traffic s
 | tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
 | valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |
 | locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
-| animate | boolean | true | Sweep the slices in clockwise when the chart scrolls into view. |
+| 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 sweep, the slice morph and the rolling centre number are the flourish; the hover pull-out and dim are the feedback `subtle` keeps. |
+| animate | boolean | true | Sweep the slices in clockwise when the chart scrolls into view. `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. |
@@ -47,9 +48,10 @@ Use PieChart for a share of one total across two to six categories — traffic s
 
 ## Motion
 
-- **arrival** · Slices · _custom (outside the recipe layer)_ — 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.
-- **response** · Active slice · _no motion_ — The hovered slice pulls outward and the rest dim at once; the geometry change itself eases (see transition).
-- **transition** · Slices · _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** · Slices · _custom (outside the recipe layer)_ — 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.
+- **response** · Active slice · _no motion_ — 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.
+- **transition** · Centre value · _custom (outside the recipe layer)_ — 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.
+- **transition** · Slices · _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** · PieChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
 
 ## Accessibility

package/llms/components/pill.md

@@ -39,6 +39,14 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 
 `palette-wash`, `palette-wash-strong`, `palette-edge`, `palette-solid`, `palette-text`, `palette-solid-ink`, `secondary`, `secondary-foreground`, `accent`, `accent-foreground`, `primary`, `primary-foreground`, `card`, `border`, `muted-foreground`, `foreground`
 
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · Root · `motion-interactive` — The hover wash eases, so sweeping the pointer along a filter row reads as one cursor moving rather than chips flashing in turn.
+- **response** · Root · `motion-press` — 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.
+- **transition** · Root · `motion-interactive` — `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.
+- **activity** · Root · _no motion_ — A chip is a choice, not a process. If applying it is slow, the results show it.
+
 ## Accessibility
 
 - Renders a native <button type="button"> for focus and keyboard activation.