trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/domains/motion/guards.md

@@ -0,0 +1,162 @@
+# Guards
+
+Reduced motion, content that starts hidden, and set pieces: where motion can take something away. Each section's fallbacks must all exist, because each covers a different reader.
+
+## Reduced motion: substitute, don't subtract
+
+For every animation, ask what it communicates, then find the cheapest thing that still communicates it.
+
+| Original | Reduced path | Why |
+|---|---|---|
+| Spring slide, re-targeting highlight | Flat tween at `duration.state` | The move is the message; the physics is decoration |
+| Scale, squash or slide entrance | Plain fade at the same tier | Presence still shown; nothing travels |
+| Blur cross-fade | Cross-fade with `blur(0px)` at both ends | Blur is the trigger; the fade isn't |
+| Reveal-on-scroll | Off; content in its final visible state | The animation is the whole effect |
+| Route fade, ambient loop | Off | Ditto |
+| Live-state loop (level bars, a travelling stroke) | Held still on a representative frame | Shape and colour already say "live"; the movement only restates it |
+| Hover lift whose motion is the whole interaction | No hover variant at all | Static is correct |
+| Theme cross-fade | Instant | Whole-viewport interpolation |
+| Programmatic smooth scroll | `behavior: "auto"` | Whole-viewport motion is among the strongest triggers |
+| Icon fill cross-fade | Instant swap | The state is the message |
+| Press scale at `duration.instant` | Keep it | Small, short, below any threshold of concern |
+| Close tween (`ease.exit`) | Keep it | Already flat and short |
+| Set piece | Never plays | A flourish by definition; don't substitute a quieter one |
+
+### CSS
+
+```css
+/* Branch the travel, keep the fade */
+:root { --motion-travel: 12px; }
+@media (prefers-reduced-motion: reduce) { :root { --motion-travel: 0px; } }
+
+/* Reveal: off entirely — resolving to the FINAL state, not the initial one */
+@media (prefers-reduced-motion: reduce) {
+  .reveal { opacity: 1; transform: none; transition: none; }
+}
+```
+
+The theme cross-fade inverts the pattern: its whole rule sits inside `prefers-reduced-motion: no-preference`, so it's opt-in.
+
+### Libraries
+
+```tsx
+// Motion
+const reduce = useReducedMotion();
+transition={reduce ? { duration: <duration.state> } : <spring.snappy>}
+whileHover={reduce ? undefined : "hover"}        // undefined registers no listener; "rest" still does
+```
+
+```ts
+// GSAP
+const mm = gsap.matchMedia();
+mm.add({ reduce: "(prefers-reduced-motion: reduce)", ok: "(prefers-reduced-motion: no-preference)" }, (ctx) => {
+  const { reduce } = ctx.conditions!;
+  gsap.from(".sheet", { opacity: 0, y: reduce ? 0 : 12, duration: 0.2, ease: "power3.out" });
+});
+```
+
+```ts
+// React Spring
+const reduce = useReducedMotion();
+const styles = useSpring({ opacity: open ? 1 : 0, y: open || reduce ? 0 : 12, config: snappy });
+```
+
+`MotionConfig reducedMotion="user"` (Motion) drops transforms and keeps opacity, a reasonable floor; `Globals.assign({ skipAnimation: true })` (React Spring) drops everything, the regression this section prevents. Neither replaces the per-component branch.
+
+### Imperative APIs
+
+Nothing called from JavaScript reads the media query: `scrollIntoView`, `scrollTo`, `Element.animate`, a GSAP timeline built outside `matchMedia`, a canvas or WebGL loop. Pass the preference in, and listen for its `change` event if the component lives long.
+
+### Testing
+
+macOS: Accessibility → Display → Reduce motion. iOS: Accessibility → Motion. Windows: Accessibility → Visual effects → Animation effects. Chrome DevTools: Rendering → Emulate `prefers-reduced-motion`. Walk the whole interface with it on, looking not for jank but for a menu that appears with no sign it opened, or a section that never appears.
+
+Related preferences take the same shape elsewhere: `prefers-reduced-transparency` (translucent surfaces become opaque) in the depth guide, `prefers-contrast: more` in the colour guide.
+
+## Content that starts hidden
+
+A reveal every reader sees:
+
+```css
+.reveal { opacity: 0; translate: 0 var(--reveal-travel);
+          transition: opacity <duration.overlay> <ease.colour>, translate <duration.overlay> <ease.standard>; }
+.reveal[data-in] { opacity: 1; translate: 0 0; }
+@media (prefers-reduced-motion: reduce) { .reveal { opacity: 1; translate: none; transition: none; } }
+@media print { .reveal { opacity: 1; translate: none; } }
+```
+
+```html
+<noscript><style>.reveal { opacity: 1 !important; translate: none !important; }</style></noscript>
+```
+
+```ts
+export function observeReveals(): () => void {
+  const els = document.querySelectorAll<HTMLElement>(".reveal:not([data-in])");
+  if (typeof IntersectionObserver === "undefined") {
+    els.forEach((el) => el.setAttribute("data-in", ""));   // never leave content hidden behind a feature check
+    return () => {};
+  }
+  const io = new IntersectionObserver((entries) => {
+    for (const e of entries) {
+      if (!e.isIntersecting) continue;
+      e.target.setAttribute("data-in", "");
+      io.unobserve(e.target);                                // one-shot: re-animating on scroll-back is nauseating
+    }
+  }, { threshold: 0, rootMargin: "0px 0px -40px 0px" });
+  els.forEach((el) => io.observe(el));
+  return () => io.disconnect();
+}
+// Call again on every client-side navigation, keyed on the path.
+```
+
+Each guard saves a reader who would otherwise see nothing:
+
+| Guard | The reader it saves |
+|---|---|
+| `threshold: 0` with a root margin | Anyone reading an element taller than the viewport. A threshold is a fraction of the element's *own* area, and an element can never exceed viewport ÷ its height, so `0.1` is unreachable for anything over ten screens tall — a long article, exactly. A root margin works at any height |
+| `data-in`, not a class | Anyone whose element re-renders. A framework rewrites `class` from its own value on every render, dropping a class added from outside; attributes it doesn't render, it leaves alone |
+| No-observer fallback | Old or stripped-down browsers |
+| `<noscript>` reset | Readers with JavaScript off, and crawlers; a feature check can't catch "the script never ran" |
+| Print rule | Anyone printing; scroll-triggered content prints blank without it |
+| Re-observe on navigation | Anyone arriving on a second page client-side |
+| Reduced-motion rule | Readers who asked for less motion |
+
+The re-render failure hides well: a utility applied during a hover can outrank the reveal's opacity, so the page breaks only when the pointer *leaves*. Test the state after the interaction, not during it.
+
+**Any CSS that hides content pending JavaScript needs a `<noscript>` reset**, whether a reveal, a hydration class or a skeleton.
+
+### Collapsibles
+
+Animate the height (`grid-template-rows: 0fr` ↔ `1fr`) and keep the content mounted, `inert` and `aria-hidden` while shut, so a tab press or screen reader meets the trigger, not hidden prose, and search still finds the content in the served HTML.
+
+## Set pieces
+
+Decide before the first pixel, in a blocking inline script in the document head:
+
+```html
+<script>
+  (function () {
+    try {
+      if (matchMedia("(prefers-reduced-motion: reduce)").matches) return;   // beats any replay override
+      if (location.hash) return;                        // a deep link is someone asking for that section
+      if (sessionStorage.getItem("intro-seen")) return; // once a session
+      document.documentElement.dataset.intro = "on";    // CSS shows the overlay at paint
+    } catch (e) {}                                      // storage can throw; failing means no set piece
+  })();
+</script>
+```
+
+The component only *ends* it — flips the attribute — and records "seen" in its completion callback; recording on start lands in the same render as the play and cancels the animation it records. Write "seen" under reduced motion too, so the reader's next tab doesn't surprise them.
+
+**Branch client-only flags on the transition, never on a rendered style.** "Has this played?" is false on the server for everyone and true on the client for most: a style branched on it paints differently on each, while a branched transition paints the same and differs only in how long the change takes:
+
+```tsx
+variants={{
+  shut: { opacity: 0, y: 6 },                                           // constant on both renders
+  open: { opacity: 1, y: 0, transition: { duration: reduce ? 0 : firstTime ? <set-piece> : <duration.state> } },
+}}
+```
+
+A filling CSS animation (`animation-fill-mode: both`) can't be transitioned out of with a plain declaration, because the animation's end state wins; replace the animation to end it.
+
+**Nothing waits behind it.** The page underneath is rendered and interactive; the skip link is the first focusable element, and focusing it ends the piece; any key or click ends it at once.

package/plugins/keyline/skills/keyline/domains/motion/guide.md

@@ -0,0 +1,198 @@
+# Interface Motion
+
+Motion in an interface has one job: **make a change legible.** Not to delight, not to demonstrate craft. Something opened, moved or was chosen, and the animation lets the user follow it. If removing an animation leaves the user no less clear about what happened, remove it.
+
+The constraint also makes the few places motion *is* spent land hard, because nothing around them competes. The laws hold under every preset; the dials are where an essay, a dashboard and a launch page legitimately differ.
+
+## Before you start
+
+Reads `DESIGN.md` `## Motion`.
+
+## Laws
+
+### 1. Motion makes a change legible, or it goes
+
+**Every animation must answer "what just changed?" — and one that answers nothing is removed, not shortened.** Motion is the strongest attention signal an interface has; spent on nothing, it trains the eye to ignore it, and the animation that matters — a save confirming, a row arriving — goes unseen. A pulsing "New" badge beside a live sync indicator is the classic: the user tunes out both. Nothing animates to attract attention, and nothing loops except to report a state still in progress, like a spinner or a progress bar; any other loop is decoration, under law 4.
+
+**Paused means still.** A loop reporting a live state — level bars on a recorder, a stroke travelling round a card while something works — stops or settles low when that state pauses; still moving, it claims the thing is still listening. Only a progress indicator loops through a wait, because waiting is its state. On hover or focus a live indicator morphs in place into the action that ends it — bars into a stop square — so the control's next move appears where the eye already is.
+
+Hover travel answers nothing either: a card rising under the pointer claims it moved, or can be picked up. Hover is a wash; how far, if at all, a preset lets a hovered thing travel is a dial (`domains/motion/ladder-and-curves.md`).
+
+→ Live indicators, pausing and the morph to their action: `domains/motion/patterns.md`
+
+### 2. Duration grows with how much of the screen changes
+
+**Duration is set by how much the eye has to re-read, never by how important the element feels, and every tier is longer than the one below it.** Tie it to importance and the primary button gets a 500ms flourish, the navigation 150ms: the most-used control is the slowest, and nothing feels like one system.
+
+| Role | What changes |
+|---|---|
+| `duration.instant` | A pressed element's own response; a focus ring |
+| `duration.micro` | One property with no position — opacity on hover |
+| `duration.state` | One small element — colour, background, icon swap, small transform |
+| `duration.popover` | A small element *and* its surroundings — a menu, a hover card |
+| `duration.overlay` | A large region entering or collapsing — a sheet, a panel, a reveal |
+| `duration.theme` | Everything on the page at once |
+
+An element tied to a larger change takes its tier: a disclosure chevron runs at `duration.popover` and lands with the panel opening below it. Hover is no exception: a wash across a large card takes a longer tier than a row swept in bulk (Dials). `duration.route` is the one tier size doesn't set; law 3 caps it. The numbers are dials; the ordering is not.
+
+**`duration.theme` runs only when the page itself switches theme**, under a class held on the root for the length of the switch. Everyday colour transitions leave out the page background and are suspended during a theme change: otherwise an OS switch by media query, which has no class to hold, cross-fades every control at its own duration while the page around it snaps.
+
+### 3. Nothing repeated waits on an animation
+
+**Anything a user does many times a session must never wait on motion: feedback starts on the input, every transition can be interrupted, and anything on the path to content is capped.** An animation is watched the first time and endured the fortieth: a tab switch that slides for 300ms is charming once and a tax by lunchtime, and a dialog that ignores clicks until its exit completes turns a double-click into a missed one.
+
+- Press feedback lands on `pointerdown` at `duration.instant`; waiting for `click` feels dead.
+- Controls stay live while animating: a new target re-targets the motion in flight, never queues.
+- A route transition sits between "I clicked" and "I can read": opacity only, never longer than `duration.overlay`, the incoming page interactive from its first frame.
+
+### 4. Off-ladder motion names its exemption
+
+**The ladder is for state. Anything longer must be classed as not-state — the subject of the moment, a set piece, or ambient — with the class written down beside it.** Forced onto the ladder these get worse; unclassed, a 900ms flourish ends up on a menu.
+
+| Class | What it is | What it must earn |
+|---|---|---|
+| Subject | The motion *is* the content being looked at — a dissolve between photographs, a chart drawing itself once | It isn't chrome reporting a change; the same component's *state* changes stay on the ladder |
+| Set piece | A greeting, a first-run sequence, a launch moment | Law 15: once a session, blocks nothing |
+| Ambient | A background loop in a hero | Never behind text being read, paused off screen, absent under reduced motion; `expressive` only. Where nothing can pause it off screen, it is finite — a few iterations, then rest — or removed |
+
+The test for all three: **would a user see this more than a handful of times a session?** If yes, it's state, and on the ladder.
+
+### 5. One standard curve; colour never overshoots
+
+**Everything that moves shares `ease.standard`; colour and opacity use `ease.colour`; and no curve may pass its target on a property with a floor.** One shared curve makes unrelated elements moving together feel like one mechanism; the urge for a second bezier is the urge for a spring, where character belongs (law 6).
+
+Colour has no mass, so overshoot on a background is a wobble in the light; opacity clamps at 1, so overshoot is a wasted tail that mistimes the fade. On a property with a hard floor — `blur()` or `brightness()` toward 0, a radius toward 0, a scale that mustn't invert — browsers clamp rather than error, and the track *stalls* for its last few frames, which is hard to trace. **Check what else rides the curve:** transform with opacity is fine; add a filter and the whole track needs a monotone curve. Whether `ease.standard` overshoots is a dial; this law bites only where it does.
+
+### 6. Springs are named by character, and move only things with position
+
+**A spring is named for how it feels (`spring.snappy`, `spring.soft`), used wherever something can be re-targeted mid-flight or grabbed, and never drives opacity, colour or filter.** A bezier restarts from a standstill at each new target, so a highlight chasing the pointer across five items stutters five times; a spring keeps its velocity. **If the user could grab it, or it could change target mid-flight, it's a spring.** A number isn't a decision: `spring-400-30` says nothing about when to reach for it. Opacity splits out as its own short tween, because a spring's overshoot on opacity hitches at the tail of every fade.
+
+Springs are wrong for discrete flips with no travel, anything that must land in step with a bezier, and long distances at low stiffness: a soft spring across 800px takes over a second and feels broken.
+
+→ Curves and springs per preset in four libraries, the opacity split in code, squash and stretch, and tuning by symptom: `domains/motion/ladder-and-curves.md`
+
+### 7. Exits get out of the way
+
+**Closing is faster than opening, flat, and eases in — no spring, no overshoot, and it travels less far.** Opening answers the user's intent and can afford character; closing comes after they've moved on, so a bounce reads as reluctance and stands in their way, and a disappearing element needn't travel the full distance. In the Glass preset a menu opens on a spring of about 400ms and closes on a 130ms `ease-in` tween. The law is for things leaving; a hover wash fading behind a pointer that has already moved on stands in nobody's way, so its leave may run longer than its arrival.
+
+### 8. Where identity persists, the element travels
+
+**If the same thing is on screen before and after a change, it moves between the two positions rather than fading out in one place and in at another.** Per-item hover backgrounds across a row of icons give overlapping fades, one brightening as its neighbour dims: a stutter, not an object. One shared highlight that re-targets its position and size can't flicker, because there is only one; it skips its mount animation, or it flies in from the corner on first paint.
+
+A view switch keeps the reader's place (layout law 9), so **measure the reading position before the outgoing layout unmounts** and open the incoming one there, neither end stretched to the other's aspect. A shared element is the wrong tool for a lone item, items that reflow while hovered, items in different scroll containers, and a grid crossed diagonally.
+
+→ Highlight, tooltip and layout-switch patterns in View Transitions, Motion `layoutId` and GSAP Flip: `domains/motion/patterns.md`
+
+### 9. One highlight travels between hovered and current
+
+**Where a group shows both a current item and the one under the pointer — a nav, a segmented control — one highlight travels with the pointer and comes to rest on the current item, rather than a second treatment appearing beside the first.** What current looks like is colour law 7's, never re-picked here, and weight never changes on hover (type law 5). Previewing a choice and reporting one are the same gesture a beat apart, so they share one moving shape (law 8): two signals each doing half the job, never one doing both. Outside such a group, hover is a wash (the dials). Nothing is filled because it looks better.
+
+A filled icon is the same outline with its interior painted, cross-faded in place at `duration.popover` on `ease.colour`, so the silhouette never moves. Marks that can't take it — a brand's official solid mark, a chevron with no interior, a lone toggle with nothing to be picked out from — signal another way. **Fill that distinguishes nothing is just weight.** Nor is a step from `text.secondary` to `text.primary` a signal (colour law 6).
+
+### 10. Reduced motion is a branch with a substitute
+
+**Every animated component reads `prefers-reduced-motion` and takes its own reduced path that still communicates the change; a global off switch is a regression.** The preference exists because large-area and accelerating motion causes nausea and dizziness, not to remove visible state: `* { animation: none !important }` strips the signals with the decoration, and a menu appears with no sign it opened.
+
+Imperative APIs — `scrollIntoView`, `scrollTo`, `Element.animate`, a GSAP timeline, a canvas loop — don't read the preference; pass it in. Motion's `MotionConfig reducedMotion="user"` and React Spring's `skipAnimation` are a floor, not the plan.
+
+→ Every substitute in CSS, Motion, GSAP and React Spring, and how to test: `domains/motion/guards.md`
+
+### 11. Motion never owns whether content is visible
+
+**Any style that hides content until an animation runs must resolve to visible whenever that animation can't run** — no JavaScript, no observer, reduced motion, print, or an element too tall to trip its trigger. The failure is not a plainer page but a correct document the reader can't see. The usual causes: an observer threshold a very tall section can't reach, and a class added outside the framework, which a re-render rewrites away.
+
+So reveals are one-shot, with a zero threshold and a root margin, re-observed on client navigation, marked by a data attribute the framework doesn't own, and reset by a `<noscript>` style and a print rule. A collapsible animates its height but stays mounted (layout law 11).
+
+### 12. Scroll work runs once a frame, and never hides what it can't bring back
+
+**Each scroll-driven behaviour is one passive listener collapsed to one `requestAnimationFrame`, with a dead zone on anything that toggles on direction — and nothing collapses on a device that can't expand it again.** A rAF flag gives one measurement per painted frame, which no time-based throttle can. A dead zone of a few pixels stops trackpad jitter toggling a collapsing header forever. Whether it may collapse at all on touch is layout law 8.
+
+### 13. Animate what the compositor can; escalate one element, never a view
+
+**Animate `transform` and `opacity`, list every transitioned property by name, justify any layout property you animate, and when the DOM can't carry a transition, move one decorative element to the GPU — never the view.** `transition: all` catches properties you never meant, including layout ones a parent adds later. Animating `width` is defensible only where nothing reflows, as on one absolutely positioned element outside the flow; otherwise use a transform, or the `0fr`↔`1fr` grid track to "animate to auto". The moving wrapper and a translucent surface are separate elements (depth law 9).
+
+GPU escalation is for one travelling element with no semantics of its own, never a view of tiles, whose semantics a canvas can't carry and whose textures cost hundreds of megabytes; its setup returns `null` rather than throwing, the path reduced motion and no-WebGL already take.
+
+→ The scroll shape with hysteresis, scroll spies, the grid technique, GPU rules and bundle discipline: `domains/motion/performance.md`
+
+### 14. Pointer gaps get intent, not luck
+
+**A hover-opened element gets a close grace period of about 100ms, or a hover bridge across the gap; the timer is cleared on unmount and on navigation; and whatever hover reveals, focus reveals too, with a separate path for touch.** Without it, the menu closes in the gap; where trigger and menu touch, a bridge of padding is cheaper, because the pointer never leaves. A timer left running across a navigation reopens a stale menu on the next page. Delay the *close*, never the open (law 3).
+
+### 15. Set pieces play once and block nothing
+
+**A greeting, a first-run sequence or a launch flourish plays at most once a session, is decided before the first paint, skips for deep links and reduced motion, and never covers content or the skip link.** Its long budget is defensible only because it never recurs. Gate it in a blocking inline script that sets a root attribute for CSS to answer at paint: the server can't see session storage, and a component decides a frame too late. Record "seen" on *completion*, or the write cancels the animation it records; branch client-only flags on the *transition*, never a rendered style, or server and client paint differently. Focusing the skip link, pressing a key or following a link ends it at once.
+
+→ The inline gate, the hydration-safe variant and the "seen" bookkeeping: `domains/motion/guards.md`
+
+## Dials
+
+| Dial | editorial | product | expressive |
+|---|---|---|---|
+| `duration.micro` | 100ms | 80ms | 120ms |
+| `duration.state` | 150ms | 100ms | 200ms |
+| `duration.popover` | 200ms | 150ms | 280ms |
+| `duration.overlay` | 300ms | 200ms | 450ms |
+| `duration.route` | 250ms opacity fade | none | 400ms fade; directional only where routes have a real order |
+| `duration.theme` | 400ms | 250ms | 600ms |
+| Exit duration | ≈ ⅔ of the entrance (popover exit 130ms) | 100ms | 180ms |
+| `ease.standard` | `cubic-bezier(0.22, 1, 0.36, 1)` — no overshoot | `cubic-bezier(0.2, 0, 0, 1)` — no overshoot | `cubic-bezier(0.34, 1.2, 0.64, 1)` — slight overshoot |
+| `ease.colour` · `ease.exit` | `ease` · `ease-in` | `ease-out` · `ease-in` | `ease` · `ease-in` |
+| Springs | `snappy` 0.15 / 0.35s, `soft` 0.2 / 0.45s, one `playful` 0.3 / 0.5s | `snappy` 0 / 0.25s, for drag, throw and a re-targeting indicator only | `snappy` 0.2 / 0.4s, `soft` 0.3 / 0.6s, `playful` 0.45 / 0.7s |
+| Reveal-on-scroll | 8px travel, `duration.overlay`, no stagger | none | up to 24px, stagger ≤ 80ms, whole group ≤ 600ms |
+| Press feedback | scale 0.96 on small controls | `surface.pressed` step, no scale | scale 0.92–0.95; wider than ≈ 200px, `scale(0.98)` or a 1px translate |
+| Hover on a card or large surface | a wash, 200ms in · 250ms out; no travel | a wash, 200ms in · 250ms out; no travel, no shadow change | a wash, 280ms in · 350ms out; a lift ≤ 4px on primary navigation only |
+| Set pieces | at most one on the site | none | a few, each named |
+| Ambient loops | none | progress indicators, and live-state indicators while the state is live | a hero only, paused off screen; where nothing can pause it, one finite motion — a few iterations, then rest |
+| Sound | absent, or opt-in behind a visible toggle | absent | opt-in, default off, visible toggle |
+
+Springs are Motion's `bounce / duration`.
+
+The presets move the tiers together, so law 2's ordering survives any row. Each set piece and ambient loop is a named entry in `DESIGN.md` with its law 4 class; exceeding the preset's allowance is a decision with a reason, not a drift.
+
+→ Why each dial sits where it does: `domains/motion/ladder-and-curves.md`. Sound's rules: `domains/motion/patterns.md`
+
+## Building it for a project
+
+1. **Read the preset and its areas.** A `product` app with an `expressive` marketing area gets two ladders; the area's paths say which a file uses.
+2. **Inventory what moves**, built or planned, with what each changes and how much screen it covers. The ladder comes from this list, not a token file.
+3. **Assign tiers by area** (law 2), promoting anything tied to a larger change. What doesn't fit is a stray to snap or an exemption to class under law 4; nothing is left unclassed.
+4. **Take the preset's numbers** and check them against the project: a consistent existing value within ~20ms of a dial is kept and recorded; scattered strays snap to the ladder. Confirm the tiers strictly ascend.
+5. **Fix the curves.** One `ease.standard`, one `ease.colour`, `ease.exit` only if exits differ. If the standard curve overshoots, find every track carrying a filter or floored property.
+6. **Name only the springs the inventory needs**, by character; with no drag and no re-targeting indicator, maybe none.
+7. **Write the reduced path for every inventory row** (law 10), and the visible end state for everything that starts hidden (law 11).
+8. **Emit tokens in the project's mechanism**: custom properties, a Tailwind theme or a JS theme object.
+
+→ Per-preset tables, the *Ledgerline* token file with Tailwind mappings, and a derivation from a messy codebase: `domains/motion/ladder-and-curves.md`
+
+## Auditing existing code
+
+Collect evidence, then report:
+
+- **Off-ladder durations:** `rg -n "\d+ms|duration[-:]\s*\d|duration-\[" src`; each value is a tier, a stray or an unclassed exemption.
+- **Curves:** `rg -n "cubic-bezier|ease-in-out|ease:" src`; more distinct beziers than the preset's two or three is a finding, as is an overshooting one on a track with a filter.
+- **Entrances on `ease-in`**, exits on springs: `rg -n "exit=|ease-in" src`.
+- **Opacity inside a spring:** `type: "spring"` with no per-property opacity override.
+- **`transition: all`**, `transition-all`, animated `width|height|top|left|margin`; a colour transition on the page background outside the theme switch's class.
+- **Reduced motion:** animated components against `useReducedMotion|prefers-reduced-motion|matchMedia` branches; global `animation: none !important`; `scrollIntoView|scrollTo|\.animate\(` with no branch.
+- **Hidden until animated:** `opacity: 0` initial states, reveal classes, `threshold:` above 0, `classList.add` on framework-rendered elements; a missing `<noscript>` reset or print rule.
+- **Scroll:** `addEventListener\("scroll"` without `passive` or rAF, or several per behaviour.
+- **Loops:** `infinite`, `repeat: Infinity`, `setInterval` driving UI; an ambient `infinite` that nothing pauses off screen.
+- **Hover:** timers never cleared on unmount; any hover style, decoration included, outside a `(hover: hover) and (pointer: fine)` gate; `rg -n "hover:-?translate|:hover[^{]*\{[^}]*transform" src` for cards that lift where the preset says wash.
+- **Live indicators:** loops with no paused branch.
+
+Then tab through with reduced motion on, and with JavaScript off, for anything that never appears or appears with no sign it opened. Check hover states on *leave* as well as enter; the leave state is where transition-property mistakes live.
+
+## Writing back to DESIGN.md
+
+Under `## Motion`: ladder rows (role, name here, value, used for); curves; springs by character; the reduced-motion policy in a sentence; each off-ladder entry as a row in the **Named exemptions** table (exemption, values, why — its law 4 class and where it plays), which the detector reads; the sound policy, if any.
+
+Under `## Decisions`, besides moved dials: a set piece added, sound turned on.
+
+## Checklist
+
+- [ ] Live indicators morph in place to their action on hover and focus.
+- [ ] `duration.theme` runs only under the page's own switch class; everyday colour transitions leave out the page background.
+- [ ] Shared elements skip their mount animation; layout switches keep the reading position.
+- [ ] Set pieces record "seen" on completion and never block the skip link.
+- [ ] Sound only if the preset allows it, off by default behind a visible, persisted toggle.

package/plugins/keyline/skills/keyline/domains/motion/ladder-and-curves.md

@@ -0,0 +1,139 @@
+# Ladder, curves and springs
+
+The numbers behind the `## Dials` table, the reasoning that sets them, and how to derive a project's ladder from what it already ships.
+
+## Why area, not importance
+
+The eye needs time in proportion to the distance it travels and the area it re-reads: a background colour changing under a 40px button is one fixation, a panel sliding in is a new region to parse, and the whole page changing colour is a re-read of everything.
+
+| Area changing | Role | editorial | product | expressive |
+|---|---|---|---|---|
+| A pressed element's own fill or scale | `duration.instant` | 0 | 0 | 0 |
+| One property, no position | `duration.micro` | 100ms | 80ms | 120ms |
+| One small element | `duration.state` | 150ms | 100ms | 200ms |
+| A small element and its surroundings | `duration.popover` | 200ms | 150ms | 280ms |
+| A large region entering or collapsing | `duration.overlay` | 300ms | 200ms | 450ms |
+| The viewport, on the critical path | `duration.route` | 250ms | — | 400ms |
+| Everything, at once | `duration.theme` | 400ms | 250ms | 600ms |
+
+`duration.route` sits below `duration.overlay` because law 3 caps it: a page transition is latency the user blames on the product. Below ~200ms a full-viewport fade looks like a rendering glitch, so `product` drops it rather than shortening it.
+
+**If unsure which tier, it's `duration.state`**, which does most of the work in every preset. `product` is shortest because its user is fluent and repeats everything; `expressive` is longest on entrances because they are usually seen once.
+
+**Above ~150ms on a hover state**, a fast pointer across a list or a dense table leaves a visible trail. That caps `duration.micro` and `duration.state` for anything hovered in bulk, in any preset, so `expressive` spends its longer `duration.state` on entrances and single controls and keeps list-row hovers at `duration.micro`. Above ~200ms, `editorial`'s `duration.state` makes reading chrome feel heavy.
+
+**A large surface is the opposite case.** A row is a thin strip the pointer crosses; a card on a board is an area the eye rests on, and the same 80ms colour change across it looks instant, not smooth. The area sets the tier here as everywhere, so a card's wash takes about 200ms in and a slower 250ms out: the pointer has already left, the fade blocks nothing, and a sweep across the board fades behind it instead of strobing. Name only `background-color` (and `border-color` if it moves), never `transform` or `box-shadow`: in `product` a card that rises or darkens its shadow under the pointer claims it can be picked up. `expressive` lets primary navigation lift, because there the travel is the invitation.
+
+## Exits
+
+An exit runs at about two-thirds of its entrance, on `ease.exit` (an `ease-in`, accelerating away, so the element reads as leaving rather than deleted), and travels about half the entrance's offset.
+
+| Entrance | editorial exit | product exit | expressive exit |
+|---|---|---|---|
+| A menu or popover | 130ms | 100ms | 180ms |
+| A sheet or panel | 200ms | 130ms | 280ms |
+
+## Curves
+
+| Role | editorial | product | expressive |
+|---|---|---|---|
+| `ease.standard` | `cubic-bezier(0.22, 1, 0.36, 1)` | `cubic-bezier(0.2, 0, 0, 1)` | `cubic-bezier(0.34, 1.2, 0.64, 1)` |
+| `ease.colour` | `ease` | `ease-out` | `ease` |
+| `ease.exit` | `ease-in` | `ease-in` | `ease-in` |
+
+`editorial`'s curve decelerates hard and never leaves [0, 1], so it is legal on every property. `product`'s front-loads even more, so a 100ms transition has visibly arrived by 50ms, and doesn't overshoot either. `expressive`'s end control point above 1 overshoots slightly — physical on a transform, never a bounce — which costs law 5's floor check on every track.
+
+**Where `ease.standard` overshoots, find every track carrying a floored property** — `blur()`, `brightness()`, `saturate()` toward 0, a radius toward 0, a scale that must not invert — and give it a monotone curve. `cubic-bezier(0.16, 1, 0.3, 1)` arrives as decisively without passing its target: the same intent, legal for the property, not a second character. Record it in `DESIGN.md` as a proposed role, `ease.floor`, if needed.
+
+A theme cross-fade is always monotone too: it is the largest change available, and overshoot on colour is a wobble in the light.
+
+### Library equivalents
+
+| | CSS | Motion | GSAP |
+|---|---|---|---|
+| A bezier | `cubic-bezier(a, b, c, d)` | `ease: [a, b, c, d]` | `CustomEase.create("standard", "a,b,c,d")` |
+| `ease-in` | `ease-in` | `"easeIn"` | `"power1.in"` |
+| `ease-out` | `ease-out` | `"easeOut"` | `"power1.out"` |
+
+React Spring is physics-only; use a spring config, or its `easings` with a `duration` for the colour track.
+
+## Springs
+
+Two vocabularies describe the same physics:
+
+- **`bounce` + `duration`** (Motion): `bounce` 0 is critically damped and `duration` is roughly the settle time, so arrival is predictable beside a bezier.
+- **`stiffness` + `damping` + `mass`** (Motion; React Spring's `tension` / `friction` / `mass`): needed when the relationship between two springs is the point, as in squash and stretch.
+
+For intuition rather than conversion, damping ratio ζ = damping ÷ (2 · √(stiffness · mass)), and bounce ≈ 1 − ζ. Tune each spring in one vocabulary.
+
+| Character | Used for | editorial | product | expressive |
+|---|---|---|---|---|
+| `spring.snappy` | A shared element re-targeting; a dragged item released | bounce 0.15, 0.35s · 400 / 34 | bounce 0, 0.25s · 600 / 49 | bounce 0.2, 0.4s · 380 / 31 |
+| `spring.soft` | A panel or card entering | bounce 0.2, 0.45s · 260 / 26 | — (tween) | bounce 0.3, 0.6s · 180 / 19 |
+| `spring.playful` | The one delight beat | bounce 0.3, 0.5s · 300 / 24, once | — | bounce 0.45, 0.7s · 220 / 16 |
+
+Stiffness / damping pairs assume mass 1. `snappy` stays near the floor of "perceptibly springy": a highlight is a thing moving, not arriving, and one that settles at every stop draws attention to itself instead of what it marks. `product` keeps springs to real momentum — a dragged card, a thrown sheet — because a fluent user notices a spring's variable settle time. `editorial`'s one `playful` spring is one delight beat: against restraint, one exuberant interaction reads as craft, three as a template.
+
+```ts
+// Motion
+const snappy = { type: "spring", bounce: 0.15, duration: 0.35 };
+// Opacity always split out as its own short tween (in GSAP, a separate tween beside the move)
+transition={{ ...<spring.snappy>, opacity: { duration: <duration.micro>, ease: <ease.colour> } }}
+// React Spring
+const snappy = { tension: 400, friction: 34 };
+// GSAP has no spring solver; to re-target use gsap.quickTo(el, "x", { duration: 0.35, ease: "power3.out" }),
+// which re-targets smoothly from the current value.
+// CSS: linear() can sample a spring's curve but can't re-target mid-flight — entrances only.
+```
+
+### Tuning by symptom
+
+Change one control at a time.
+
+| Symptom | Fix |
+|---|---|
+| Floaty, slow to commit | ↑ stiffness, or ↓ duration |
+| Wobbles too many times | ↑ damping, or ↓ bounce |
+| Snaps, feels mechanical | ↓ damping slightly |
+| Slow to start moving | ↓ mass |
+| Too eager, no weight | ↑ mass |
+| Flickers at the end of a fade | opacity is still on the spring — split it out |
+| Takes over a second across a long distance | raise stiffness with distance, or use a tween |
+
+### Squash and stretch
+
+A light, underdamped spring on the grow axis (high stiffness, low damping, mass below 1) and a stiffer, heavily damped one on the cross axis: through the overshoot the element is briefly taller and narrower, then settles — the animation principle from physics, interruptible for free, with deformation reading as mass. Travel on the grow axis rides the same spring as its scale, or the anchored edge detaches from the trigger mid-flight. In the Glass preset the pair is 620 / 19 / 0.85 against 380 / 30. `editorial` may spend this once; `product` never; `expressive` may use it on menus throughout.
+
+## Emitting tokens
+
+A fictional project, *Ledgerline* — bookkeeping software on `product`, with `app/(site)/**` on `expressive`. The app's tokens, in its existing `--motion-*` style:
+
+```css
+:root {
+  --motion-micro: 80ms;     /* duration.micro   — row opacity on hover */
+  --motion-state: 100ms;    /* duration.state   — cell colour, icon swaps */
+  --motion-popover: 150ms;  /* duration.popover — menus, date picker */
+  --motion-overlay: 200ms;  /* duration.overlay — inspector panel, sheets */
+  --motion-theme: 250ms;    /* duration.theme */
+  --motion-exit: 100ms;     /* duration.exit    — ease-in, flat */
+  --motion-ease: cubic-bezier(0.2, 0, 0, 1);  /* ease.standard */
+  --motion-ease-colour: ease-out;              /* ease.colour */
+  --motion-travel: 12px;    /* a sheet's slide as it fades in */
+}
+@media (prefers-reduced-motion: reduce) {
+  :root { --motion-travel: 0px; }  /* still fades, no longer slides */
+}
+```
+
+In Tailwind v4, `--ease-*` in `@theme` generates `ease-*` utilities; durations have no theme namespace, so use `duration-(--motion-state)`. A v3 config extends `transitionDuration` and `transitionTimingFunction`; a JS theme object carries `motion.duration.state` and `motion.spring.snappy` beside its colours.
+
+## Deriving a project's ladder from its code
+
+A worked case: a codebase with 31 distinct durations.
+
+1. **Cluster by value and by what moves.** 150ms, 160ms and 175ms are all hover colours: one tier. 300ms and 350ms are both drawers: one tier. A lone 1200ms is a toast's auto-dismiss, a timer rather than motion, so out of scope.
+2. **Name each cluster's role** by the area it changes, not its name in code: a `--slow` token on every tooltip is `duration.popover`.
+3. **Compare with the preset.** A consistent cluster within ~20ms of the dial keeps its value, recorded, because users already know its rhythm; a scattered one snaps to the dial.
+4. **Check the ordering.** Tooltips (popover) that outrun drawers (overlay) put the ladder upside down: an open issue whatever the numbers.
+5. **Class what's left** under law 4 or list it as a stray; nothing remains unclassed. One component can hold both: in a Glass preset gallery, a photograph dissolving to the next is the subject, but the same photograph moving between layouts is state, in the overlay tier.
+6. **Write it to `DESIGN.md`** with the counts: *"`duration.state` → `--dur-fast` 150ms; 42 uses; 9 strays at 160–180ms snapped."*