@felloinnovations/brand-kit 0.4.0 → 0.5.1

package/design-system/13-motion.md

@@ -1,58 +1,341 @@
 # Motion
 
-One motion language: things arrive on one soft curve, leave faster on the exit curve, and nothing loops but the one working
-beat. Everything is still under reduced motion.
+Seth's motion, taken from his North app and named by role (D7). Things grow out of where they were and go back the same
+way, quicker. The frame moves first; its details settle after. Hover is a colour, never a lift. Under reduced motion
+everything is still.
 
-## Tokens
+## The rule
 
-| Token | Value | For |
+**Motion comes from the kit.** Build with the component's markup and classes and it already moves: the press, the
+sliding indicators, the folds, the enters and exits are in `fello.css`, on Seth's springs. Never type a duration, a
+curve, a `cubic-bezier()`, a spring or a `@keyframes` by hand, and never restyle a kit element's transition.
+
+When a part is genuinely your own (nothing in the catalog has it), it still moves on the kit's role tokens, inside
+`@media (prefers-reduced-motion: no-preference)`:
+
+- **A spring for what the person drives** (a press, the pointer, a choice, a panel): `--ws-spring-<name>` over
+  `--ws-spring-<name>-duration`, always the pair. Each is Seth's spring written out as a CSS `linear()` curve, its own
+  small overshoot kept, and the time it takes to settle. A spring can be interrupted and picks up from where it is.
+- **A duration and a curve for what the system plays** (a draw, a build, a loop): `--ws-duration-*` and
+  `--ws-ease-*` (Role tokens, below).
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  .my-thumb { transition: translate var(--ws-spring-indicator-duration) var(--ws-spring-indicator); }
+  .my-note { animation: ws-settle var(--ws-duration-settle) var(--ws-ease-soft) backwards; }
+}
+```
+
+In React with the motion library, the same springs are presets: `import { springs, eases } from
+'@felloinnovations/brand-kit/tokens'` (`transition={springs.press}`), and every motion tree sits in
+`<MotionConfig reducedMotion="user">`.
+
+## By situation
+
+### Hover
+
+A colour, never a lift: no shadow, rise or grow on hover. Kit controls and rows carry their own wash; anything of yours
+takes `.ws-hover-tint` (`--faint` for a list row, the default for a nav or menu row, `--strong` for an icon button or a
+quiet act). It turns over `--ws-duration-hover` (200 ms) on `--ws-ease-soft`, only where a pointer hovers
+(`@media (hover: hover)`), so a tap never leaves it on. Why: a colour answers the pointer without moving the layout; a
+lift says "this floats", and a control does not. What hover reveals (a close, an arrow, a row's acts) also shows on
+`:focus-visible` and on a tap; an arrow may step forward by `--ws-nudge`.
+
+```html
+<li class="lead-row ws-hover-tint ws-hover-tint--faint">...</li>
+```
+
+### Press
+
+`.ws-btn`, `.ws-icon-btn`, `.ws-suggestion-chip` and a chip that acts (`button.ws-chip`, `a.ws-chip`) give under a
+press and spring back, on `--ws-spring-press` (Seth's "Button press (mic, add)"): to `--ws-press-scale` (0.97), a round
+act (`ws-icon-btn--round`, `.ws-press--round`) to 0.94, the send act (`.ws-press--send`) to 0.92. Their colours turn at
+once going in and over `--ws-duration-hover` coming out. Words that act (`--link`, `--text`), a disabled control and a
+busy one do not move. Rows, list rows, menu rows and cards never scale: a press tints them a step darker
+(`--ws-surface-press`). Why: the spring's small give says "pressed" without changing the layout, and it rides `scale`,
+so the control's own transform is untouched. Your own pressable thing adds `.ws-press`.
+
+```html
+<button type="button" class="report-tile ws-press">Open the report</button>
+```
+
+### A choice moving: sliding indicators
+
+When the choice changes, its mark slides from the old item to the new one instead of jumping. No script and no extra
+markup: the chosen item is a CSS anchor and the track's own pseudo-element slides to it. Mark the choice the way the
+component's README says and it moves.
+
+| Component | What slides | Spring (Seth's label) |
 | --- | --- | --- |
-| `ws-ease-soft` | decelerate | everything arriving; every pop (no overshoot) |
-| `ws-ease-exit` | accelerate | everything leaving |
-| `ws-ease-glide` + `ws-duration-glide` | balanced, 400 ms | a side panel's width |
-| `ws-ease-steady` | linear | a live ring keeping pace with a clock |
-| `ws-duration-instant` | 120 ms | hover, press, focus, a chip flipping, a dialog's exit |
-| `ws-duration-gentle` | 200 ms | the default: a row or card arriving, a menu, a drawer leaving |
-| `ws-duration-settle` | 320 ms | a pane, dialog or drawer in, a screen changing, a pop, a tile rising |
-| `ws-duration-calm` | 420 ms | content replacing a skeleton, a chart drawing, a figure counting |
-| `ws-stagger` | 30 ms (40 slow), at most 6 items | a list's first paint only |
-| `ws-sweep` | 220 ms | a chart's parts filling first to last |
-| `ws-rise` | 6 px | how far things rise as they arrive (the person's message 12) |
-| `ws-press-scale` | 0.97 | a control under a press; 1 with reduced motion |
-| `ws-loop` / `ws-loop-slow` | 1.2 s / 2.4 s | the working beat; a big quiet area's |
+| `Segmented` | the thumb | `--ws-spring-indicator` ("Toggle pill slide") |
+| `Tabs` | the underline | `--ws-spring-tab` ("Department card underline") |
+| `AppShell` | the sidebar's current-row pill | `--ws-spring-nav` ("Sidebar active row slide") |
+| `SideList`, `ListDetail` | the selected row's fill | `--ws-spring-highlight` ("List highlight slide") |
 
-## Rules
+Only a real choice moves it: at rest the chosen item paints its own ground, and the slide takes over while the track is
+pointed at or holds focus, so a resize or a late font lands at once. Why a spring: the person drives it, and a second
+click mid-slide turns it from where it is.
+
+```html
+<div class="ws-segmented" role="group" aria-label="View">
+  <button type="button" class="ws-segmented__item" aria-pressed="true">Bars</button>
+  <button type="button" class="ws-segmented__item" aria-pressed="false">Line</button>
+</div>
+```
+
+### Something opening in place: folds
+
+What opens in place grows from nothing to its height and fades in, then closes back the same way, on `--ws-spring-fold`
+(Seth's "Sidebar sections open / close", no bounce); a chevron turns on the same spring. Every kit `<details>` does it
+on its own (`Fold`, or any `<details>` inside a kit element). A body your script shows and hides with the `hidden`
+attribute wears `.ws-unfold` (as `CheckRow`'s detail does), and its padding and margins grow with it, so nothing
+jumps. Why: what sits below is pushed down smoothly instead of leaping, and the person sees where the new part came
+from.
+
+```html
+<button type="button" aria-expanded="false" aria-controls="why">Why this move</button>
+<div class="ws-unfold" id="why" hidden>...</div>
+```
+
+### Something appearing over the page: enters and exits
+
+It grows out of what opened it and goes back there, **quicker**: every exit is shorter than its entrance. Why: the eye
+follows cause to effect on the way in; on the way out the person has already moved on.
+
+| Component | Enters | Leaves | How the exit gets to play |
+| --- | --- | --- | --- |
+| `Menu`, `Popover` | out of the corner it hangs from, 4 px toward its control, from `--ws-open-scale` (0.97), on `--ws-spring-settle` ("Messages and steps settle") | back into that corner over `--ws-duration-exit` (120 ms) on `--ws-ease-exit` | a native `popover`: `@starting-style` and `allow-discrete` keep its box while it leaves, and a close mid-entrance turns back. Mounted by the app: `data-leaving`, then remove it |
+| `Dialog` | the scrim fades; the window rises 14 px out of `--ws-open-scale-pane` (0.98) on `--ws-spring-settle`, its parts settling in after it | 8 px down over `--ws-duration-exit` | a native `<dialog>` (`showModal()`, `close()`), the same way. A drawer slides in from its edge over `--ws-duration-grow` on `--ws-ease-grow` and back over `--ws-duration-shrink` |
+| `Toast` | up out of `--ws-open-scale-toast` (0.96) on `--ws-spring-settle` | 4 px down over `--ws-duration-exit` | `data-leaving`, then remove it |
+| `Tooltip` | pops from 0.9, 4 px toward its control, on `--ws-spring-pop` ("Tooltip pop-in"), after the 40 ms hover intent; at once on keyboard focus | fades off over 180 ms | CSS alone: hover, focus or `ws-tooltip--open` |
+| `HoverCard` | pops from 0.9 on `--ws-spring-pop`, its rows settling 45 ms apart; `--follow` glides after the pointer on `--ws-spring-follow`, which never bounces | to `--ws-pop-scale` over `--ws-duration-exit` | `data-leaving`, then remove it |
+| `Panel`, `ChatShell` | out of 0.97 from the edge it docks to, out of an 8 px blur, on `--ws-spring-panel` ("Opens / moves / docks") | back over 160 ms | `data-leaving` (or `ws-panel--leaving`), then remove it |
+
+An element the app mounts and unmounts keeps its node until its exit has played. Wait on its own animations, never a
+number of your own (under reduced motion there are none, so it goes at once):
+
+```js
+toast.dataset.leaving = '';
+Promise.allSettled(toast.getAnimations().map((a) => a.finished)).then(() => toast.remove());
+```
+
+### A card going full screen, or the chat changing mode: `morph()`
+
+A thing that changes its place or size goes there as itself, never as a copy sliding in. `morph(update, { as, el })`
+runs your class or state change as a view transition on Seth's curve for `as`: `full` (a chat card to full screen and
+back, `--ws-duration-morph` on `--ws-ease-morph`), `grow` and `shrink` (a tile opening across its row over
+`--ws-duration-grow`, closing back over the quicker `--ws-duration-shrink`, both on `--ws-ease-grow`), `shift` (the chat
+between bar, docked and full, `--ws-duration-shift` on `--ws-ease-shift`). Words never scale: they ride in the frame's
+corner, fade off and fade back. `full` also lifts the element into the top layer, so it covers the whole window from
+inside any ancestor, moves focus in, and Escape (or its own Back button) brings it home. Why: the person sees the card
+they tapped become the full screen, and finds it again in its place when it closes.
+
+```ts
+import { morph } from '@felloinnovations/brand-kit';
+morph(() => card.classList.toggle('ws-chat-card--full'), { as: 'full', el: card });
+morph(() => flushSync(() => setMode('docked')), { as: 'shift', el: shellRef.current }); // React: flush inside
+```
+
+### A list reordering: `reorder()`
 
-- Only `transform`, `opacity`, colour and shadow move; height only through a layout animation, `interpolate-size` or a
-  fixed track. No UI motion over 400 ms; `calm` only for content and charts. Exits are shorter than entrances.
-- Everything is interruptible: a transition picks up from where it is; no keyframe blocks input; animation never moves
-  focus.
-- A stagger runs only on first paint, never on a re-filter.
-- Things arrive from where they belong: a panel from its edge, a menu from its corner, a chart from its middle, words
-  rising 6 px into place. Nothing slides across the screen.
-- Nothing loops on its own except the working signal (typing dots, a pressed button's dot, a live face's ring, an
-  indeterminate bar), all on `ws-loop`.
-- Reduced motion: keyframes do not run, presses do not scale, dialogs cross-fade, folds snap, scrolling is instant, figures
-  show their value, a chart shows its final figure drawn.
+Rows that change places glide to their new places instead of jumping: a sort, a filter, a card dropped in another
+column. `reorder(update, within)` snapshots the rows before and after your update and moves each as one piece on
+`--ws-spring-reorder` (Seth's "List rows reorder", no bounce); a row that arrives or leaves fades, and a card that
+changes column flies above the ones it passes. It knows the kit's rows (`KanbanBoard` cards, `ListDetail` rows,
+`SideList` picks); pass a selector as the third argument for others. Give each row an `id` or `data-key` so it is
+followed across a re-render. Why: the person keeps their place in the list and sees where each row went. A stagger
+never replays on a re-filter: rows that stay reorder in place.
 
-## What moves, beyond the components
+```ts
+import { reorder } from '@felloinnovations/brand-kit';
+reorder(() => flushSync(() => setRows(sorted)), listRef.current);
+```
 
-Each component's README says how it moves. What sits between components:
+### Build-in (a dashboard on arrival)
 
-| What | What moves | How |
+Amit, 5 Nov 2026: North's Home intro is the kit's default for every dashboard, not North's alone. A page or a section
+of cards wears `.ws-build`; each card in it wears `.ws-build__card` with `--ws-i` (0, 1, 2 ... in reading order).
+
+- **The cards** rise in (`ws-rise`: 6 px and a fade, 320 ms on `settle`), each 70 ms after the one before
+  (`ws-stagger-part`; North's cards are 71 ms apart, a .21 share of its 1.7 s rail). A card's start is
+  `--ws-build-at` (`--ws-i` x 70 ms).
+- **The charts in a card** that carry their draw (`--draw` on a `MetricTile`, `SideList`, `PaceBar`, `GoalBars`,
+  `TickStrip`, `TickRow`, `ShareBar`, `StepLine`; `.ws-ring__value--draw`; `--build` on a `Heatmap`; `ws-grow-up`
+  on `TrendBars` and `GoalTubes`) add `--ws-build-at` to their own delays, so each draws as its card lands. A tile's
+  columns grow from the baseline one after another, its line draws left to right and its dots pop, then its foot's
+  figure rises in; a goal list's bars fill in order. Those two run over the card's share of `ws-duration-fill-page`
+  (1343 ms, North's "Metric + goal bars fill"); every other chart keeps its own draw (900 ms in a card).
+- **When**: on arrival, once. Where the browser has scroll-triggered animation (a `timeline-trigger` on the card's own
+  `view()` timeline, `animation-trigger: play-once`), a card waits, hidden, until a tenth of it has come into view and
+  then plays; scrolling back never replays it. Elsewhere it all plays on first paint, so a card below the fold has
+  finished, its final state, by the time it is reached. It is a scroll trigger, not a scroll-driven timeline: the
+  build plays in time and is never scrubbed by the scroll.
+- **Budget**: the first screen's build, cards and draws, stays under `ws-duration-build` (2400 ms). Number the cards
+  that arrive together from 0: a card below the fold plays when it is reached, so its `--ws-i` orders it only among the
+  cards that come into view with it (a row of tiles 0 to 3, the next row 0 to 3 again).
+- **What stays still**: hover is still a tint (a tile's frame darkens, its arrow steps); a headline figure shows its
+  value at once (it never counts); a re-filter or a resize replays nothing. A fresh element builds in again, so an
+  app keeps its cards' elements (stable keys) when only their numbers change.
+- **Reduced motion**: no build. Every card and chart is in its final state from the first frame.
+- North's cards also arrive at 1.15 and shrink to their place; the kit leaves the scale out (a card larger than its
+  column pushes a phone's page sideways while it lands) and keeps North's curve, stagger and draws.
+
+```html
+<section class="ws-build">
+  <div class="ws-metric-tiles"><div class="ws-metric-tiles__grid">
+    <button type="button" class="ws-metric-tile ws-metric-tile--draw ws-build__card" style="--ws-i: 0;" aria-label="...">...</button>
+    <button type="button" class="ws-metric-tile ws-metric-tile--draw ws-build__card" style="--ws-i: 1;" aria-label="...">...</button>
+  </div></div>
+  <div class="ws-side-list ws-side-list--draw ws-build__card" style="--ws-i: 2;">...</div>
+  <section class="ws-card ws-build__card" style="--ws-i: 3;">... <div class="ws-pace-bar ws-pace-bar--draw">...</div></section>
+</section>
+```
+
+### Loading
+
+Content on its way is a ghost the size of what it stands for with the shimmer passing over it: one quiet tone, the
+ghost grey and a lighter pass of the same grey, never a chart hue (`Skeleton`, or `.ws-shimmer` on a block of your own:
+every `--ws-loop-shimmer`, 1.8 s, on `--ws-ease-shimmer`), never a spinner. When the content lands, its details settle in top to bottom (`.ws-settle` with `--ws-i` on each, 22 ms
+apart). An answer at work shows a `StatusLine`; a long load with no figure a `LoadBar`; a pressed button waiting keeps
+its width and shows its working dot on `--ws-loop`. Why: the layout is already in place, so nothing jumps when the real
+thing arrives. Under reduced motion the shimmer stops on its ghost and the words say what is loading.
+
+```html
+<div class="ws-skeleton ws-skeleton--line" aria-hidden="true"></div>
+<p class="ws-settle" style="--ws-i: 0;">Your calls this week</p>
+```
+
+### Charts drawing
+
+A chart builds in when it arrives: its `--draw` variant (the list under Build-in) or, for `TrendLine`, on its own. A
+draw is one progress: marks start at their share (mark `i` of `n` at `i / (n - 1) x 0.55` of the draw) and ease on
+`--ws-ease-settle`; values written in the chart follow it. A chart draws over `--ws-duration-draw` (900 ms) in a card,
+`--ws-duration-draw-chat` in the chat, and over its card's share of `--ws-duration-fill-page` in a `.ws-build`. Why: one
+sweep reads as the data arriving; marks sliding in from an edge read as noise.
+
+- **On hover** the hovered column's band slides over `--ws-duration-settle`; the rest dims to `--ws-dim`; a hovered
+  tick or wedge grows to `--ws-grow-scale` from its base.
+- **Bars to a line** (`TrendLine`): the columns collapse into their tops on `--ws-spring-morph-chart` ("Bars to line
+  morph") while the line draws left to right; back, they grow down from the dots. Switch the class; the CSS does the
+  rest.
+- **A headline figure never counts up**: it shows its value.
+- **Nothing that carries data loops.**
+
+```html
+<div class="ws-goal-bars ws-goal-bars--draw">...</div>
+```
+
+## Which spring, when
+
+From `motion.springs` in `tokens/design-tokens.json`: Seth's tuned springs, each as `--ws-spring-<name>` and
+`--ws-spring-<name>-duration` in CSS and `springs.<name>` in JS. Reach for the one whose label matches the move; the
+components already use theirs.
+
+| Spring | Seth's label | For |
 | --- | --- | --- |
-| Rows, menu rows, sidebar rows | a tint; a step darker under a press (rows never scale) | instant |
-| Sidebar's current row | the wash slides from the row it left | a shared layout, 200 ms |
-| A clicked link card or row | its navy edge pulses until the page answers | `ws-working` |
-| A field's error, a form's outcome | rises in with a mark before the words | `ws-arrive` |
-| Typing dots | breathe | `ws-loop` |
-| Search results, a filter's results | cross-fade | gentle |
-| Cards on a board | rise in, staggered | settle |
-| Route change inside the frame | the canvas cross-fades (fixed panels stay) | settle |
-| A pane closing | slides back and fades, gives its room back before the next page answers | gentle, exit curve |
-| A row set aside, Undo | folds away; rises back | gentle |
-| Bars, tubes | grow from their start; ease to a new length when the value changes | calm, staggered; settle |
-| Ticks, days | fill in first to last | gentle each, over `ws-sweep` |
-| Petals, marks | bloom from the middle | settle |
-| Rings | draw to their figure once; a live one follows at an even pace | calm; steady |
-| A figure | counts up from nought; counts on when it changes while shown | calm |
+| `press` | Button press (mic, add) | a button or chip under a press (house press) |
+| `follow` | Tooltip follows cursor | something trailing the pointer; never bounces (`HoverCard --follow`) |
+| `pop` | Tooltip pop-in | a tip or a hover card popping in (`Tooltip`, `HoverCard`) |
+| `settle` | Messages and steps settle | menus, popovers, dialogs, toasts, a message settling |
+| `fold` | Sidebar sections open / close | a height opening or closing, and its chevron (`<details>`, `.ws-unfold`) |
+| `indicator` | Toggle pill slide | a segmented thumb (`Segmented`) |
+| `tab` | Department card underline | a tab's underline (`Tabs`) |
+| `nav` | Sidebar active row slide | the sidebar's current pill (`AppShell`) |
+| `highlight` | List highlight slide | a list's selected fill (`SideList`, `ListDetail`) |
+| `reorder` | List rows reorder | rows moving to new places (`reorder()`) |
+| `tile` | Tile grows open / closes | a heatmap square opening (`Heatmap`) |
+| `mark` | Pace dot on an opened square | a small mark popping in (`Heatmap`) |
+| `panel` | Opens / moves / docks (spring) | a panel or the chat opening, moving, docking (`Panel`, `ChatShell`) |
+| `card` | Chart card arrives | a chart card arriving in the thread (`ChatCard`) |
+| `glow`, `roll` | Focus glow; Placeholder roll | the composer's focus glow and rolling placeholder (`Composer`) |
+| `morphChart` | Bars to line morph | a chart changing form (`TrendLine`) |
+| `lane` | Department: lane detail opens / closes | a lane's detail opening (token only) |
+| `lens` | Lens switch (chart swap) | one chart swapping for another inside an open tile (token only) |
+| `swap` | Old chart out / new chart in | a board chart replaced by another (token only) |
+| `flag` | Trend flag follows the pointer (spring) | a read-out following the pointer along a chart (token only) |
+| `text` | Metric card text swap | a card's words swapping (token only) |
+| `badge` | Nav count badge pop | a count badge popping when it changes (token only) |
+| `chip` | Attention chip to card | a chip opening into its card (token only) |
+| `orb` | Agent orb arriving | an agent's orb arriving (token only) |
+| `default` | Anything not tuned | anything the person drives that no spring above fits |
+
+"Token only": no kit component moves this way yet; build it on the token and report it as new.
+
+## Role tokens
+
+For your own part, by role. Values are in `tokens.md`.
+
+| Duration | For |
+| --- | --- |
+| `--ws-duration-instant`, `--ws-duration-exit` (120 ms) | a press going in; every exit |
+| `--ws-duration-hover` (200 ms) | hover colour, tint, edge and opacity; a scrim |
+| `--ws-duration-text` (250 ms) | words changing colour, small fades |
+| `--ws-duration-settle` (320 ms) | details settling in, a chart's hover band |
+| `--ws-duration-reveal` (350 ms) | an underline growing, a bar's ground |
+| `--ws-duration-shrink` (400 ms), `--ws-duration-grow` (550 ms) | a tile closing back; a tile or drawer growing open |
+| `--ws-duration-morph` (450 ms), `--ws-duration-shift` (550 ms) | a shared element in flight; layout moving (docking, columns, the sidebar folding) |
+| `--ws-duration-fill` (700 ms), `--ws-duration-draw` (900 ms) | a bar filling; a chart drawing in a card, a ring filling |
+| `--ws-duration-draw-chat`, `--ws-duration-fill-page`, `--ws-duration-build` | a chart in the chat; a dashboard's charts; a page's whole build, at most |
+
+| Curve | For |
+| --- | --- |
+| `--ws-ease-soft` | the default: content arriving, a hover, a fold |
+| `--ws-ease-settle` | things that land and rest: a mark, a bar filling, a card building in |
+| `--ws-ease-grow`, `--ws-ease-shift`, `--ws-ease-morph` | a shape changing size; layout moving; one element in flight |
+| `--ws-ease-exit` | everything leaving |
+| `--ws-ease-steady` | linear: a draw's overall progress, a live ring keeping pace |
+| `--ws-ease-sweep`, `--ws-ease-commit` | a chart sweeping in the chat; a decisive one-shot (sending, a check mark) |
+| `--ws-ease-shimmer`, `--ws-ease-loop`, `--ws-ease-ambient` | a loading sweep; every loop; the one slow brand sheen |
+| `--ws-ease-pop`, `--ws-ease-lift` | overshoot, for marks under 24 px only |
+
+Staggers: `--ws-stagger` (30 ms, a list's rows on first paint), `--ws-stagger-detail` (22 ms, details in an opening
+part, `.ws-settle`), `--ws-stagger-row` (45 ms, a hover card's rows), `--ws-stagger-part` (70 ms, cards building in).
+Loops: `--ws-loop` (the working dots), `--ws-loop-status`, `--ws-loop-shimmer`, `--ws-loop-slow`, `--ws-loop-ambient`
+(the one ambient sheen, never on data). Distances: `--ws-nudge` (4 px), `--ws-rise` (6 px), `--ws-drop` (12 px);
+`--ws-blur-arrive` (3 px) and `--ws-blur-panel` (8 px) on arrival.
+
+## Rules
+
+- **What may move**: transform, `scale`, `translate`, opacity, colour, a blur up to 8 px on arrival, `clip-path`, and a
+  shimmer's `background-position`. Size, padding and grid tracks move only in a fold, a dock, the sidebar folding or a
+  `morph()`; never on hover.
+- **From where it belongs**: a tip from the edge nearest its mark, a menu from its corner, the chat from its mode's
+  edge, a tile out of its slot, a card out of its place in the thread and back to it.
+- **Two phases**: the frame lands, then its details settle top to bottom (`.ws-settle`, `--ws-i` on each).
+- **Interruptible**: a change picks up from where it is; animation never moves focus, and none blocks input except a
+  `morph()` for the length of its own move (the browser's rule for a view transition).
+- **Overshoot** only on marks under 24 px and indicators, never a card, a panel, a field or words.
+- **A stagger runs when content arrives** (first paint, an open, a new answer), never on a re-filter.
+- **Never moves**: content below a chart while its card changes size, a field as it takes focus (the ring appears,
+  nothing else), anything during a resize drag, a scroll reset or a theme change (every surface turns at once).
+
+## Reduced motion, and browsers without a feature
+
+**Reduced motion is still: the final state, at once.** Under `prefers-reduced-motion: reduce` the kit's net makes every
+transition and animation on a kit element instant: presses do not scale, indicators land, folds snap, menus and dialogs
+appear and go, a dashboard shows its end, a chart its final drawing, a shimmer its still ghost (with a word: "Loading
+your calls"), the working dot is still and its words say it. `morph()` and `reorder()` run the update at once (`full`
+still lifts the card). Your own motion goes inside `@media (prefers-reduced-motion: no-preference)` so it is still too;
+in React, `<MotionConfig reducedMotion="user">` turns the springs off.
+
+**A browser without a feature shows the change at once**, never half-moved: without `linear()` the spring transitions
+are dropped; without anchor positioning an indicator jumps to the choice; without `interpolate-size` or
+`::details-content` a fold opens at once; without `@starting-style` a menu or dialog simply appears; without view
+transitions `morph()` and `reorder()` just run the update; without scroll-triggered animation a `.ws-build` plays on
+first paint, and a chart below the fold is whole when it is reached.
+
+## See it
+
+The `Motion` card (`components/Motion/preview.html`, hosted at
+`https://brand-kit-site-production.up.railway.app/latest/components/Motion/preview.html`):
+
+- **Try it**, the playground: a product screen built only from kit components, with a numbered hint at each move
+  (hover a card, press a button, switch Bars / Line, open the menu, open the chart full screen, fold a section, save
+  for a toast, open the drawer, move the chat, sort the list, replay the arrival) and a Slow motion switch that runs
+  everything four times slower.
+- **Reference for developers**: 206 behaviours by Seth's own label, each with North's values, the kit's token, class
+  or helper, a live demo and how close the kit is (exact, close, JS helper, not yet).
+
+Compare what you built against it, side by side. In the kit's repo, `node scripts/check-geometry.mjs --only <Name>
+--hover` shoots each control at rest, hovered and focused, and flags a hover that lifts and anything still moving under
+reduced motion; add `--motion` to run the same pass with motion on, which catches a lift that only plays then.

package/design-system/14-accessibility.md

@@ -4,38 +4,61 @@ The audience skews older and mobile-heavy. These are floors, part of the definit
 
 ## Floors
 
-- **Contrast**: 4.5:1 for words under 24 px (3:1 at 24 px or bold 19 px and up), 3:1 for every border, focus ring, icon or
-  mark that carries meaning. Measure on the cream (#FEFBF9) and on the sunk surface; the pairs are in Colour.
-- **Targets**: WCAG 2.2 (2.5.8, AA) asks 24 by 24 px or the spacing to match. The team's floors are higher: 40 px for a
-  boxed control on a touch screen, 44 px for every act on a public page (`KitButton` large is 45), 24 px
-  tall for words that act. A small face that acts gets 4 px of room round it.
+- **Contrast**: 4.5:1 for words under 24 px (3:1 at 24 px or 18.66 px bold and up), 3:1 for every border, focus ring,
+  icon or mark that carries meaning. Every word token is computed on all eight grounds (cream, white, plate, tray,
+  raised, shell, press, well) in light, night and the navy ground; the tables are in tokens.md and Colour. A word in a
+  tone uses the tone's word token, never the mark's tone (D2).
+- **Focus**: every element that takes keyboard focus shows a 2 px navy ring 2 px outside it on `:focus-visible`
+  (`ws-focus-color`, `ws-focus-width`, `ws-focus-offset`; `shadow-focus-ring` is the same ring as a shadow). Inside a
+  dense row, a well, a list, a segmented track or a clipped container the same ring is drawn inside (`ws-focus-inset`).
+  Never `outline: none` without a visible replacement; a tint alone is not focus. The 2 px gap keeps the ring off a white
+  field. It is 12.3:1 on the cream and at least 10.2:1 on any light ground; in night at least 12.2:1 (D8).
+- **Targets**: WCAG 2.2 (2.5.8, AA) asks 24 by 24 px or the spacing to match. The team's floors are higher, at every
+  pointer for words and on touch for boxes: 40 px for a boxed control on a touch screen (a button, a field, an icon
+  button through its hit area, a segmented item, a tab, a menu item, a date cell); 24 px tall for words that act; 44 px
+  for every act on a public page (`ws-touch-public`; `KitButton` large is 45). The kit's coarse-pointer block sets these;
+  a component's own min-height stays at or above them. A small face that acts gets 4 px of room round it.
 - **Fields**: a white ground (`ws-field`) on the cream, a visible edge and a label above; a field that blends into the
-  page reads as no field. `autocomplete` and the right `type` on every field about the person (1.3.5).
-- **Keyboard**: everything reachable and operable; a visible focus ring (`shadow-focus-ring`, 3 px salmon at
-  20%, with the mid-blue field border); arrow keys inside a tab row, a segmented switch, a menu, a radio group; Home and End to the ends; Escape closes a
-  dialog, a menu, a panel and returns focus to what opened it; Enter saves an inline edit, Escape reverts.
-- **Native first**: `<button>`, `<a>`, `<input type="checkbox">`, `<fieldset>` with a `legend`, `<details>` for a fold, a
-  native `<dialog>`. Roving focus and arrow keys come from Radix where native cannot.
+  page reads as no field. `autocomplete` and the right `type` on every field about the person (1.3.5). A checkbox's edge
+  at rest reaches 3:1.
+- **Keyboard**: everything reachable and operable; arrow keys inside a tab row, a segmented switch, a menu, a radio
+  group, a list with a detail; Home and End to the ends; Escape closes a dialog, a drawer, a menu, a panel and returns
+  focus to what opened it; Enter saves an inline edit, Escape reverts.
+- **Native first**: `<button>`, `<a>`, `<input type="checkbox">`, `<input type="range">`, `<fieldset>` with a `legend`,
+  `<details>` for a fold, a native `<dialog>`, the `popover` attribute for a menu in the top layer. Roving focus and
+  arrow keys come from Radix where native cannot. A sidebar's rows are real links with `aria-current="page"`.
 - **Names**: every icon button has a label (read out and its tooltip); every card is a region named by its title; a chart is
-  a `figure` whose label says the answer and the numbers; a figure that counts up is read at its value at once.
+  a `figure` whose label says the answer and the numbers; a tick strip is hidden and its figure said in words; a figure
+  is read at its value.
 - **Errors**: a message, wired with `aria-describedby` and `aria-invalid`; never a colour change alone. A pending control says
-  `aria-busy`; a toggle says `aria-pressed`; the current tab `aria-selected`; the current page `aria-current`.
-- **Reduced motion**: every keyframe is `motion-safe`; the working signal is still and its words say it (the rest is in
-  Motion).
+  `aria-busy` and stays focusable (`aria-disabled`); a toggle says `aria-pressed`; the current tab `aria-selected`; the
+  current page `aria-current`; an open row `aria-expanded`.
+- **Reduced motion**: under `prefers-reduced-motion: reduce` everything is still (D7) and every state is still
+  reachable; the working signal is still and its words say it. How the kit does it, and what each thing looks like, is
+  in Motion.
 - **Zoom and reflow**: text at 200% (1.4.4) and the page at 320 px wide (1.4.10, the same as 400% zoom): columns stack, the
   panel is the screen, nothing scrolls sideways, nothing is clipped, and every region holding more than it shows scrolls.
   A product drawn at a UI zoom divides viewport heights back by it.
 - **WCAG 2.2 additions**: a sticky header, act or banner never covers the focused control (2.4.11); anything dragged (a
-  sheet, a card on a board) also works by a press (2.5.7); sign-in allows paste and password managers, and a code can be
-  pasted (3.3.8); nothing asked twice in one flow (3.3.7); help sits in the same place on every page (3.2.6).
-- **No hover-only content**: what a hover shows, touch and keyboard show too (1.4.13).
-- **Colour independence**: every state has a word or a mark; success and danger differ in lightness (teal #09787F and brick
-  #B35040), never red and green by hue alone; a falling number is mid blue.
-- **Reading order** is the DOM order is the phone's order: a board's columns are stacked in the order the first column reads.
+  sheet, a card on a board, a slider's thumb) also works by a press or the keys (2.5.7); sign-in allows paste and password
+  managers, and a code can be pasted (3.3.8); nothing asked twice in one flow (3.3.7); help sits in the same place on
+  every page (3.2.6).
+- **No hover-only content**: what a hover shows (a row's acts, a close, a cell's full words in a tooltip, a hover card's
+  reading) touch and keyboard show too, on focus and on a tap (1.4.13). A tip stays while the pointer moves onto it and
+  closes on Escape.
+- **Colour independence**: every state has a word or a mark; success and danger differ in lightness, never red and green
+  by hue alone; a falling number is mid blue; a rating says its band in words ("Strong", "Needs work").
+- **Reading order** is the DOM order is the phone's order: a board's columns are stacked in the order the first column
+  reads; a list that goes above its detail on a phone comes first in the markup.
+- **Dark**: every pair above holds in dark. In a product the theme is the person's choice (`ThemeSwitch`) or their
+  system's; a page drawn dark for everyone (an event page on the navy ground) passes the same pairs. Switching it moves
+  nothing.
 - **Language**: plain words, sentence case, no abbreviations a person outside the trade would not know.
 
 ## Checks
 
-Automated (axe or the Storybook a11y addon) catch the markup and contrast subset; the audit crawl (every page, each
-role, desktop and phone) catches clipping, sideways scroll, fields with no ground and small targets; a keyboard walk, a
-200% zoom, a screen reader pass (VoiceOver on a phone) and a reduced-motion run are done by hand on every new screen.
+Automated (axe or the Storybook a11y addon) catch the markup and contrast subset; the geometry check catches small
+targets, focus that looks like rest, clipping and text off its line (`node scripts/check-geometry.mjs --hover`, light and
+dark); the audit crawl (every page, each role, desktop and phone) catches sideways scroll, fields with no ground and
+pages that cannot scroll. A keyboard walk, a 200% zoom, a screen reader pass (VoiceOver on a phone) and a reduced-motion
+run are done by hand on every new screen.

package/design-system/15-ai-experiences.md

@@ -7,19 +7,23 @@ references, never copies.
 
 Only in its chat (one chat per assistant; an umbrella assistant may sit over several). No in-page assistant, no mission panel, no "ask to change" box
 on a page. A page's one link to the agent is "Ask about this", which opens the chat with the thing attached ("About: Jordan
-Lee"). Voice goes through the one Talk button, which carries the assistant's mark; when a product's own call takes the
+Lee"); a drawer may carry a compact ask field that asks the same chat. The chat sits in its shell (`ChatShell`): a bar
+over a page, docked beside it (the page steps aside, never covered), floating, or full screen; it moves between them as
+itself. Voice goes through the one Talk button, which carries the assistant's mark; when a product's own call takes the
 microphone, the assistant steps aside and comes back after.
 
 ## The turn
 
-The agent's words are plain text, 15/24, no bubble, no avatar beside every line (the face is in the header). The person's
-words sit in a sunk bubble with 12 px corners and navy text. A reply is words plus at most one card, never both saying the
+The agent's words are plain text, no bubble, no avatar beside every line (the face is in the header). The person's words
+sit in a bubble with navy text (`ChatTurn` has the sizes). Starters sit under the composer as `SuggestionChip`s; one long
+conversation is marked by topic (`TopicRail`), never split into threads the person did not ask for. A reply is words plus at most one card, never both saying the
 same thing. An act is a one-line receipt ("Drafted the opener for Nellie"), not a paragraph. A question is not echoed back.
 
 ## Streaming, working and cancelling
 
-A reply arrives as it is written; the working line's typing dots breathe on the one beat; a long job shows its steps as a
-`Stepper` in a card with Stop in its band. Stop is always one press away and says what was kept. The person can type the next
+A reply arrives as it is written; while it works, a status line (`StatusLine`) says who is working, what it is doing and
+the step, and the typing dots breathe on the one beat; a long job shows its steps as a `Stepper` in a card with Stop in its
+band. Under reduced motion the answer shows whole and the status line is still. Stop is always one press away and says what was kept. The person can type the next
 message while a reply streams.
 
 ## Cards from an agent
@@ -27,7 +31,8 @@ message while a reply streams.
 A card is a reference with at most one act: a kind in its head ("Suggestion", "Task", "Question"), a title that says the
 thing, one sentence, facts on a plate, the band with the app's door on the left and the buttons on the right (secondary then
 the one navy). A rich card (a chart, a long list, a comparison) shows as one line in the chat and whole in the panel beside
-it. Asks and pick lists stay in the chat. Taps answer at once (the button shows its pending state).
+it. Asks and pick lists stay in the chat. Taps answer at once (the button shows its pending state). A thread's first
+open follows Page recipes, 22: the app's face and one line, one example on the team's own numbers, the app's tiles.
 
 ## What waits on you
 

package/design-system/16-creativity.md

@@ -20,7 +20,7 @@ system does not have.
 | --- | --- | --- |
 | An operational page or panel (most of the product) | little | the right chart, a sharp title, one well-placed act, cards arriving in order |
 | A chat card | some | a drawing on the dots that says the answer at a glance; a plate that holds exactly the facts |
-| A hero (Team, Progress) | more | a 40 px line, a still faint wash (`ws-cool-glow`, `ws-team-glow`), a vertical-tube chart |
+| A hero (Team, Progress, a report's score) | more | a 40 px line or the 96 px score, a still faint wash (`ws-cool-glow`, `ws-team-glow`), a vertical-tube chart |
 | An entry page or a welcome step | more | the three faces glancing round, sample cards rising in beside |
 | A guide or a walkthrough | more | a drawn board, the assistant talking it through |
 | A report or a launch moment | the most | an expressive composition, imagery, a sequence of cards that tells one story |