@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/skills/motion-kit/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: motion-kit
+description: Apply Yewdiel's motion and design line (@yewdiel21/motion-kit) in any web project — Stepbro's dialogs that grow out of their button (morph, liquid, shared title, drag to dismiss, floating window), options menu, toast deck, chat (glass bubbles, delayed "Pensando…" that morphs into the reply, live background driven by the microphone), navigation (7 styles + phone bar + app shell), onboarding steps, drag to reorder (lists and kanban, tilting floating copy, keyboard), Dousan Miao's glass, progressive frost, floating tags, film grain, success confetti and bottom sheet, Siena's burger icon and rolling button, text and scroll motion (OFFFICE masked type, Siena's slot title, reveal cascade, photo parallax, depth grid, frame zoom, header contrast, marquee, Dousan's playful letters) and two custom cursors (Dousan's glass chip, Siena's dot), iyo.ai's floating glass navbar (island), stacked product card dock, autoplaying snap strip, scroll fill-text and GPU particle hero (optional /gl entry), Stepbro's utility animations (exits, shake, highlight, loading sweeps, gradient text), design line (19 Material 3 themes light/dark, tokens, DM Sans type scale, capsule controls, theme picker, theme generator from a colour) and motion (flowIn/flowOut, step change, reveal wave, details, sliding tab indicator, counters, layout reflow, slot text, chat message entrance) plus spencergabor.com recipes (spring cards, curved inertia carousel, piles, elastic words, stretching footer, radial menu), for Astro/HTML (data-mk + autoInit, custom elements) or React/Next.js (hooks and components). Use when the user asks for "texto que sale de una máscara", "texto por líneas", "título que gira / tragaperras", "parallax", "grid desde el fondo", "marquee / banda infinita", "cursor personalizado", "cursor que sigue al ratón", "navbar flotante", "navbar de cristal / isla", "dock de tarjetas", "cards apiladas", "carrusel con snap", "texto que se rellena con el scroll", "hero de partículas", "partículas WebGL", "cristal", "glassmorphism", "liquid glass", "blur progresivo", "confeti", "animación de salida", "quitar fila animada", "shake", "skeleton / loading", "texto degradado", "sheet / hoja desde abajo", "hamburguesa a X", "diálogo que sale del botón", "chat como Stepbro", "burbujas de chat", "fondo del chat", "navegación de Stepbro", "barra de navegación", "sidebar / dock", "onboarding por pasos", "arrastrar para reordenar", "kanban", "drag and drop", "modal como Stepbro", "ventana flotante", "arrastrar para cerrar", "menú de opciones", "toasts", "la línea de diseño de Stepbro", "temas de Stepbro", "selector de tema", "botones/campos como Stepbro", "tabs con indicador", "contador animado", "slot text", "onda reveal", "flowIn", "las animaciones de Spencer", "carrusel curvo", "cards con resorte", "footer que se estira", "menú radial", "motion-kit", or wants the portfolio's or Kayro's look and motion in another project.
+---
+
+# motion-kit
+
+Stepbro (Tasks, Money) and spencergabor.com, rewritten as one framework-agnostic package. Layers, bottom up:
+
+| Layer | Import | What |
+|---|---|---|
+| Core + motion functions | `@yewdiel21/motion-kit` | `registerMotion`, `EASE`, `TIMING`, `flowIn`, `revealFrom`, `slideIndicator`, `countTo`, `captureLayout`/`reflowLayout`, `enterMessages`… |
+| Recipes | same + `/auto` + `/react` | `createX(root, options) → { destroy, …controls }`; `data-mk="x"` + `autoInit()`; `useX(ref, options)` |
+| Components | engine in `.`, `<mk-x>` in `/elements`, `<X>` in `/react` | own markup + styles: `dialog`, `menu`, `toast`, `theme-picker`, `chat`, `chat-background`, `nav`, `steps`, `cursor`, `island` |
+| WebGL (optional) | `@yewdiel21/motion-kit/gl` (+ matching hooks in `/react`) | `createParticleHero`, `createLiquidBlend`, `createMatcap`, `createShaderGrain`, `createShaderBlur`; reduced motion and fallback |
+| Effects | `/css/effects` (in `/css`) + `.` / `/react` | `.mk-anim-*`, `.mk-loading`, `.mk-text-gradient`, `.mk-frost`, `.mk-float`, `.mk-grain`, `.mk-success`; `animate(el, name)`, `leave(el, exit)`, `confetti(origin)`, `<Frost />` |
+| Design line | `/css`, `/css/themes`, `/css/fonts`, `/theme`, `/theme/generate` | tokens, 19 themes, controls, theme runtime and generator |
+
+## 1. Install (pick one)
+
+**Package** (public npm registry, no token required):
+
+```sh
+npm i @yewdiel21/motion-kit gsap
+npm i -D @material/material-color-utilities@^0.3.0   # only for the theme generator
+```
+
+**Copy the code** (editable, no runtime dependency on the package):
+
+```sh
+npx @yewdiel21/motion-kit list
+npx @yewdiel21/motion-kit add tabs slot-text theme-picker --react --elements --dir src/motion-kit
+npx @yewdiel21/motion-kit add theme neogreen oled
+npx @yewdiel21/motion-kit add controls
+npx @yewdiel21/motion-kit theme brand --seed "#ff6a3d" --out src/styles
+```
+
+`add` copies each entry, what it `requires`, only the core files it imports, the base CSS (tokens, default theme, base, entrance states) and, with `--react` / `--elements`, the hook/component and custom element. Imports are relative, so nothing needs rewriting. `gsap` must be installed.
+
+## 2. Wire it once
+
+1. CSS: `import '@yewdiel21/motion-kit/css'` (tokens, default theme, controls, recipe and component styles). Add `/css/themes` (all 19) or `/css/themes/<id>` and, for Stepbro's fonts, `/css/fonts`.
+2. Head, inline, in this order:
+   - `MK_THEME_HEAD_SCRIPT` (`/theme`): applies the stored theme/mode before the first paint.
+   - `MK_HEAD_SCRIPT` (`/auto` or `.`): adds `.mk-js` so entrances start hidden, `.mk-failed` if no recipe ran within 2.5 s.
+3. `<body class="mk-app">` gives the page the theme's background, text colour and DM Sans.
+4. Start things:
+   - **Astro / HTML**: `initTheme()`; `data-mk="<recipe>"` + `autoInit()`; `defineElements()` for `<mk-…>` components.
+   - **React / Next.js** (entries are `'use client'`): `<ThemeProvider>` at the root, hooks (`useTabs(ref)`), components (`<ThemePicker />`, `<SlotText text />`, `<AnimatedNumber value />`, `<FlipGroup>`). Keep `data-mk="<recipe>"` on recipe markup so the hidden entrance state applies before hydration.
+
+## 3. Design line
+
+- Colour: 37 Material 3 roles `--md-sys-color-*` per theme; components use the semantic layer `--mk-bg`, `--mk-surface`, `--mk-surface-1…5` (container lowest→highest), `--mk-text`, `--mk-muted`, `--mk-accent`, `--mk-on-accent`, `--mk-accent-soft`, `--mk-secondary-soft`, `--mk-outline(-soft)`, `--mk-error(-soft)`, `--mk-scrim`, `--mk-shadow-color`. Never hard-code colours in components: use these.
+- Themes: `<html data-mk-theme="<id>" data-mk-mode="system|light|dark">`. Ids: blue, purple, neogreen (default), red, pink, pastel-pink, brown, super-blue, gray, oled (the 10 Stepbro shows) + black, green, orange, cold-blue, modern-1, funny, new, new2, black-green. `setTheme(id)`, `setMode(mode)`, `getTheme()`, event `mk:theme`. Nested `[data-mk-theme]` sections work.
+- Own brand colour: `applyTheme('#ff6a3d', { id: 'brand' })` at runtime, or `motion-kit theme brand --seed …` for a static file.
+- Type: `--mk-font` (DM Sans), `--mk-font-mono` (Geist Mono), icons `.mk-icon` (Material Symbols Rounded). Scale classes `.mk-type-{display|headline|title|body|label}-{large|medium|small}`.
+- Shape: capsules. `--mk-radius-{xs 8, sm 12, md 16, lg 24, xl 32, 2xl 40, 3xl 48, 4xl 64, full}`; bubble 32, dialog 40, chat 48, dock 64. Spacing `--mk-space-1…16` (4 px). Breakpoint 680 px.
+- Controls (CSS only): `.mk-glass` (Dousan's glass on any button/chip; `<span class="mk-glass__shadow">` inside for its shadow), `.mk-burger` (three lines → X with `aria-expanded`), `.mk-button--roll` (Siena: `<span class="mk-roll" data-text>` + `<span class="mk-roll__arrow"><span class="mk-icon" data-icon>`), `.mk-button` (`--primary`, `--tonal`, `--outlined`, `--text`, `--icon`, `--sm`, `--lg`; squash on pointer focus), `.mk-field` (+ `__label`, `__hint`, `aria-invalid`), `.mk-switch` (`<input type=checkbox role=switch>`), `.mk-checkbox`, `.mk-chip` (`--filter[aria-pressed]`, `--input`), `.mk-segmented` (with the `tabs` recipe), `.mk-icon`.
+- Full table: [reference/design.md](reference/design.md).
+
+## 4. Recipes
+
+| Recipe | Markup | Key options (defaults) | Controls |
+|---|---|---|---|
+| `tabs` | root with `[data-mk-tab]` buttons and a `[data-mk-indicator]` (use `.mk-segmented`) | `orientation 'horizontal'`, `duration .45`, `onSelect(i, tab)` (event `mk:tab`) | `select(i)`, `index` |
+| `counter` | element with a number | `to` (text), `from 0`, `duration .6`, `decimals`, `locale`, `prefix`, `suffix`, `trigger 'scroll'` | `play()`, `set(n)` |
+| `details` | container of `<details>` (chevron `[data-mk-chevron]` in the summary) | — | — |
+| `reveal` | element to uncover | `speed 'fast'\|'normal'\|'slow'\|'slower'`, `origin` (selector), `trigger 'manual'\|'load'` | `play(origin?)` |
+| `reflow` | list with `[data-mk-item][data-flip-id]` | `duration .62` | `capture()` before the DOM change, `play()` after |
+| `slot-text` | text element | `duration 300` ms, `stagger 45`, `maxTilt 5` | `set(text)` |
+| `spring-cards` | root with `[data-mk-card]` children, each with `.mk-card__shadow` + image | `push .4`, `falloff 6`, `initialOffset 100`, `stiffness .05`, `friction .8`, `stagger .08`, `delay .4` | — |
+| `curved-carousel` | root with `[data-mk-slide]`; optional `.mk-carousel__media`, `.mk-carousel__title` | `friction .85`, `throwBoost 2`, `wheel .2`, `startIndex 0`, `onSelect(i, slide)` (auto: `mk:select` event) | `next()`, `prev()`, `goTo(i)`, `index` |
+| `pile` | `.mk-pile > .mk-pile__stack > .mk-pile__layer > .mk-pile__media`; back layers styled with `pileStyle(pileLayers(n, seed)[i])` | `threshold .25` | — |
+| `words` | any text element | `by 'words'\|'chars'`, `trigger 'scroll'\|'load'\|'manual'`, `duration .8`, `stagger .1` | `reveal()`, `replace(mutate)` |
+| `flow` | container; its children animate | `y 20`, `blur 16`, `duration .5`, `stagger .05`, `style 1\|2`, `trigger` | `play()` |
+| `pop` | any element | `scale .7`, `duration 1.1`, `trigger` | `play()` |
+| `fit-text` | one-line element inside a parent | `safety .995` | `refit()` |
+| `stretch-footer` | `footer[data-mk="stretch-footer"]` containing `[data-mk-footer-title]`, plus a `[data-mk-phantom]` spacer after `<main>` | `lambda .9` | — |
+| `radial-menu` | root with `[data-mk-toggle]` and `[data-mk-item]` direct children | `radius '3.6rem'`, `startAngle 1.5708`, `spacing .9` | `open()`, `close()`, `toggle()`, `isOpen` |
+| `pill` | `.mk-pill` button, `.mk-stretch` link | CSS only | — |
+| `mask-text` | any text | `by 'lines'|'words'|'chars'`, `y 100` (Siena titles 120), `duration 1.2`, `delay .1`, `stagger .02`, `trigger 'scroll'|'load'|'manual'`, `once` | `play()`, `hide()`, `split` |
+| `cascade` | block with `[data-mk-cascade="rule|fade|rise"]` children (`rise` inside a clip) | `delay` (`data-mk-delay`), `step .03`, `duration 1.2`, `once`, `trigger` | `play()`, `reset()` |
+| `text-roll` | a title | `trigger 'load'|'scroll'|'hover'|'manual'`, `delay`, `interval` (ms, Siena 6000), `duration 2`, `stagger .04` | `play()` |
+| `letters` | a word | `effect 'scale'|'blink'`, `colors`, `autoplay` | `play()` |
+| `parallax` | clipped frame with a picture (`[data-mk-parallax-target]`) | `amount 1`, `lerp 1`, `scroll` | `seek(p)` |
+| `depth-grid` | grid container | `start 'top center'`, `end 'bottom bottom'`, `lerp 1`, `scroll` | `seek(p)` |
+| `frame-zoom` | frame with one picture/video child | `start 'top bottom'`, `end 'bottom top'`, `lerp 1` | `seek(p)`, `open(on)` |
+| `contrast` | header; sections with `data-mk-tone="light|dark"` | `sections`, `attribute 'data-mk-on'` | `tone` |
+| `marquee` | strip whose first child is the group | `axis 'x'|'y'`, `speed 2` (s per item), `reverse` | `refresh()` |
+| `card-dock` | `.mk-card-dock` with `.mk-card-dock__item` (> `a.mk-card-dock__card` + `.mk-card-dock__title`), optional `.mk-card-dock__cta`; `mk-card-dock--fixed` | `intro 1600` (ms spread on load, 0 skips) | `expand()`, `collapse()`, `expanded` |
+| `snap-strip` | `.mk-snap-strip` with the cards as children | `autoplay`, `interval 5000`, `resume 2000`, `delay 500` (`data-mk-delay`) | `next()`, `previous()`, `index` |
+| `fill-text` | any text | `from .2`, `start 'top 90%'`, `end 'center 40%'`, `scroll` | `seek(p)`, `progress` |
+| `sortable` | root with `[data-mk-item][data-mk-id]` (optional `[data-mk-sortable-group="key"]` lists, `data-mk-sortable-locked`, `[data-mk-sort-handle]`) | `mutate true` (`false` in `useSortable`), `handle`, `autoScroll true`, `follow {1100, 38}`, `onReorder(detail)` (event `mk:reorder`, cancelable) | `cancel()`, `dragging` |
+
+React hooks: `useCardDock`, `useSnapStrip`, `useFillText`, `useParticleHero`, `useMaskText`, `useCascade`, `useTextRoll`, `useLetters`, `useParallax`, `useDepthGrid`, `useFrameZoom`, `useContrast`, `useMarquee`, `useSortable`, `useTabs`, `useCounter`, `useDetails`, `useReveal`, `useReflow`, `useSlotText`, `useSpringCards`, `useCurvedCarousel`, `usePile`, `useWords`, `useFlow`, `usePop`, `useFitText`, `useStretchFooter`, `useRadialMenu`. Markup and options: each recipe's `README.md` (`src/recipes/<name>/`). Parameters and origin: [reference/recipes.md](reference/recipes.md).
+
+## 4b. Effects (v0.5)
+
+| Name (`animate` / class `.mk-anim-<name>`) | Motion | Time |
+|---|---|---|
+| `out` / `out-left` / `out-bottom` | up 20 / left 64 / down 24 px, blur 16, fade | 0.5 s |
+| `collapse` | folds height, padding and margin while blurring | 0.25 s |
+| `highlight` | 4 px inner ring in primary-container | 1 s |
+| `shake` / `shake-strong` | ±4 px / ±10 px | 0.5 s / 0.4 s |
+| `fade`, `wipe`, `progress-in` | appear; a surface veil leaves to the right; appear late | 0.3 / 0.7 / 1 s |
+
+`await animate(el, name)` replays even if already playing; `await leave(row, 'out-left' | 'collapse', { remove })` animates then removes (or hides). In React lists: `leave(item, 'out', { remove: false })`, then drop it from state. Classes: `.mk-loading` (+`--soft`), `.mk-shimmer`, `.mk-text-gradient` (theme), `.mk-text-rainbow`, `.mk-frost` (+ five `<i>`; `--top`, `--fixed`; `<Frost />`), `.mk-float` / `.mk-float-group`, `.mk-grain` (`--mk-grain`), `.mk-success` + `confetti(button)`. Reduced motion: loops stop, exits jump to the end, confetti does not draw.
+
+## 5. Motion functions (no instance)
+
+Use them inside your own components; they all honour reduced motion and return the tween (or `null`).
+
+| Function | Stepbro use |
+|---|---|
+| `flowIn(targets, { style, reverse, target })` / `flowOut(targets)` | lists, steps, settings entering / leaving |
+| `stepChange(container, () => render next)` | wizard / onboarding steps (flow out → swap → flow in) |
+| `flowInMenu`, `flowInPalette`, `flowInForm`, `flowInLanding`, `flowInContent` | menu options, swatches, form cards, landing, articles |
+| `revealFrom(el, { origin, speed })` | a surface uncovered like a wave from the control that opened it |
+| `toggleDetails(details, open)`, `installDetailsMotion(root)` | disclosures |
+| `slideIndicator(indicator, target)` | any sliding selection indicator |
+| `countTo(el, n)`, `revealCounter(el, n)`, `tweenNumber(a, b, cb)` | changing numbers, balances |
+| `captureLayout` + `reflowLayout` | reorder / filter / add in lists |
+| `enterMessages(bubbles)`, `fitComposer(textarea)`, `scrollToLatest(scroller)` | chat / comments |
+| `capturePending(el)` + `morphPendingToReply(state, reply, list)` | a "thinking" placeholder turning into the answer (other frameworks) |
+| `audioEnergy(stream, onEnergy)` | microphone level 0…1 for `chat-background` (never asks for the mic itself) |
+| `channels(start, onChange)` + `spring()` / `eased()` | multi-property spring motion (liquid surfaces) |
+| `trackScroll(el, { start, end, lerp, onUpdate })` | an element's 0→1 progress through the viewport (follows the page; `lerp < 1` smooths it) — build your own scroll effects |
+| `motionSpring(stiffness, damping, mass?)` → `{ ease, duration }`, `springLinear(…)` | Motion/Framer springs (Dousan) as a GSAP ease or a CSS `linear()` |
+| `sheetOpen`, `sheetClose`, `pushUnderlay`, `releaseUnderlay` | a sheet rising from the bottom while the page behind sinks |
+| `morphOpen(surface, opener)`, `morphClose`, `morphCloseWithGhost`, `liquidOpen/Close` | any surface growing out of / folding into a control |
+| `attachDragDismiss(surface, { onDismiss })`, `attachFloating`, `anchorSurface` | drag to dismiss, floating windows, anchored panels |
+| `fadeBackdrop(dialog, 'in')`, `ghostOf`, `clearStyles` | backdrop tint, inert close copies, cleaning without GSAP measuring hidden nodes |
+
+Curves: `EASE.signature` (the Stepbro line), `EASE.flow`, `EASE.fadeAway`, `EASE.blurAway`, `EASE.layoutReflow`…; CSS: `var(--mk-ease-signature)`, `--mk-ease-flow`, `--mk-ease-close`. Times: `TIMING.*`.
+
+## 6. Components
+
+| Component | HTML / Astro | React |
+|---|---|---|
+| `dialog` | `<button data-mk-open="crear">` + `<mk-dialog id="crear" heading="…" [description] [variant="liquid|sheet"] [placement="anchor\|side"] [size="sm\|lg\|xl"] [float="key"] [shared="id"] [no-backdrop] [persistent] [no-drag]>` (children → body; `data-mk-part="footer"` stays below) | `<Dialog.Root variant placement float…><Dialog.Trigger/><Dialog.Content size><Dialog.Header><Dialog.Title/><Dialog.Close/></Dialog.Header><Dialog.Body/><Dialog.Footer/></Dialog.Content></Dialog.Root>` |
+| `menu` | `<button data-mk-open="m">` + `<mk-menu id="m" label="…">` with `<button data-mk-item data-mk-value>`; listen `mk:select` | `<Menu.Root onSelect><Menu.Trigger/><Menu.Content><Menu.Item value/><Menu.Separator/></Menu.Content></Menu.Root>` |
+| `toast` | `<mk-toaster>` once + `toast('Copiado', { origin: button, tone, action })` | `<Toaster />` once + `toast(…)` |
+| `theme-picker` | `<mk-theme-picker [show-hidden] [themes="a,b"]>` | `<ThemePicker themes showHidden onChange />` inside `<ThemeProvider>` |
+| `chat` | `<mk-chat [background] [mic] placeholder="…">` (history `[data-mk-message][data-mk-role]` inside); `mk:send` → `el.add('user', t)`, `el.pending()`, `el.reply(answer)` | `<Chat.Root onSend><ChatBackground /><Chat.Messages pending>{<Chat.Message role/>}</Chat.Messages><Chat.Confirm/><Chat.Composer/></Chat.Root>`; set the reply and `pending=false` in the same render |
+| `chat-background` | `<mk-chat-background energy scale>` first inside a positioned box; `el.busy(true)` | `<ChatBackground energy scale />` |
+| `nav` | `<div class="mk-shell"><main class="mk-shell__view">…</main><mk-nav class="mk-nav mk-nav--bonita" nav-style="bonita" [accent] [reveal] [storage-key]><div class="mk-nav__buttons"><a class="mk-nav__button" href aria-current="page">…</a></div></mk-nav></div>`; `mk:navigate` | `<Nav navStyle items active onSelect first actions accent reveal />` inside `.mk-shell` |
+| `cursor` | `<mk-cursor>` once (chip over `[data-mk-cursor="Label"]`, `data-mk-cursor-shape="circle"`, `data-mk-cursor-icon`) · `<mk-cursor variant="dot" text arrows>` inside a zone (`data-mk-cursor-hide` hides it) | `<Cursor />` · `<Cursor variant="dot" text arrows zone />` |
+| `island` | `<mk-island [class="mk-island--contained"] [entrance="false|manual"]>` with `.mk-island__backdrop[data-mk-island-close]`, `.mk-island__shell` (glass, header, `[data-mk-island-toggle="menu"]` buttons, `.mk-island__cta`), `.mk-island__content > div > [data-mk-island-panel="menu"]` with `[data-mk-island-item]` rows and `.mk-island-card`s; `mk:island` | `<Island brand cta panels={[{ name, label, icon, light, content }]} contained onChange />` |
+| `steps` | `<mk-steps class="mk-steps">` + `[data-mk-step]` sections, `[data-mk-flow-item]`, `[data-mk-counter]`, `[data-mk-step-next/prev/goto]`; `el.busy(on)`, `mk:step` | `<Steps index onChange busy><ChatBackground /><Steps.Counter /><Steps.Step>…</Steps.Step></Steps>` |
+
+Register elements with `defineElements()` (or a list of tag names). Engines for your own markup: `createDialog(dialogEl, opts)`, `createMenu(dialogEl, opts)`, `createToaster(hostEl)`, `createThemePicker(el)`, `createChat(el)`, `createChatBackground(el)`, `createNav(navEl, { style })`, `createSteps(el)`.
+
+Dialog behaviour (Stepbro ModalHost): the opener turns into the dialog (0.7 s signature, colour handover 0.3 s, content from an 8 px blur) and it folds back on close (0.5 s, content blur 32 + radius 400, via an inert ghost so focus returns at once); without an opener it scales from .92. `data-mk-shared="id"` on a piece of the opener and of the dialog flies that text between them. Auto-resize 0.45 s; drag down > 100 px dismisses (also on phones); `float` lifts it into a movable, resizable window on desktop; full screen with radius 0 under 680 px. Events: `mk:open`, `mk:close` (cancelable), `mk:closed`. `[data-mk-close]` inside closes it. `open(null)` opens with no opener (scale-in).
+
+Chat (PrettyChat): bubbles grow from their speaker's side (scale .5, blur 24, 0.7 s) while words rise; "Pensando…" only after 500 ms, then it morphs (Flip 0.7 s) into the reply; Enter sends, Shift+Enter breaks the line; the composer grows from 64 px (0.18 s). Nav styles: `clasica`, `bonita` (Money default), `dock`, `guapa`, `tasks`, `melon`, `tunnel` (`NAV_STYLES`), one glass bar under 680 px; `accent` = Stepbro's variant-1. Steps: flow out → swap → flow in (0.5 s), counter rolls, focus goes to the step's title. Sortable: lift 0.18 s, spring 1100/38, tilt up to 14°, neighbours slide 0.62 s, land 0.42 s; touch drags only from the handle; Space/arrows/Escape on the keyboard.
+
+**Adding a component** (in the motion-kit repo): `pnpm new component <name>` scaffolds `src/components/<name>/{engine.ts, <name>.css, element.ts, react.tsx, README.md}`, a test, playground demos, the registry entry and the exports. Fill the engine (works on existing markup, defaults from `TIMING`, reduced motion, `destroy()` restores the DOM), then `pnpm test`. See [reference/components.md](reference/components.md).
+
+## 7. Rules
+
+- Call `destroy()` when the element leaves (hooks, components and `autoInit()`'s returned function do it). Never leave instances running on removed nodes.
+- Respect reduced motion: everything here already shows the final state under `prefers-reduced-motion: reduce`; custom motion must check `reduced()` too.
+- Flip contract: measure before the DOM change, animate after it (`capture()`/`play()`, `<FlipGroup signature>`).
+- Text that changes: `words.replace(() => …)`, `fit.refit()`, `slot.set(text)` — don't re-create.
+- Elements inside a closed `<dialog>`: create `words` with `trigger: 'manual'` and call `reveal()` after `showModal()`.
+- `stretch-footer` needs the page above it: `main { position: relative; z-index: 1; background: var(--mk-bg) }`.
+- Theme: style with `--mk-*` tokens and controls; switch with `setTheme`/`setMode` (or `useTheme()`), never by swapping stylesheets.
+- Override look with CSS variables (`--mk-button-bg`, `--mk-field-radius`, `--mk-swatch-size`, `--mk-tabs-indicator`, `--mk-shadow`…), not by editing package code.
+
+## 8. Choosing
+
+- New app with Stepbro's look → `/css` + `/css/themes` + `/css/fonts`, `.mk-app`, controls, `theme-picker` in settings.
+- Segmented filters / view switch → `.mk-segmented` + `tabs`. Totals → `counter` / `<AnimatedNumber>`.
+- Lists that reorder → `reflow` / `<FlipGroup>`; lists the user reorders by dragging (tasks, kanban) → `sortable`; lists that appear → `flow` (or `flowIn`).
+- Editorial headlines → `mask-text` (lines; `y 120` for film-title feel); credits / spec lists → `cascade`; a hero title that keeps alive → `text-roll` with `interval`; a playful word → `letters`.
+- Photos in long pages → `parallax`; a gallery section → `depth-grid`; a video section → `frame-zoom`; header over dark/light sections → `contrast`; logos / festivals → `marquee` (+ `.mk-fade-x`).
+- Site header for a product / landing → `island` (menu + cart share it); a product switcher pinned to a corner → `card-dock` (`--fixed`); phone carousels → `snap-strip`; a manifesto paragraph → `fill-text`; a hero with a living background → `particle-hero` from `/gl` (keep the text in HTML).
+- Portfolio cards → `cursor` chip (`data-mk-cursor="View project"`); a draggable reel or full-bleed hero → `cursor` dot.
+- Glass actions or tags over photos / colour → `.mk-glass` (+ `.mk-float-group` for floating tags); bottom fade over scrolling content → `.mk-frost`; a cinematic hero → `.mk-grain`.
+- Removing rows → `leave(row, 'out-left' | 'collapse')`; form error → `aria-invalid="true"` (vibrates) or `animate(el, 'shake')`; success → `.mk-success` + `confetti(button)`; loading cards → `.mk-loading`; AI / premium labels → `.mk-text-gradient`.
+- Project detail over the page → `dialog` with `variant="sheet"` and `data-mk-underlay` on the page; mobile menu toggle → `.mk-burger`; "Explore" CTA → `.mk-button--roll`.
+- App frame → `.mk-shell` + `nav` (let the user pick the style; `storageKey` remembers it). Assistant / support chat → `chat` + `chat-background`. First-run setup → `steps` (with `ChatBackground` and `busy` while saving).
+- FAQ / settings groups → `details`. Date/time popovers → `revealFrom` from the field.
+- Language switch on a title → `slot-text`.
+- Portfolio hero → `spring-cards` + a giant `fit-text words` title; featured projects → `curved-carousel`; archive → `pile`; last screen → `stretch-footer`; corner quick actions → `radial-menu`.
+- Film navigation → `ticket-menu` or `<Menu.Root ticket>` / `<mk-menu ticket>`; preserves menu focus, selection and keyboard handling.
+- Circular archive → `infinite-reel` (wheel, drag, keyboard, axis x/y); interactive card grid → `repel-bento`; testimonials → `rotator` (8 s, pause on focus/hover).
+- Numeric experience/time selector → `drag-ruler` (role slider, 60 px/unit, step .1); a shared active indicator in navigation → `dock-pill` (spring 380/30). Navigation remains the app's responsibility.
+- GPU image transitions → `createLiquidBlend`; metal study → `createMatcap`; film processing → `createShaderGrain` / `createShaderBlur`, all from `/gl`. React hooks `useLiquidBlend`, `useMatcap`, `useShaderGrain`, `useShaderBlur` are in `/react`. Import explicitly: these are not autoInit recipes. Retain accessible HTML images and set dimensions on the host. See [reference/recipes.md](reference/recipes.md) and each recipe README for the source parameters and declared adaptations.

package/skills/motion-kit/reference/components.md

@@ -0,0 +1,86 @@
+# Components
+
+A component brings its own markup and styles; recipes animate yours. Each one lives in `src/components/<name>/`:
+
+| File | Job |
+|---|---|
+| `engine.ts` | `create<Name>(root, options) → { …controls, destroy }`. Vanilla. Works on existing markup; creates only temporary internals (ghosts, generated children) and removes them. Defaults from `core/timing.ts`; reduced motion gives the end state; `destroy()` restores the DOM. |
+| `<name>.css` | Styles on `--mk-*` tokens; parts as `[data-mk-part="…"]`; own variables `--mk-<name>-*`. |
+| `element.ts` | `<mk-<name>>` custom element on `MkElement` (light DOM). `static options` maps attributes (kebab-case) to engine options: `string`, `number`, `boolean` (presence), `list` (comma separated), `json`. The engine is created on connect, recreated on attribute change, destroyed on disconnect. |
+| `react.tsx` | `'use client'` component that renders the root and creates the engine in a layout effect; callbacks read through refs; `className`, `style`, `unstyled`. |
+| `README.md` | Markup (HTML and React), options/attributes, events, CSS variables, accessibility, origin of every parameter. |
+
+`registry.json` lists it (`kind: "component"`, `files`, `element`, `react`, `requires`, `since`). The CLI (`list`, `add --elements --react`), the CSS build (`dist/css/components/<name>.css`, included in `/css`), the playground and this skill read from there. `pnpm test` checks that every component has the five files.
+
+## Add one
+
+```sh
+pnpm new component demo-card      # from the repo root
+```
+
+It writes the five files, `test/components/demo-card.test.ts`, `apps/playground/src/demos/demo-card/{Vanilla.astro,React.tsx}`, the registry entry (`since` = next minor) and the exports in `src/index.ts`, `src/react/index.ts` and `src/elements/index.ts`. Then:
+
+1. Write the engine from the kit (`Stepbro - Kit de replicacion/…`): every duration in `TIMING`, curves in `EASE`.
+2. Fill the README and the description in `registry.json`.
+3. Extend the test (behaviour + destroy restores markup, with and without reduced motion).
+4. `pnpm test`, `pnpm dev` and check the playground page in light and dark.
+
+## theme-picker (v0.2)
+
+- Engine `createThemePicker(root, { themes, showHidden, labels, onChange })` → `{ select(id), destroy }`. Generates `button.mk-swatch[data-mk-swatch]` for each theme unless the root already has swatches; `aria-pressed` follows `getTheme()`; clicking calls `setTheme`.
+- `<mk-theme-picker show-hidden themes="a,b">`, `<ThemePicker />` (+ `<ThemeProvider>` / `useTheme()`).
+- Motion: entrance `flowInPalette` (scale .5, blur 4, .1 s, 10 ms). Ball: circle → 32 px radius on hover (+ saturate 1.5) → 16 px when chosen, 0.5 s `--mk-ease-swatch`; inner ring; two blurred lights drift (3.5 s, background 4.5 s, `--mk-ease-swatch-light`).
+- Variables: `--mk-swatch-size` 72px, `--mk-swatch-gap` 12px, `--mk-swatch` per ball.
+
+## dialog (v0.3)
+
+- Engine `createDialog(dialog, options)` on a native `<dialog>` → `{ open(origin?), close(), toggle(), float(), dock(), isOpen, isFloating, element, destroy }`. `open()` without argument grows from the focused control; `open(null)` scales in from .92.
+- Options: `variant` morph | liquid, `placement` center | anchor | side, `backdrop`, `closeOnBackdrop`, `drag`, `float` (key), `autoResize`, `triggers` (`[data-mk-open="<id>"]`), `modal`, `labels`, `onOpen`, `onClose`.
+- Parts: `[data-mk-part]` header, title (names the dialog), description, actions, body (scrolls), footer, close, handle (floating). `[data-mk-close]` anywhere inside closes.
+- Motion (TIMING.dialog): open 0.7 s signature, colour 0.3 s, content blur 8 → 0; close 0.5 s through an inert ghost (content toward the opener on a 2 s path cut at 0.5 s, blur 32, radius 400, fade); fallback .92 / 0.35 s; backdrop 0.5 s signature linear(); auto-resize 0.45 s. Liquid (TIMING.liquid): springs 144/14 (kick 2400) open, 130/18 close. Drag: follow ×0.5, scale 1 − y/400, dismiss > 100 px, restore elastic.out(.5,.5) 0.5 s. Floating: spring 1100/38, glide decay 0.18 s, min 320 × 240, margin 8, `mk-float.<key>`.
+- Element `<mk-dialog>` builds the parts from `heading` / `description` / `shared` / `float`; React `Dialog.*` compound components.
+
+## menu (v0.3)
+
+- `createMenu(dialog, { closeOnSelect, onSelect, … })`: a dialog anchored to its button, transparent backdrop, no drag or auto-resize, content not grown as a group; options `[data-mk-item]` cascade with `flowInMenu` (opacity only, so they can take focus). role menu / menuitem; arrows, Home, End; Enter/Space on non-button items. Event `mk:select` (value = `data-mk-value` or text).
+- `<mk-menu id label keep-open>`; React `Menu.Root/Trigger/Content/Item/Separator`.
+
+## toast (v0.3)
+
+- Store (`components/toast/store.ts`): `toast(message, { origin, duration 4000, tone success|error|info|neutral, action, icon })`, `toast.dismiss(id)`, `toast.clear()`, at most 5 live; timers pause while the deck is open.
+- `createToaster(host, { labels })` draws the cards (the one component that creates markup): stack peek 16 / −5 % / 3 drawn, hover expands (springEase .55, 60 ms) and collapses after 150 ms; origin morph by channels; letters 0.4 s / 20 ms after 0.225 s; exit 24 px + blur 4 in 0.3 s; swipe up 48 px or wheel 80 px dismisses. Host is a manual popover (top layer, above dialogs), role status / aria-live polite.
+- `<mk-toaster>`, React `<Toaster />`; `toast` is exported from `.`, `/elements` and `/react` (one store).
+
+## chat-background (v0.4)
+
+- `createChatBackground(root, { energy 0, scale 1 })` → `{ setEnergy, setScale, busy(on), energy, scale, destroy }`; `chatBackgroundOf(el)` finds a running one. Writes `--mk-chat-orbit-1` (10 − 3.5·e s), `--mk-chat-orbit-2` (15 − 4.5·e s), `--mk-chat-blob-opacity` (.5 + .15·e), `--mk-chat-scale` ((1 + .1·e)·scale); adds the grain (`.mk-chat-background__noise`, SVG turbulence). `busy(true)`: energy 1.6 / scale 1.8 in 0.8 s power2.out; back 0.6 s power2.inOut.
+- `audioEnergy(stream, onEnergy)` → `{ stop }`: FFT 256, smoothing .3, −90…−10 dB, lowest 40 % ×3, attack .8, release .15. The app asks for the microphone.
+- `<mk-chat-background energy scale>` (attributes update in place), `<ChatBackground energy scale />`.
+
+## chat (v0.4)
+
+- `createChat(root, { animateExisting, clearOnSend, labels: { thinking }, onSend })` over `[data-mk-part="messages"]` (+ composer, input, send, mic) → `{ add(role, text), pending(), reply(el | text), confirm(bar), setRecording(on), scrollToLatest(), adopt(el), messages, destroy }`.
+- A MutationObserver animates any new `[data-mk-message]` (`enterMessages` + `scrollToLatest`); history stays still unless `animateExisting`. `pending()` shows `[data-mk-pending]` after 500 ms; `reply` morphs it (Flip 0.7 s, `scale: false`, text width fixed, words rise) or enters normally. Enter / submit → cancelable `mk:send` → `onSend`. `capturePending` + `morphPendingToReply` for frameworks.
+- `<mk-chat background mic placeholder thinking animate-existing>` builds its own list and composer when empty. React `Chat.Root/Messages(pending)/Message(role)/Composer/Confirm` + `useChat()`; `Chat.Messages` is a class component (getSnapshotBeforeUpdate measures the placeholder before React swaps it).
+- Variables: `--mk-chat-radius` 40, `--mk-chat-bubble-radius` 32, `--mk-chat-user-bg/-fg`, `--mk-chat-assistant-bg/-fg`.
+
+## nav (v0.4)
+
+- `createNav(nav, { style, accent, reveal, storageKey, labels, onSelect })` → `{ select(i | value), setStyle(name), setAccent(on), index, style, items, destroy }`. Items: `.mk-nav__buttons .mk-nav__button` (value = `data-mk-value` or `href`); current = `aria-current="page"`; click → cancelable `mk:navigate` (`detail.originalEvent` for SPA routers). `revealShell(nav)` uncovers `.mk-shell` from the first button.
+- CSS: Stepbro's seven `.app-nav.style-N` as `.mk-nav--{clasica|bonita|dock|guapa|tasks|melon|tunnel}`, `variant-1` → `.mk-nav--accent`, mobile-style-1 under 680 px, shell `.mk-shell` / `__view` / `__header` / `__title` / `__content`. Names hidden by a style stay readable (clip, not display none). Current icon fills (`mk-nav-icon` 125 ms, `--mk-icon-fill` registered with `@property`).
+- `<mk-nav nav-style accent reveal storage-key>` (style and accent change in place), `<Nav items active onSelect navStyle accent reveal first actions />`.
+
+## steps (v0.4)
+
+- `createSteps(root, { index, duration .5, animateFirst, target '[data-mk-flow-item]', onChange })` → `{ next, prev, goTo, busy(on), index, count, steps, destroy }` (promises settle on the last requested step). Hidden steps get `hidden`; items flow out/in (opacity only on the way in so the title can take focus); `[data-mk-counter]` rolls (0.9 s); focus to `[data-mk-step-title]` or the first heading; `mk:step`; `busy` → `aria-busy` + the chat background inside.
+- `<mk-steps index>` (index changes move), `<Steps index onChange busy>` + `Steps.Step` (direct children) + `Steps.Counter`.
+
+## Gotcha: GSAP and hidden elements
+
+`gsap.set(el, { clearProps: 'transform' })` measures the element first; an element with no width (a closed dialog, display: none) is moved to the end of the document and back to be measured, which shifts whitespace and disconnects custom elements inside. Engines clear their inline styles with `clearStyles(elements, properties)` instead when the element may be hidden.
+
+Reading a transform (`gsap.getProperty(el, 'y')`, Flip) also writes `translate/rotate/scale: none` inline; engines that only measure clear those afterwards (see `sortable`'s `untouch`).
+
+## Ticket menu (v0.8)
+
+Use `<mk-menu ticket label="Sections">` or `<Menu.Root ticket>` for Siena's ticket presentation. The existing menu engine still handles roles, roving focus, disabled items, selection, Escape, focus return and the dialog lifecycle. Direct factory: `createTicketMenu(dialog, MenuOptions)`; declarative: `data-mk="ticket-menu"`. It uses a local clip-path opening (.9 s) and rows from 150% (1.1 s, .02 stagger), adapting Siena's grid-row panels. The underlying `createMenu` also accepts `ticket: true`.

package/skills/motion-kit/reference/design.md

@@ -0,0 +1,92 @@
+# Design line (Stepbro)
+
+Values from the Stepbro replication kit (`tasks/source/frontend.css`, `tasks/themes/theme.{light,dark}-*.css`, runtime observations of 2026-10-13). Colour values are reproduced; no Stepbro code is shipped.
+
+## Colour
+
+Every theme defines the 37 Material 3 roles `--md-sys-color-<role>` in light and dark:
+background, on-background, surface, surface-dim, surface-bright, surface-container-lowest, -low, (plain), -high, -highest, on-surface, surface-variant, on-surface-variant, inverse-surface, inverse-on-surface, outline, outline-variant, shadow, scrim, surface-tint, primary, on-primary, primary-container, on-primary-container, inverse-primary, secondary, on-secondary, secondary-container, on-secondary-container, tertiary, on-tertiary, tertiary-container, on-tertiary-container, error, on-error, error-container, on-error-container.
+
+Semantic layer (declared on `:root` and every `[data-mk-theme]`):
+
+| `--mk-*` | Role |
+|---|---|
+| `bg` | background |
+| `surface` | surface |
+| `surface-1` … `surface-5` | surface-container-lowest, -low, container, -high, -highest |
+| `text` / `muted` | on-surface / on-surface-variant |
+| `accent` / `on-accent` | primary / on-primary |
+| `accent-soft` / `on-accent-soft` | primary-container / on-primary-container |
+| `secondary-soft` / `on-secondary-soft` | secondary-container / on-secondary-container |
+| `outline` / `outline-soft` | outline / outline-variant |
+| `error` / `on-error` | error / on-error |
+| `error-soft` / `on-error-soft` | error-container / on-error-container |
+| `scrim` / `shadow-color` | scrim / shadow |
+
+Note: Stepbro's dark palettes often set `primary` to white (neogreen dark: `#ffffff`) and put the colour in `primary-container` (`#00f46b`). That is why the default `.mk-button` uses `accent-soft`.
+
+## Themes
+
+| Id | Name | Shown by Stepbro | Seed (dark surface-tint) |
+|---|---|---|---|
+| blue | Blue | yes | #b3c5ff |
+| purple | Purple | yes | #d2bcff |
+| neogreen | Neogreen (default; Money's default) | yes | #00e563 |
+| red | Red | yes | #ffb4ac |
+| pink | Pink | yes | #f7acff |
+| pastel-pink | Pastel Pink | yes | #ffcee8 |
+| brown | Brown | yes | #ffb783 |
+| super-blue | Super Blue | yes | #bcc2ff |
+| gray | Gray | yes | #c6c6c6 |
+| oled | Oled (Tasks' default; dark only, light uses Black) | yes | #9fb8e4 |
+| black, green, orange, cold-blue, modern-1, funny, new, new2, black-green | — | hidden | see `THEMES` |
+
+Selectors: light `[data-mk-theme="id"]`; dark `[data-mk-theme="id"][data-mk-mode="dark"]` or inside `[data-mk-mode="dark"]`; system dark through `prefers-color-scheme` unless `data-mk-mode="light"`. Default palette (neogreen) sits in `:where(:root)` with zero specificity.
+
+Generator: `generateTheme(seed, { variant, contrast })` (Material Color Utilities 0.3; variants tonal-spot, vibrant, expressive, neutral, content, fidelity, monochrome) → same 37 roles; `themeCss(id, palettes)` → same selectors; `applyTheme(seed, { id })` injects and selects it.
+
+## Type
+
+| Role | Large | Medium | Small |
+|---|---|---|---|
+| display | 57/64, 400, −0.25 | 45/52, 400 | 36/44, 400 |
+| headline | 32/40, 400 | 28/36, 400 | 24/32, 400 |
+| title | 22/28, 400 | 16/24, 500, .15 | 14/20, 500, .1 |
+| body | 16/24, 400, .5 | 14/20, 400, .25 | 12/16, 400, .4 |
+| label | 14/20, 500, .1 | 12/16, 500, .5 | 11/16, 500, .5 |
+
+Tokens `--md-sys-typescale-<role>-<size>-{font,size,line-height,weight,tracking}`; classes `.mk-type-<role>-<size>`. Stepbro's bundle writes weights as `400px`; here they are plain numbers (adaptation). Fonts: DM Sans (`--mk-font`), Geist Mono (`--mk-font-mono`), Material Symbols Rounded (`.mk-icon`).
+
+## Shape, space, motion
+
+- Radii: xs 8, sm 12, md 16, lg 24, xl 32 (bubble), 2xl 40 (dialog, observed 400 × 40 on desktop), 3xl 48 (chat window), 4xl 64 (mobile dock), full 999. Mobile dialogs go full screen with radius 0 under 680 px.
+- Space: `--mk-space-n` = n × 4 px (1…16).
+- CSS curves: `--mk-ease-signature`, `--mk-ease-tint` (same), `--mk-ease-flow` (`cubic-bezier(.25,.1,.25,1)`), `--mk-ease-close`, `--mk-ease-blur-away`, `--mk-ease-nav-radius` (`.38,.49,0,2`), `--mk-ease-nav-move` (`.38,.49,0,1.2`), `--mk-ease-swatch` (`.38,.49,0,1.5`), `--mk-ease-swatch-light` (`.11,1,0,1`), `--mk-ease-slot`. Durations `--mk-dur-fast .25s`, `--mk-dur .45s`, `--mk-dur-slow .7s`.
+
+## Controls (Stepbro's Material Web overrides)
+
+| Control | Values |
+|---|---|
+| Button | 40 px, 24 px sides, capsule; filled = primary-container; small 32 px, 16 px sides, radius 12; state layer 8 % hover, 10 % focus/press |
+| Field | filled, surface-container-high, radius 16, no active indicator, 56 px; error → error-container |
+| Filter chip | capsule, no outline, container-high; selected primary-container / on-primary-container |
+| Checkbox | radius 6 |
+| Menu | radius 16 |
+| Switch | 52 × 32 track, thumb 16 → 24 px |
+
+## Glass (Dousan Miao, v0.5)
+
+`.mk-glass` on any button, link or chip; one element, no JS (`css/controls/glass.css`). Dousan's layers:
+
+| Layer | Value |
+|---|---|
+| Surface | `linear-gradient(-75deg, a, b, a)`: a 5 % / b 22 % white (dark: 2 % / 8 %); `backdrop-filter: blur(4px)`; inner/outer shadows (`--mk-glass-shadow`, `-hover`, `-active`); radius 999vw |
+| Ring (`::before`) | `conic-gradient(from var(--mk-glass-angle-1), …)` + vertical gradient, masked to a `clamp(1px, .0625em, 4px)` border (`mask-composite: exclude`); angle −75° → −125° on hover, 0.5 s (`@property`) |
+| Shine (`::after`) | band `transparent → 55 % white 40–50 % → transparent` at `--mk-glass-angle-2` (−45°), `200% 200%`, `mix-blend-mode: screen`; position 0 % → 25 % hover → `50% 15%` and −15° pressed, 0.5 s `cubic-bezier(.25,1,.5,1)` |
+| Shadow (`.mk-glass__shadow`, optional) | blurred gradient ring 22 % → 10 % black (dark 85 % → 55 %) under the button; only its lower part shows |
+| Press | `scale(.95)` on Dousan's 400/10 spring (`--mk-ease-press`, `--mk-dur-press`) |
+
+Light/dark through `light-dark()` (themes set `color-scheme`). Without `backdrop-filter`: an almost opaque background. It is layered CSS, not refraction — like the original.
+
+Related tokens: `--mk-ease-glass`, `--mk-ease-sheet`, `--mk-ease-siena`, `--mk-ease-quint`, `--mk-ease-press` / `--mk-dur-press` (400/10), `--mk-ease-success` / `--mk-dur-success` (260/18). `motionSpring(k, c)` and `springLinear(k, c)` turn any Motion spring into a GSAP ease or a CSS `linear()`.
+

package/skills/motion-kit/reference/recipes.md

@@ -0,0 +1,172 @@
+# Recipe parameters and origin
+
+Values were read from the public bundles of spencergabor.com (Nuxt 3, analysed with REA on 2026-10-14) and Stepbro Tasks/Money, then re-implemented. No third-party code is shipped.
+
+## Shared
+
+| Name | Value | Origin |
+|---|---|---|
+| Spring | `v = v·friction^dt + (target − x)·stiffness·dt; x += v·dt`, stiffness .05, friction .8 | spencergabor.com `useSpring` |
+| Frame loop | one `gsap.ticker` callback, `dt = Δms / (1000/60)`, capped at 3; recipes subscribe only while visible | spencergabor.com shared rAF loop |
+| `--mk-ease-elastic` | `linear(0, .5737 7.6%, … 1.0011 81.26%, 1)` | spencergabor.com `--ease-out-elastic` |
+| `--mk-ease-elastic-hover` | `linear(0, .2178 2.1%, … .9981 86.66%, 1)` | spencergabor.com `--ease-out-elastic-100-30` |
+| `ELASTIC` (GSAP) | `elastic.out(1, 0.45)` | visual match of `--mk-ease-elastic` |
+| `mk-signature` | `M0,0 C0.308,0.19 0.107,0.633 0.288,0.866 0.382,0.987 0.656,1 1,1` | Stepbro signature curve |
+| `mk-flow` | `M0,0 C0.25,0.1 0.25,1 1,1` | Stepbro flowSoft |
+| `mk-close` | `.56,.27,0,1` | Stepbro close fade |
+| `--mk-shadow` | `0 9px 21px rgb(0 0 0/.1), 0 38px 38px rgb(0 0 0/.09), 0 85px 51px rgb(0 0 0/.05)` | spencergabor.com `--shadow` |
+
+## spring-cards
+
+- Start offset: random ±100 px, released after 100 ms.
+- Pointer push: `dx = (px − cx)/innerWidth·2`, `dy = (py − cy)/innerHeight·2`, `k = max(0, 1 − hypot(dx, dy))^6 · .4`, `push += movement·k`, `push *= .9^dt`.
+- CSS: `rotate: calc(tilt − velocity·.25deg)`; tilts 2°, −3°, 6°, −2°; vertical offsets 5 %, −6 %, 5 %, −4 %.
+- Entrance: `scale 0 → 1`, 1 s, elastic, `i·.08s + .4s`.
+- Portfolio change: 4:3 cards and −1.5 % overlap (Spencer: square, −6 %) so text on covers stays readable.
+
+## curved-carousel
+
+- Friction .85; drag velocity = pointer movement per frame; on release `v·2`, rest `x − v·f/(1−f)`, snap to the nearest slide, approach `x += (target − x)(1 − f^dt)`.
+- Tap: under 6 px of travel (Spencer: < 10 px and < 100 ms).
+- Wheel: `v −= deltaX·.2` when horizontal; snap 150 ms after the last wheel event.
+- Arc: `rotate: t·.03deg`, origin `50% 70vw`, `translateY: cos(t·π/1000)·−3rem + 3rem`, title opacity `cos(t·π/600)`; `t` = slide centre − viewport centre in px.
+- Entrance: media from `scale .8; translate 0 20%`, 1.4 s elastic, delay `sin(k·π/2)·.12s`.
+
+## pile
+
+- Layers: `rotation = rand(2,5)·(±1 alternating)`, `offsetX = rand(4,10)·random sign`, `offsetY = (n − i)·5`; seeded (mulberry32) so SSR and client match.
+- CSS: `rotate: rot·.6deg`, `translate: px·.3% py·.3%` (Spencer: .5deg / .25%).
+- In view: media `scale .7 → 1`, shadow `0 → 1`, .8 s elastic; hover 1.01/1.02/1.03, active .97/.98/.99.
+
+## words
+
+- `scaleY 0 → 1`, `yPercent 25 → 0`, origin bottom, .8 s, `ELASTIC`, 100 ms between words, 60 ms between letters.
+- Spencer did this with CSS transitions and `@starting-style`; the package uses GSAP SplitText so reduced motion and text replacement work.
+
+## flow (Stepbro)
+
+- From `y −20`, `blur(16px)`, opacity 0 → 0, 0.5 s, 50 ms stagger, `mk-flow`.
+
+## pop
+
+- `scale .7 → 1` + opacity, 1.1 s, `ELASTIC`.
+
+## fit-text
+
+- Measures at 100 px, sets `font-size = 100 · available · .995 / width`; refits on parent width changes only.
+
+## stretch-footer
+
+- Phantom of 100dvh at the end of the flow; `g = lerp(g, scrollY, 1 − e^(−.9·dt))`.
+- `scaleY = map(g, phantomTop − vh, phantomTop, 0, 1)`; `offsetY = map(…, vh − titleBottom, 0)`, both clamped.
+
+## radial-menu
+
+- Item position: `translate(sin(i·.9 + 1.5708)·−r, cos(i·.9 + 1.5708)·r)`, r = 3.6rem (Spencer: spacing .75, start 1.25).
+- Open: `scale .5 → 1`, .5 s elastic, `i·.05s`; close: .15 s `cubic-bezier(.55,.055,.675,.19)`.
+
+## pill
+
+- Hover `scale 1.05` + shadow, active `.95`, .8 s elastic; `.mk-stretch` hover `scaleY(1.2)`, 1 s elastic-hover.
+
+## Stepbro v0.2 (Tasks `especificacion-replicacion.json`, Money `replication-catalog.json`)
+
+| Name | Value | Kit id |
+|---|---|---|
+| `mk-fade-away` / `mk-blur-away` | `.56,.27,0,1` / `.37,.35,0,1` | modal-close-origin |
+| `mk-chat-scroll` | `M0,0 C0.308,0.19 0.318,0.567 0.5,0.8 0.593,0.921 0.656,1 1,1` | chat-scroll |
+| `mk-layout-reflow` / `mk-sortable-land` | spring path `FA(.52)` / `FA(.62)` (stiffness 5.6, sampled 72 steps) | task-layout, task-drag |
+| `--mk-ease-signature` | Stepbro's own `linear()` sampling of the signature (its backdrop tint) | tasks-modal-backdrop |
+
+### flowIn / flowOut / stepChange
+
+- In: `y −20 → 0` (style 2: `scale .9 → 1`), blur 16 → 0, opacity, 0.5 s, 50 ms, `mk-flow`; `reverse`, `target` selector. Out: `y 0 → 20`, blur 0 → 16, opacity 1 → 0.
+- Step change: await out → mutate → next frame → in; 0.5 s (0.45 in verification dialogs).
+- Named: menu `style 2`, .9, blur 4, .35 s, 40 ms, delay .1, reverse · palette .5, blur 4, .1 s, 10 ms · form `[data-flow-item]` .9, blur 8, .35 s, 40 ms · landing .85, blur 24, .4 s, 50 ms, delay .15 · content `[data-flow], .markdown-content > *` style 2, .6 s, 60 ms.
+
+### tabs
+
+- Indicator to the selected tab's box (Flip.fit in the original), 0.45 s, signature; centres a scrolling list; reduced: instant.
+
+### counter
+
+- `numberSoft` (= `mk-flow`), 0.6 s (prices 0.7 s), from the value shown. Onboarding reveal: rAF, 0.9 s, `1 − (1 − p)^3`.
+
+### details
+
+- Height `0 ↔ scrollHeight` + content opacity, 0.32 s, signature; chevron 0 ↔ 180°, 0.25 s; `clearProps` after opening so nested content can grow.
+
+### reveal
+
+- Radial gradient veil from the origin's centre (else last pointer, else the centre), progress 0 → 100 % with `power2.out`, then the veil fades with `power1.out`; overshoot 2. Speeds (travel/fade): fast .5/.25, normal .7/.35, slow 1.05/.5, slower 1.6/.75 s.
+
+### reflow
+
+- `Flip.from` on `data-flip-id`, 0.62 s `mk-layout-reflow`, `zIndex 3`; new items `scale .94 → 1` + opacity in 0.372 s.
+
+### slot-text
+
+- Per changed letter: out and in by one line height, 300 ms `cubic-bezier(.34,1.56,.64,1)`, 45 ms cascade, 50 ms exit offset, letter fade 280 ms, deterministic tilt ≤ 5° (noise `sin((i+1)·12.9898 + c·78.233)·43758.5453`), width eases `cubic-bezier(.2,0,0,1)` (≥ 140 ms); trailing letters collapse at 55 % of their time.
+
+### chat (motion functions)
+
+- Bubble `scale .5 → 1`, blur 24 → 0, autoAlpha, 0.7 s signature, 60 ms; origin right (user) / left (assistant). Words `y 16 → 0`, blur 6 → 0, 0.25 s, 50 ms, `back.out(1)`; skip `table`/`pre`; whole block if splitting grows the text by > ½ line.
+- Composer: height → scrollHeight (min 64), 0.18 s `power2.out`. Scroll to bottom: 0.35 s `mk-chat-scroll`.
+
+### sortable
+
+- Stepbro Tasks `useDragReorder` ("transform" mode). Threshold 6 px; floating copy (cloned into the item's own list, `position: fixed`, so the list's CSS still styles it) follows a spring 1100/38 with mass `clamp(√(w·h / 24000), 1, 2.5)`; tilt spring 170/13 toward `14·tanh(torque / 14)`, torque from smoothed velocity (×2e-3) and acceleration (×45e-5) about the grab point (arm Y ≥ .4). Lift 0.18 s `power2.out`, scale `1 + .03·lift`, shadow `0 12·lift 32·lift rgb(0 0 0 / .22·lift)`.
+- Neighbours: `y` by the item's height + the space to its neighbour, 0.62 s `mk-layout-reflow` (FA .52); insertion index by the pointer against item midpoints; group by pointer x (then y). Land 0.42 s `mk-sortable-land` (FA .62) to the slot, cross-fade 0.277 s `power1.inOut` to a copy styled by the destination list.
+- Auto-scroll: scrollable ancestors (and the page) within 56 px of an edge, `ceil(16 · min(1, d / 56))` px a frame. Touch (`pointer: coarse`): handle only. Escape / pointercancel: back. Keyboard (added): Space/Enter, arrows, Escape; reflow 0.62 s; `aria-live` announcements.
+
+## iyo.ai (v0.7, REA research `REA - iyo.ai`)
+
+### island (navbar `nav`/`d3`)
+
+- Shell fixed top 2rem, 23.5rem wide (28rem ≥ 1920 px; 1rem / 5vw side margins ≤ 767 / 479 px), radius 3em → 2em (0.4 s `cubic-bezier(.4,0,.2,1)`, closing 0.45 s late). Glass `blur(20px)` on `#38383899` + `linear-gradient(141deg, #a9c2f214, #62718c24)`.
+- Content `grid-template-rows 0fr → 1fr`, 0.6 s `cubic-bezier(.625,.05,0,1)`, 0.125 s late. Backdrop black 0 → .4, 0.7 s `cubic-bezier(.5,.5,0,1)`, 0.1 s late. Rows `opacity 0 → 1`, `translateY 3em → 0`, 0.6 s, delay `0.15 + i·0.025` s.
+- Entrance `yPercent −300 → 0`, 1.8 s (no ease given, so GSAP's `power1.out`). Card hover: siblings 20 % (0.15 s ease-out), picture 1.04 (0.4 s, back 0.3 s `cubic-bezier(.25,.46,.45,.94)`). Closes on a scroll > 1 px after wheel / touchmove.
+
+### card-dock (`product-cards`, `PM`)
+
+- Stack, from the end: `translateY(90 % / 180 % / 270 % / 360 %) scale(.93 / .87 / .8 / .73)`; open 0.8 s, close 0.64 s, `cubic-bezier(.48,.01,0,1.08)`. Card 4rem → 4.5rem, 0.6 s `cubic-bezier(.77,0,.175,1)`; surface `#38383899 → #555555b0` 0.3 s `cubic-bezier(.65,0,.35,1)`; `blur(19px)`, border `#8a8a8a1a`, radius .9rem.
+- Title opacity 0.5 s, `translateX(−15 % → −120 %)` 0.4 s. Intro: spread 1600 ms from the call, then the CTA fades in. Tablet (768–1024 px, `hover: none`): the first tap opens.
+
+### snap-strip (`product-card-mobile`, `CM`)
+
+- 5000 ms a card, 2000 ms wait after mousedown / touchstart / wheel, `data-delay 500`, cards 68vw. iyo uses Smooothy (snap physics, cloned loop); here native scroll-snap.
+
+### fill-text (`GM`)
+
+- SplitText `words, chars`; `fromTo(chars, { autoAlpha: .2 }, { autoAlpha: 1, stagger: .1, ease: 'linear' })` (0.5 s each), scrubbed `top 90%` → `center 40%`.
+
+### particle-hero (`wK` / `YW` / `dE`, adapted)
+
+- iyo: 1280² points, RGBA float ping-pong, Newton step .4 × 4 toward the field's zeros, Chladni `sin(mπx/a)·sin(nπy/b)`, destination by hash vs `texturePercent`, damping `.985^dt60`, pointer radius .16 / force .0225 × smoothed speed (`min(d·5, 1)`, `.8 old + .2 new`), fade in 1 s after .3 s `power2.out`. Timeline: modes m, n ∈ {3, 5, 7} every 6–12 s; frequency 20–45 every 5–10 s; Chladni 0–5 over 1.2–3 s `power2.inOut`; word cycle N = 3–6 s (out .4N, in .6N to .4–.8, hold 2–4 s).
+- Kit: own shaders, size² points (128² by default), damping .91, pointer radius .28, words drawn locally (dark pixels < 120 of a 640 × 320 canvas), Canvas2D fallback (~1800 points).
+
+## Collections and menu (v0.8)
+
+All six have a `createX(root, options)` factory in the main entry, `useX(ref, options, deps)` in `/react`, CLI entry and vanilla/React playground page. `autoInit()` supports all six. Destroy restores the host and clears timers, tweens, listeners, observers and generated markup.
+
+| Name | Markup | Options and controls | Source |
+|---|---|---|---|
+| ticket-menu | `.mk-dialog.mk-menu` dialog with `[data-mk-item]` | `MenuOptions`; `open`, `close`, `toggle`, `items`, `isOpen`; also `<Menu.Root ticket>` / `<mk-menu ticket>` | Siena: .9 s opening, 1.1 s rows from 150%, stagger .02; clip-path adapts the site's grid panels |
+| infinite-reel | `.mk-infinite-reel > [data-mk-reel-track]` | `axis x/y`, `speed 0`, `friction .95`; `moveBy`, `position`, `pause`, `resume` | Siena: DOM/inertia adaptation, without original scene or snap |
+| repel-bento | `.mk-repel-bento` with cards | `distance 30`, `breakpoint 1024`; `play`, `reset` | Dousan: entry spring 60/15, stagger .006, .6 vector; neighbours min(5000/d,30), spring 300/25 |
+| rotator | `.mk-rotator` with one item per child | `interval 8000`, `autoplay true`, `index`, `onChange`; `select`, `next`, `previous`, `index` | Dousan testimonials: .25 s, y 5→0 |
+| drag-ruler | `.mk-drag-ruler[aria-label]` | `min 0`, `max 8`, `step .1`, `value max`, `pixelsPerUnit 60`, `onChange`; `set`, `value`; `mk:change` | Dousan's years ruler |
+| dock-pill | `.mk-dock-pill` with `[data-mk-dock-item]` links/buttons | `index`, `onSelect`; `select`, `index`; `mk:select` | Dousan's activeTabPill, spring 380/30 |
+
+Reduced motion disables inertia, autoplay, entry and repulsion, keeping manual navigation. Reel copies are inert, aria-hidden and have no duplicate IDs. Ruler supports arrows, Home/End and PageUp/PageDown. Dock supports arrows/Home/End and skips disabled items. Keep rotator controls outside its child list.
+
+## Image shaders (v0.9, explicit `/gl`)
+
+`createLiquidBlend`, `createMatcap`, `createShaderGrain`, `createShaderBlur` share `{ images?, progress?, amount?, maxDpr? }` and return `{ setProgress, setAmount, pause, resume, mode, destroy }`. Images default to the host's first two `<img>` elements; one image is repeated. Same-origin or CORS-enabled images; loading is observed. A host with explicit dimensions is required. React hooks have the corresponding `use…` names. These factories are not exported from the main entry or registered with autoInit.
+
+- Liquid: `amount .15`, progress 0→1 blends the two textures with centre-weighted UV waves. OFFFICE `liquid-swap` mechanism adapted to images without models or render targets.
+- Matcap: analytic sphere, normal UV .495+.5, hemispheric light and gain .15; optional image used as matcap. OFFFICE's model renderer is not included.
+- Grain: own temporal hash, amount .07 from Siena's postprocess; 24 Hz grain, fixed frame for reduced motion.
+- Blur: amount 5 image pixels, seven weighted samples with Siena's .19648255/.29690696/.09447040/.01038136 weights and 1.41176471/3.29411765/5.17647059 offsets. Progress rotates the direction x→y.
+
+WebGL unsupported, compilation/texture error or context loss leaves the original HTML available. Context restoration rebuilds resources. The canvas is decorative; loops pause offscreen and in hidden tabs. No Three/OGL dependency and no shaders/assets copied from the researched sites.