git:20261028.776fc68 to git:20261028.a3c506e

- description: 'Sistema de motion e micro-interação da Visant: tokens de easing/duração espelhados em CSS e framer-motion, mais motion-lint e medição de URL. Use em "animação", "motion", "transição", "deixa mais suave", "apple-like", "loading", "skeleton", "tela de espera", "micro-transições", /visant-motion.'

- Build interfaces where motion is invisible-correct: every transition has a purpose, responds instantly, and stays under the perception of "slow". Governing rule: **SSoT — never hardcode a cubic-bezier or a duration in a component.**

- **§1 and §2 are the whole skill in practice.** Everything after them is

- reference for a specific moment. This order is deliberate and it's a fix: the

- skill used to open with the SSoT bootstrap, which only matters once per repo,

- and buried the decision rules and the gotchas below it. What survives in

- behaviour is the first screen — so the first screen is now what you use every

- time. Bootstrap moved to §10, where you'll look for it exactly when you need it.

- **Source of the principles:** Emil Kowalski's skills — https://github.com/emilkowalski/skills (`emil-design-eng`, `apple-design`, `improve-animations`, `review-animations`) — distilled from animations.dev + Apple *Designing Fluid Interfaces* (WWDC 2018). Consult that repo for the upstream, canonical guidance; this skill is Visant's applied, SSoT-ized version of it.

- 2. **Easing:** enter/exit → `EASE_OUT`. Move on-screen → `EASE_IN_OUT`. Hover/color → `ease`. Constant (marquee/shimmer/progress) → `linear`. **Never `ease-in` on UI** — one exception, §5 rule 2.

- 3. **Duration:** UI < 300ms. press 100-160 · dropdown 150-250 · modal 200-300. Route passages (§5), marketing, scroll and 3D may be long & deliberate — the ceiling is about a control answering a click.

- 4. **Never `scale(0)`** — start at `scale(.95)` + opacity.

- ## 2. Gotchas (non-obvious, all battle-tested — read before you write)

- 4. **Never `transition-all`** — animates unexpected props and janks. Scope: `transition-colors`, or `transition-[color,background-color,border-color,box-shadow,opacity]`, or `transition-transform`. Use the codemod (§7) to sweep a repo.

- 6. **Reduced motion is a real signal, not "off".** Keep opacity/color, drop movement/spring. A global `@media (prefers-reduced-motion) { *{…0.001ms} }` guard is the cheap safety net. On a list-row exit that means the row still *leaves* — you zero the animation, never the outcome.

- 7. **An exit animation played behind an open modal is wasted — and it stalls the close.** Completing an item from a dialog where the payoff is the row collapsing out of the list, the naive order awaits the ~300ms exit (a `completing` flag on the row) and *then* closes the modal — so the collapse runs hidden under the modal and the modal sits ~300ms doing nothing. Close the surface **first**: the modal closing is itself the exit-with-weight, and the row then collapses in view. Same rule as skipping the ritual when a kanban card changes column (the column-move *is* the exit). One visible exit per surface, never two. Pattern → `visant-frontend` › [Close the surface before the exit ritual](../visant-frontend/references/stack-tailwind-react.md#close-the-surface-before-the-exit-ritual).

- 8. **Amplitude, not duration, is what reads as amateur.** Measured on a "black hole" delete: 200° spin, overshoot on the vanishing dot and 22 dust grains per row → the owner's verdict was "tá mt amadora kkk". The fix kept the timing and cut the amplitude: ~12° spin, row shrinks to 40%, 12 faint grains, neighbours pulled ≤ 4px, no overshoot on anything that disappears. Rule: halve the amplitude, then halve it again; good motion is barely noticed.

- 9. **One focus of motion per surface.** A screen where the queue ticks, four images stream in, an export counts %, an error shakes and a toast slides — all at once — was reported as "mt coisa espremida e acontecendo ao mesmo tempo". Sequence the states (sent → generating → ready → exporting) so only one thing moves at a time.

- ## 2b. Sound (SFX) — analog clicks, only where the person acts

- Sound is motion for the ear and obeys the same ceilings. The house engine is `sfx-bus` (Web Audio synthesis, zero files, zero requests; `npx shadcn@latest add @visant/sfx-bus` from the Visant library at [ui.visantlabs.com](https://ui.visantlabs.com/llms.txt), which also ships ready motion pieces: `motion-layer`, `fold-motion`, `line-reveal`, `text-morph`, `count-up`, `toast-stack`). What a long round of owner reports converged on:

- - **Map gesture → timbre:** discrete step (knob, tab, dock icon crossed) → `detent`; continuous drag (slider) → `focus` per 1/20–1/40 of travel; switch → `toggle`; hold/slide to confirm reaching the end → `complete`. A drag must not play on every pixel and a parametric curve the owner tweaks for minutes should stay silent ("tirar sfx de arrastar aqui").

- - **Level:** every timbre below the old UI click (~-44 dBFS RMS); measure with an `OfflineAudioContext` render and keep the numbers in a table in the source comment.

- ## 3. The API (`lib/motion.ts`)

- | `EASE_OUT` | `[0.23,1,0.32,1]` | enter/exit, responds to input — **the default** |

- | `itemEnter(i, step=.04, cap=.4)` | — | list-item entrance, short capped stagger |

- | `pressable` | — | subtle `whileTap` for clickable cards/tiles |

- CSS form (property-explicit — see gotcha #1): `[transition-duration:var(--dur-base)] [transition-timing-function:var(--ease-out)]`.

- Every moment the user waits has motion on it whether you designed it or not — a bare spinner is just the default nobody chose. Waits are also **rare-frequency** by §1 rule 1, so this is where the delight budget actually lives: illustration, brand character, a loop worth watching. It's the one place in the product where charm doesn't fight the work.

- | < 100ms | nothing — optimistic write + undo toast | a spinner (it only flashes) |

- | unknown | stream partials — content arriving **is** the loader | indeterminate anything |

- 1. **Answer the click before the server does.** Press feedback + immediate state change is frame one of loading. Optimistic patch + undo (§6) beats every spinner — and if the surface closes on click, the in-button spinner can never show at all, so it's dead chrome: `visant-frontend` › [unreachable spinner](../visant-frontend/references/stack-tailwind-react.md).

- 3. **Skeleton ≈ the real layout** — same box sizes, radius, gaps — so content lands without shift. Shimmer is `linear`, infinite, ~1.2–1.6s: constant motion (§1 rule 2). It's the one legitimate `@keyframes` in the app, because nothing ever interrupts it.

- 5. **An empty state is a wait too** — waiting on the user's first data. It earns the same treatment: illustration plus the single action that ends the wait. (Whether it earns space at all is `visant-frontend`'s call, not this skill's.)

- 6. **Reduced motion:** shimmer/pulse degrades to a static tint or slow opacity fade. The progress readout stays — it's information, not decoration.

- 9. **A wait ends in a result — design the losing branch too.** Skeleton → error is the transition everyone forgets, and it's the one that lands hardest: the skeleton has been promising content for 3s. Don't collapse the layout; swap the skeleton in place for the error, keep the box, put retry inside it. Same crossfade, no bounce, no red flash. An error is information, not a scare.

- **Don't write this from scratch.** Vercel maintains the patterns and the full CSS as an official skill — install it and follow it for the *how*:

- 1. **Durations live in `--dur-vt-*`**, never inline: exit 150 · enter 210 (delayed by the exit) · move 400. The asymmetry is the point — the old view leaves fast because it already lost the argument; the new one arrives calmly enough to read.

- 2. **The one exception to "never `ease-in`" is `::view-transition-old`.** Nothing is waiting on an exit, so front-loading its stillness costs nothing. Everywhere else the ban holds — and `motion-lint` encodes exactly this exception.

- 5. **The wrapper goes in `page.tsx`, never the layout** — layouts persist across navigation, so enter/exit never fire there. Costs an hour to discover by hand.

- 6. **`::view-transition { pointer-events: none }`** — already in the starter CSS. Without it, a tap during a 400ms passage is silently swallowed.

- 8. **Reduced motion needs its own rule** — the global `*` guard does not reach view-transition pseudo-elements (they hang off the document). Directional slides are the top motion-sickness trigger; this is the one guard you cannot skip. Also in the starter CSS.

- 9. **Not every morph is a navigation.** A row reordering, a card changing column, an item moving between lists — nothing navigated, so View Transitions is the wrong instrument. That's framer-motion's `layout` / `layoutId` (it FLIPs, so the size change runs on `transform` and stays honest with §1 rule 5). Two costs to know: `layout` on a long list re-measures every child on each commit, so scope it to what actually moves; and a `layoutId` pair must be mounted in the same `AnimatePresence` or the morph degrades to a plain crossfade. Rule of thumb: **route changed → View Transitions; DOM reshuffled in place → `layout`.**

- **Scroll-driven motion:** prefer native `animation-timeline: scroll()` / `view()` over a scroll library — it runs off the main thread, so it can't jank. Gate it behind `@supports (animation-timeline: view())` and keep the JS path as the fallback, not the default. Scroll and marketing motion may be long and deliberate; they're audited-and-kept, not defects.

- ## 6. Reuse before rebuilding (in visant-board; replicate elsewhere)

- - Shared `Button` bakes in `active:scale-[0.97]` → every button already has press feedback. Don't re-add it per-button; put press on the shared primitive once.

- - Shared overlays are origin-aware. New custom overlay? Apply the same Radix var.

- - Optimistic UI + `sonner` toast + undo is the established feedback pattern — reuse it, don't invent modal confirmations.

- - The status-write + completion ritual (celebrate → row exit → optimistic patch → undo) lives in **one hook** (`hooks/useIssueActions`), consumed by both the board and the home on the **same SWR key**. A new surface that needs to complete/act on an item calls the hook — it does not re-implement the ritual, and it must not read the list without the light-status resolver (or its counts silently diverge from the board's). High-frequency sub-values (a running clock) are split into their own context so the ritual's consumers don't re-render every second — gotcha-tier, see `visant-frontend` › [Split a per-second value into its own context](../visant-frontend/references/stack-tailwind-react.md#split-a-per-second-value-into-its-own-context).

- ## 7. Tooling — lint, then codemod

- ### `motion-lint.mjs` — the severity table, executable

- Exit 1 on any HIGH (`--strict` adds MEDIUM), so it drops straight into a pre-push hook or CI. It knows the real exceptions — `ease-in` on `::view-transition-old`, `--dur-vt-*` above 300ms, `cubic-bezier` inside the SSoT file itself, a loader in a file that imports `useDelayedFlag`. When a rule is genuinely wrong for a line (long, deliberate marketing/scroll motion), suppress it *with a reason*:

- **After editing any rule, run `node scripts/motion-lint.mjs --self-test`.** It checks the three things a regex suite loses silently over time: every rule still fires against `scripts/__fixtures__/bad.*`, the clean fixture still reports zero (no false positives), and suppression still suppresses. A rule that quietly stopped matching is worse than no rule — the audit comes back green. Add a fixture case with every new rule; the self-test fails if a rule has no case.

- ### `--fix` — the mechanical half, in one command

- Most of a real audit is not judgement. In one round, **48 of 55 findings were

- `duration: 0.6` wanting to be `DUR.slow`** — mechanical, and it still ate most

- of the session by hand. `--fix` is the door; the codemods own the decision of

- what is safe to rewrite. What it deliberately leaves alone: `ease-in` on UI,

- `scale(0)`, non-origin-aware popovers, blinking loaders, undesigned waits. Those

- are design decisions, not text substitution.

- ### `codemod-duration.mjs` — inline durations → `DUR.*`

- node scripts/codemod-duration.mjs --apply --over # also >300ms — read the list first

- Three buckets, because the rewrites are not equivalent. **EXACT** — the number

- already *is* a token (`0.2` → `DUR.base`); pure rename. **NEAR** — within 25% of

- a token and under the 300ms ceiling (`0.25` → `DUR.base`). **OVER** — above

- 300ms (`0.6` → `DUR.slow`), which *halves the animation*: that's a behaviour

- change, not a refactor, so it needs `--over` and a look at the list. Route

- passages and marketing are legitimate exceptions and only someone watching the

- screen can say so.

- A value far from every token stays **UNMAPPED** instead of being guessed: `0.08`

- may be a deliberately drier press, and silently snapping it to `DUR.press`

- erases the decision rather than recording it. The import is added using whatever

- path the repo itself already uses for the SSoT.

- ### `codemod-transition-all.mjs` — sweep the second biggest finding

- Adjust the `ROOTS` / `isUi` constants at the top for a different repo layout. Always run `tsc` + tests + build after.

- ## 8. Feel-check — measure the URL, then judge with your eyes

- - **Long Animation Frames** (Chromium 123+) with per-script attribution — the frame that blocked, and the function that blocked it. This is the jank users feel and never report.

- **Then judge with your eyes** — the numbers can't. DevTools → Animations → 25% speed: press gives an instant scale-down? popover grows from its trigger? no two overlapping states during a crossfade? stagger reads as a short cascade, not one-by-one? Review again the next day with fresh eyes.

- **Start with `node scripts/motion-lint.mjs --json` (§7)** — it does the whole grep sweep for you, with severity and fixes already attached. Then measure the deployed URL (§8). Only then read code, and only where the tools pointed.

- Two things the lint can't see, so audit them by hand: **waiting states** — list every `isLoading`/`isPending`/`Suspense`/empty branch and ask what the user is looking at during each (§4) — and **navigation**, which is judged by whether the passage makes a true claim, not by any pattern in the source (§5). Then load **`references/motion-rules.md`** for the 9 audit categories, HIGH/MEDIUM severity criteria, and exact fixes. Report findings by leverage (impact ÷ effort); fix core/shared primitives first (they propagate to every route). Long, deliberate marketing/scroll/3D animations are audited-and-kept, not flagged.

- ## 10. Bootstrap the SSoT (only when the repo doesn't have one yet)

- Motion lives in ONE place, mirrored across JS and CSS so framer-motion and Tailwind/Radix stay in lockstep.

- - **JS:** drop `assets/motion-ssot-starter/motion.ts` → `lib/motion.ts` (easings, `DUR`, variants, and the `WAIT` thresholds of §4).

- - **CSS:** merge `assets/motion-ssot-starter/globals-tokens.css` into the `:root` + a `@layer utilities` block of the app's global stylesheet. Ships the `.skeleton` shimmer, the `--dur-vt-*` route-transition scale, and the two reduced-motion guards the global `*` rule can't reach.

- - **Waiting:** drop `assets/motion-ssot-starter/use-delayed-flag.ts` → `lib/use-delayed-flag.ts`. Every loader in the app goes through it (§4.2), so the anti-flicker pair is a shared primitive and not a thing each dev re-derives wrong.

- If the repo already has these (e.g. visant-board has `lib/motion.ts` + `--ease-*`/`--dur-*` in `globals.css`), **use them** — do not create a parallel system. `visant-board` is the canonical reference implementation; `node scripts/motion-lint.mjs` (§7) is what keeps that claim true instead of merely stated.