@sableui/react 0.6.2 → 0.7.1

package/llms/reference/utilities.md

@@ -2,8 +2,7 @@
 
 The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, when to reach for it, and what you would hand-write without it. Generated from `src/utilities/utility-docs.ts`; the full data is `registry.json → utilities`; one entry at a time with `sable utility <name>`.
 
-- **Typography:** The paired `text-*` page tiers (`text-heading-1`, `text-body-md`, `text-label-sm`, `text-mono-md`, …) are documented as `registry.json → tokens.typography` (named without the `text-` prefix). `sable token typography`.
-- **Motion:** The `motion-*` and `animate-*` recipes are listed in `registry.json → tokens.motion.recipes`, with the slot model in `registry.json → motionLayer`. `sable docs motion`.
+- **Typography:** The paired `text-*` page tiers (`text-heading-1`, `text-body-md`, `text-label-sm`, `text-mono-md`, …) are documented as `registry.json → tokens.typography` (named without the `text-` prefix). Retrieve one with `sable utility text-heading-1`, all with `sable token typography`.
 
 ### relative surface (6)
 
@@ -131,12 +130,93 @@ The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, wh
     - **Instead of** An animated fade or a hand-written `mask-image` gradient. Use `StreamingText` first; this is for a stream rendered without it.
     - `<span className="stream-tail">{latestChunk}</span>`
 
-### helper (3)
+### motion (24)
+
+- **`motion-interactive`** — The transition for interactive chrome: colour, background, border, shadow, opacity, fill, stroke, scale and translate at the fast duration and standard easing. Also removes the mobile tap delay and the platform's grey tap flash. *Use for:* On anything clickable that changes on hover, focus, press or selection: a custom row, a tile, a link, an app-owned button. It is the `response` slot, and the only transition declarer such an element needs.
+    - **Instead of** Tailwind's colour-only or all-property transition utilities with a hand-picked duration. Those ignore --motion-scale, skip the transform properties `motion-press` needs, and leave the 300ms tap delay on touch screens. sable-lint's `static-interactive` fires on a hover style with no recipe.
+    - `<a href="/inbox" className="motion-interactive link-underline text-primary">Inbox</a>`
+- **`motion-press`** — A small tactile settle (scale 0.97) while the element is pressed. Skips disabled elements. Declares only the pressed state, not a transition. *Use for:* A pressable surface that is not a Sable Button (Button already has it): a tile, a card that acts as a button, an icon control.
+    - **Instead of** An `active:` scale utility with its own transition, which fights `motion-interactive` for the transition property and keeps animating with motion off.
+    - `<button type="button" className="motion-interactive motion-press sable-surface sable-frame sable-frame-r-lg sable-frame-p-4">Open</button>`
+- **`motion-fade`** — Opacity-only enter and exit, keyed to Base UI's `data-starting-style` / `data-ending-style`: fades in at the enter duration, out at the exit duration. *Use for:* Scrims, backdrops and overlays that should appear without moving. The element rests visible; the data attributes supply the from and to.
+    - **Instead of** A keyframe fade or a conditional opacity class, which cannot animate the exit of an element Base UI is unmounting.
+    - `<div className="motion-fade fixed inset-0 bg-overlay" />`
+- **`motion-pop`** — Enter with a slight scale from the anchor edge (spring easing) and exit faster without overshoot, keyed to `data-starting-style` / `data-ending-style`. Scales from Base UI's `--transform-origin`. *Use for:* Anchored or centred floating surfaces: popovers, menus, selects, tooltips, dialogs, command menus. Sable's own overlays already carry it.
+    - **Instead of** A custom zoom keyframe, or a spring on exit, which draws the eye to what the user just dismissed.
+    - `<div className="motion-pop sable-surface-popover bg-popover text-popover-foreground rounded-lg shadow-lg">…</div>`
+- **`motion-slide-up`** — Fade plus a 0.5rem rise on enter, reversed faster on exit, keyed to `data-starting-style` / `data-ending-style`. The suffix is the travel direction on enter. *Use for:* A surface arriving from below: a toast at the bottom of the screen, a bottom bar, a banner under its trigger.
+    - **Instead of** A translate keyframe with a literal duration, which keeps moving under reduced motion.
+    - `<div className="motion-slide-up sable-surface rounded-lg">Saved</div>`
+- **`motion-slide-down`** — Fade plus a 0.5rem drop on enter, reversed faster on exit, keyed to `data-starting-style` / `data-ending-style`. *Use for:* A surface arriving from above: a top toast, a dropdown panel that reads better sliding than scaling.
+    - **Instead of** A translate keyframe with a literal duration.
+    - `<div className="motion-slide-down sable-surface rounded-lg">Connected</div>`
+- **`motion-slide-left`** — Fade plus a 0.5rem travel leftward on enter (it starts offset to the right), reversed faster on exit. *Use for:* A surface arriving from the right edge: a side panel, a right-anchored toast.
+    - **Instead of** A translate keyframe with a literal duration.
+    - `<aside className="motion-slide-left sable-surface">…</aside>`
+- **`motion-slide-right`** — Fade plus a 0.5rem travel rightward on enter (it starts offset to the left), reversed faster on exit. *Use for:* A surface arriving from the left edge: a navigation drawer, a left-anchored toast.
+    - **Instead of** A translate keyframe with a literal duration.
+    - `<nav className="motion-slide-right sable-surface">…</nav>`
+- **`motion-disclosure`** — Height plus fade for a panel that opens and closes: carries the overflow, the transition and the content fade. The component sets the target height and zeroes it on the starting/ending style. *Use for:* A hand-built expanding region. Accordion and Collapsible already use it; reach for them first.
+    - **Instead of** Animating max-height to a guessed number, or a show/hide with no transition. Height is the one sanctioned non-compositor property.
+    - `<div className="motion-disclosure h-[var(--collapsible-panel-height)]">…</div>`
+- **`motion-icon-swap`** — Cross-fades two glyphs stacked in one cell when a control's icon changes with its state: the outgoing one shrinks and blurs out, the incoming one resolves in. The inactive glyph is the one marked `aria-hidden="true"` (or `data-active="false"`). *Use for:* Play/pause, mute/unmute, outline/fill, copy/check, menu/close: one control whose icon changes. Keep both icons mounted; the correct accessibility markup is also the animation hook.
+    - **Instead of** Rendering one icon or the other (it snaps between two frames), or absolutely positioning the second icon, which collapses the wrapper. Under reduced motion the swap is instant and the glyph still changes.
+    - `<span className="motion-icon-swap"><Icon name="play" aria-hidden={playing} /><Icon name="pause" aria-hidden={!playing} /></span>`
+- **`motion-spin`** — A continuous rotation for a spinner glyph, scaled by --motion-scale so reduced motion freezes it. *Use for:* A loading glyph that is not the Spinner component (use Spinner first), such as an icon inside a busy button.
+    - **Instead of** Tailwind's built-in spin animation, which ignores --motion-scale. sable-lint's `builtin-animate` flags it.
+    - `<Icon name="spinner" className="motion-spin" />`
+- **`motion-orbit`** — A slow continuous rotation (24s by default) for ambient line art. `--motion-orbit-duration` sets the speed and `--motion-orbit-direction` the direction; it rotates about the centre of any viewBox. *Use for:* The idle loop of an illustration or schematic after it draws on, usually with `motion-draw` on the same figure.
+    - **Instead of** `motion-spin`, which is a loader's speed, or a hand-written keyframe that keeps turning under reduced motion.
+    - `<svg className="motion-orbit [--motion-orbit-duration:40s]" viewBox="0 0 200 200">…</svg>`
+- **`motion-pulse`** — A soft looping opacity pulse, scaled by --motion-scale. *Use for:* A live or pending indicator: a recording dot, an unsaved marker, a pending status.
+    - **Instead of** Tailwind's built-in pulse animation, which ignores --motion-scale. For a loading placeholder use Skeleton or `motion-shimmer`.
+    - `<span className="motion-pulse size-2 rounded-full bg-destructive" />`
+- **`motion-shimmer`** — The skeleton sweep: one band of light that passes across every skeleton on screen in sequence, because the gradient is fixed to the viewport. Rests off-screen, so with motion off a skeleton is a calm block. *Use for:* A hand-built loading placeholder. The Skeleton component already uses it.
+    - **Instead of** A pulse on each block, or a per-box gradient, where a short line and a tall card sweep at different speeds.
+    - `<div className="motion-shimmer h-4 w-48 rounded-md bg-muted" />`
+- **`motion-text-shimmer`** — The sweep run through the glyphs instead of behind them, for a live status line. The gradient goes muted to foreground and back, so the text stays readable on every frame. *Use for:* Status text while work is happening: "Thinking…", "Searching", "Generating response".
+    - **Instead of** `motion-shimmer` on text, which paints a band behind real words and reads as a skeleton. Named `motion-*`, not `text-*`, so tailwind-merge does not drop the colour class beside it.
+    - `<span className="motion-text-shimmer text-body-sm">Thinking…</span>`
+- **`motion-dot-bounce`** — A looping vertical bounce for one dot of a typing or waiting indicator. Offset each dot with an animation delay. *Use for:* A three-dot typing indicator in a chat or assistant surface.
+    - **Instead of** Tailwind's built-in bounce animation, which ignores --motion-scale.
+    - `<span className="motion-dot-bounce size-1.5 rounded-full bg-muted-foreground" />`
+- **`motion-ping`** — A looping ring that expands and fades from a point, scaled by --motion-scale. *Use for:* Drawing attention to a live point: a new-activity dot, a location marker, a beacon behind a status dot.
+    - **Instead of** Tailwind's built-in ping animation, which ignores --motion-scale.
+    - `<span className="motion-ping absolute inset-0 rounded-full bg-success" />`
+- **`animate-fade-in`** — A one-shot fade in on mount at the base duration, decelerating, with `both` fill so there is no flash before it starts. *Use for:* Content that appears once when a route or panel mounts.
+    - **Instead of** A keyframe with a literal duration. For content entering on scroll use Reveal (`motion-reveal`).
+    - `<section className="animate-fade-in">…</section>`
+- **`animate-fade-up`** — A one-shot fade plus rise on mount at the slow duration, decelerating, with `both` fill. *Use for:* A page section or list arriving from below on mount.
+    - **Instead of** A translate keyframe with a literal duration. For scroll-triggered entrances use Reveal.
+    - `<div className="animate-fade-up">…</div>`
+- **`animate-fade-down`** — A one-shot fade plus drop on mount at the slow duration, decelerating, with `both` fill. *Use for:* Content arriving from above on mount, such as a notice under a header.
+    - **Instead of** A translate keyframe with a literal duration.
+    - `<div className="animate-fade-down">…</div>`
+- **`motion-stream-in`** — Each token of a live stream resolves in from a slight blur once, on mount. Knows nothing of the final length, so there is no stagger. *Use for:* Wrapping each arriving chunk of a streamed response. StreamingText already does it.
+    - **Instead of** The reveal recipes, which stage text that is already there, or a typewriter effect.
+    - `<span key={chunk.id} className="motion-stream-in">{chunk.text}</span>`
+- **`motion-caret`** — A caret that blinks only when idle and holds steady while `data-streaming="true"`, so the blink returning signals the stream has finished. *Use for:* The cursor at the end of streamed or typed text.
+    - **Instead of** A caret that blinks while text is arriving, which sets two competing rhythms.
+    - `<span className="motion-caret" data-streaming={streaming} aria-hidden="true">▍</span>`
+- **`motion-reveal`** — Fade plus a 0.75rem rise when `data-reveal` flips from "out" to "in". Out of view it rests hidden and nudged down; with motion off the content stays visible. *Use for:* Through the Reveal and TextReveal components, which set `data-reveal` when the element scrolls into view. Use the class directly only on an element whose `data-reveal` you set yourself.
+    - **Instead of** An IntersectionObserver plus hand-written opacity classes.
+    - `<Reveal><Card>…</Card></Reveal>`
+- **`motion-draw`** — Draws an SVG path on when an ancestor's `data-reveal` flips to "in". The path needs `pathLength="1"`. `--motion-draw-duration` and `--motion-draw-delay` (both scaled by --motion-scale) set its pace and stagger. *Use for:* Line art and schematics inside a Reveal. Stagger sibling paths with `--motion-draw-delay`.
+    - **Instead of** A hand-written dash-offset animation with literal timing, which keeps animating, or keeps its delay, under reduced motion.
+    - `<Reveal><svg viewBox="0 0 100 100"><path className="motion-draw" pathLength="1" d="M10 50 L90 50" /></svg></Reveal>`
+
+### helper (5)
 
 - **`hit-target`** — Grows an element's tap target to 44px with a transparent `::after`, without moving its layout by a pixel. `--hit-target-size` overrides the size. *Use for:* A deliberately small mark — a tag's remove ×, a tiny disclosure, a toast close — that must still meet the WCAG touch floor. Shrink it (`[--hit-target-size:32px]`) where targets sit side by side, or the later one steals the taps.
     - **Instead of** Padding the glyph up (moves it off the row's grid and pushes siblings) or a bigger icon. Never on an `<input>` or other replaced element — pseudo-elements silently do nothing there; wrap it in a label.
     - `<button className="hit-target text-muted-foreground" aria-label="Remove"><Icon name="xmark" /></button>`
-- **`link-underline`** — An underline drawn from the font's own metrics (position and thickness `from-font`) with ink skipping descenders, so it retunes when a theme swaps typeface. *Use for:* Inline links in running text. Pair with `motion-interactive` for a colour change on hover.
+- **`reveal-on-hover`** — Hides a row or tile action until its item is hovered or holds focus — on hover-capable devices only. Touch and no-hover devices always show it, and it fades with opacity, so it never leaves the tab order or the accessibility tree. The item is the nearest ancestor with `group` (or `data-reveal-scope`); an open popup keeps its trigger visible. `--reveal-offset` adds a short rise. *Use for:* Secondary per-item actions in a dense list or grid — a tile's play button, a row's overflow menu or visibility toggle — where showing every action at rest would turn the list into a wall of controls. Put `group` on the item (the row, the tile), not on the list, and the class on the action or its wrapper.
+    - **Instead of** `opacity-0 group-hover:opacity-100` (hidden forever on a phone), `hidden group-hover:flex` (drops it from the tab order and the accessibility tree), or a hand-written `[@media(hover:hover)]:opacity-0` pair (snaps, and misses focus and open menus). Not for a primary action — that stays visible.
+    - `<li className="group flex items-center gap-2"><span className="flex-1">Track</span><Button variant="ghost" size="icon-sm" aria-label="Like Track" className="reveal-on-hover"><Icon name="heart" /></Button></li>`
+- **`stretched-link`** — Makes one link cover its whole item with a transparent `::after`, so a tile or card is clickable everywhere while its other links and buttons stay separate controls. Focus draws the ring on the overlay, rounded by `--stretched-link-radius`. *Use for:* A card, tile or row that IS a link but also holds a second control — a subtitle link to the artist, a play button, a menu. Put it on the primary link (usually the title), `relative` on the item, and `relative z-10` on every other control.
+    - **Instead of** Wrapping the item in an `<a>` or `Card render={<a />}` — invalid as soon as it nests another link or button, which browsers re-parent and screen readers read as one long link. Not with `hit-target` on the same element (both own `::after`).
+    - `<article className="relative [--stretched-link-radius:var(--radius-lg)]"><a href="/albums/1" className="stretched-link">Low tide</a><a href="/artists/2" className="relative z-10">Juno Avery</a></article>`
+- **`link-underline`** — An underline drawn from the font's own metrics (position and thickness `from-font`) with ink skipping descenders, so it retunes when a theme swaps typeface. Also carries the link's focus-visible outline in `--ring`, so a plain `<a>` meets the focus floor without app CSS. *Use for:* Every plain text link — inline in running text or standalone ("Forgot password?"). Pair with `motion-interactive` for a colour change on hover.
     - **Instead of** `underline underline-offset-4 decoration-2` — tuned to one face and wrong for the next theme's. Animating thickness or offset is not supported; a growing underline is a separate pseudo-element.
     - `<a href="/terms" className="link-underline motion-interactive text-primary">terms</a>`
 - **`checkerboard`** — The transparency checkerboard, painted from `--panel` and a derived darker step so it reads in both modes. `--checkerboard-size` (default 16px) and `--checkerboard-alt` tune it. *Use for:* Behind anything that can be translucent: a colour swatch with alpha, an image or artboard preview, an alpha slider track.

package/llms/tasks/building-a-page.md

@@ -30,9 +30,9 @@ designs. Record the reason for the chosen composition.
 </AppShell>
 ```
 
-- **Never a global `max-width`.** Width is capped per region by role:
-  `prose` / `form` / `feed` / `content` / `wide` / `full`. A form region is narrow
-  because a 700px text input is harder to use, not more generous.
+- **Never a global `max-width`.** Width is chosen per route by what the person
+  does there (below). A form region is narrow because a 700px text input is
+  harder to use, not more generous.
 - **Measure ≠ width.** Cap prose line length in `ch` (`--measure-prose`)
   independently of the region's layout width.
 - **The 12-column grid lives *inside* a region**, for genuinely multi-column
@@ -40,6 +40,37 @@ designs. Record the reason for the chosen composition.
 - **Chrome is off the grid.** `Sidebar` and rails are fixed-width, outside the
   content grid.
 
+## Choosing a width
+
+Pick each route's `max` by what the person mainly does on it:
+
+| They mainly… | `max` | Why |
+|---|---|---|
+| read long text | `prose` on the text, inside `content` | line length sets readability: cap the text, not the page |
+| fill in a form | `form` | narrow fields are faster to scan and fill |
+| scroll one stream | `feed` | one column, one eye path |
+| review one record, or settings | `content` | labels stay close to their values |
+| scan and compare rows, cards or charts | `wide` | room for columns without stretching the gaps between them |
+| work across panes, a board, an editor or a map | omit it (fluid), or `full` | the extra width goes to the parts that use it |
+
+- **Go fluid only when a flexible part uses the space**: a table's main column,
+  a canvas, a board, a reading pane. If extra width only widens the gaps between
+  fixed columns (a date drifting away from its subject), cap it.
+- **In a fluid page, cap text by line length** (`--measure-prose`, or
+  `Center max="prose"`), not by page width.
+- **Sibling routes in one nav share a width**, so the header doesn't jump as
+  people move between them. A detail view may differ.
+- **`full` is the largest cap, not edge to edge.** It keeps the page inset;
+  `bleed` is edge to edge.
+- **A cap is a ceiling.** It applies only once the viewport minus app chrome is
+  wider than it: beside a 256px sidebar, `wide` (1280px) starts at about 1536px,
+  so at 1440px `wide`, `full` and fluid look the same. Judge widths at 1920px and
+  2560px, and record each route's width and reason in the brief.
+- **A product's widths belong in its theme.** A preset may set `page-inset` and
+  `region-*` (`form`, `feed`, `content`, `wide`, `full`) in `tokens.shared`
+  (a copy in `light` or `dark` wins over it); keep the role names and change
+  the values.
+
 ## Typography: pick the tier by ROLE, not by size
 
 | tier | for | not |

package/llms/tasks/converting-an-app.md

@@ -53,12 +53,22 @@ probably keeping a layout that Sable would have given you.
 
 ## 4. Icons
 
-**Reicon works by default.** No icon provider is needed. To use another icon
-package, map Sable's semantic names in an app-owned IconSet and mount it through
-IconProvider. To add domain-specific names while retaining Reicon:
+**Mount an icon set once at the root.** `<Icon>` has no built-in fallback:
+without an `IconProvider`, icons render nothing (a development build warns once).
 
 ```tsx
-import { IconProvider, composeIconSets, reiconIconSet } from "@sableui/react"
+import { IconProvider } from "@sableui/react"
+import { reiconIconSet } from "@sableui/react/icons/reicon"
+<IconProvider set={reiconIconSet}>{app}</IconProvider>
+```
+
+To use another icon package, map Sable's semantic names in an app-owned IconSet
+and pass it instead; the app then ships none of Reicon. To add domain-specific
+names while retaining Reicon:
+
+```tsx
+import { IconProvider, composeIconSets } from "@sableui/react"
+import { reiconIconSet } from "@sableui/react/icons/reicon"
 <IconProvider set={composeIconSets(appExtras, reiconIconSet)} />
 ```
 

package/llms/tasks/creating-a-preset.md

@@ -13,7 +13,10 @@ cannot establish animation timing, hidden behavior, or an unseen responsive stat
 Choose an original direction suitable for the user's future product. Map that
 direction onto the installed Sable token vocabulary. Preserve readable semantic
 roles and supported control behavior rather than recoloring every primitive
-independently. Load fonts through the consuming project's font setup.
+independently. Load fonts through the consuming project's font setup. Page widths
+are optional: set `page-inset` and the `region-*` caps (`form`, `feed`, `content`,
+`wide`, `full`) in `tokens.shared` only when the direction calls for a different
+page proportion, and keep each cap's role.
 
 ```bash
 pnpm exec sable preset --template

package/llms/tasks/reviewing-a-design.md

@@ -10,6 +10,10 @@ Save the surface brief, then capture the rendered route at a desktop width of at
 least 1024px and a mobile width of at most 480px. Record the actual viewport,
 route/state, supported color mode, and motion setting with each artifact. Inspect
 the whole route as well as its first viewport. Ensure fonts and media have loaded.
+Also capture a route that sets a width cap, or goes fluid, at 1920px: a cap applies
+only once the viewport minus app chrome exceeds it, so at 1024–1440px `wide`,
+`full` and fluid usually look the same and the width decision never shows. Add
+2560px for a fluid route.
 Use a recording or an observed interaction report for behavior that a still cannot
 show. Include reduced motion and every color mode the surface promises to support.
 
@@ -47,6 +51,21 @@ those values into artifact records only after inspecting the corresponding files
 replacing a capture at the same path then makes the review incomplete. Neither
 the source fingerprint nor an artifact hash proves someone inspected the screen.
 
+The template starts with one example screenshot and one example report artifact.
+Replace them with your own captures; as shipped they point at no file and fail
+validation. Each artifact record has these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | A unique name that dimensions, checks and iterations cite in `evidence`. |
+| `kind` | `screenshot`, `recording`, or `report` (a written observation, such as a keyboard walkthrough). |
+| `path` | The capture file, relative to the review JSON. It must exist and be non-empty. |
+| `sha256` | The file's hash, copied from `review.artifactHashes` after you inspect the file. |
+| `state` | The route and state captured, such as "checkout, payment error". |
+| `viewport` | `{ width, height }` in pixels. Screenshots and recordings only. You need one at 1024 wide or more and one at 480 wide or less. |
+| `colorMode` | `light` or `dark`. Screenshots and recordings only. |
+| `motion` | `full` or `reduced`. Screenshots and recordings only. At least one artifact must be captured with reduced motion. |
+
 ## Review these eight dimensions
 
 | Dimension id | Look for concrete evidence |

package/llms/tasks/using-presets.md

@@ -76,6 +76,25 @@ Use a unique preset ID so it cannot override a bundled theme or another record.
 Record any intentional adaptation and run the validation and rendered review in
 [building-with-sable.md](./building-with-sable.md).
 
+## Apply to an existing app
+
+A preset pasted into an agent for a running app (Canvas's “Copy for agent”) is a
+restyle: the job ends with the app built and rendered in the preset, not with a
+saved file. Replace, don't add beside:
+
+1. Save it to `.sable/presets/<id>.json`, overwriting an earlier revision of the
+   same ID, and run `sable preset --check`.
+2. Regenerate its CSS with `sable preset --css` and import it after Sable's
+   stylesheet. Remove the stylesheet of a theme it replaces when nothing else uses it.
+3. Load the families its `fonts` stacks name through the app's existing font
+   setup, and drop the old theme's font loading when no other code uses it.
+   An unloaded family falls back to a system face without any error.
+4. Point SableThemeProvider's `defaultThemeId` at the preset ID and
+   `defaultPreference` at its `defaultMode`, unless the user asked for another
+   mode. A bundled theme left as the default keeps the app on the old look.
+5. Run the app's build and type check, then `sable check`, and review the result
+   in both modes.
+
 ## Upgrade the package and skill
 
 ```bash