@yewdiel21/motion-kit 0.9.0 → 0.10.0

package/skills/motion-kit/SKILL.md

@@ -1,189 +1,209 @@
----
-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.
+---
+name: motion-kit
+description: Use motion-kit components and animation recipes in vanilla JavaScript, Astro and React. Includes dialogs, menus, toasts, chat, navigation, onboarding, sortable lists, text and scroll effects, collections, themes, CSS controls and optional WebGL. Use for component installation, configuration, composition and motion-kit API examples.
+---
+
+# motion-kit
+
+Motion components for vanilla JavaScript, Astro and React. Entry points:
+
+| 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):
+
+```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 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 visible themes) + 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` (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` (`.mk-roll[data-text]` for the label and `.mk-roll__arrow` for the arrow), `.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`, `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`, `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 options: [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 | 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 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`, `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: 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: 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`, `dock`, `guapa`, `tasks`, `melon`, `tunnel` (`NAV_STYLES`), one glass bar under 680 px; `accent` highlights the active page. 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 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 parameters and controls.
+
+## Referencias y básicos (próxima versión)
+
+- Contact CTA en tres piezas: `createJoinedCta`, `useJoinedCta`, `data-mk="joined-cta"`; tres spans dentro de `.mk-joined-cta`.
+- Media contrazoom: `createImageZoom`, `useImageZoom`, `data-mk="image-zoom"`; `[data-mk-zoom-frame]` con imagen dentro.
+- Fuente alternada/rodillo y overlay propio opcional: `createFontCycle`/`useFontCycle` (`font-cycle`); navegación de categorías con miniaturas: `createThumbnailNav`/`useThumbnailNav` (`thumbnail-nav`).
+- Botones de presión y etiqueta film: `createActionButton`/`useActionButton` (`action-button`); hero editorial de cine: `createFilmHero`/`useFilmHero` (`film-hero`).
+- Hero/tarjetas/contacto: `createEditorialReveal`/`useEditorialReveal` (`editorial-reveal`), compone mask-text/cascade/parallax/contrast.
+- Dock bento: `createStudioDock`, `<StudioDock>`, `<mk-studio-dock>`, `useStudioDock`; páginas, contacto y reel.
+- Video modal nativo: `createTrailer`, `<Trailer>`, `<mk-trailer>`, `useTrailer`; video suministrado por la app; fullscreen se aplica a su stage.
+- Básicos: `createQuantity`/`<Quantity>`/`<mk-quantity>`; `createPagination`/`<Pagination>`/`<mk-pagination>`; `createHoverCard`/`<HoverCard>`/`<mk-hover-card>`; `createInputOtp`/`<InputOtp>`/`<mk-input-otp>`.
+- Quantity limita min/max/step; pagination limita total/page y mantiene foco; hover-card soporta hover/foco/tap/Escape; OTP usa un input nativo con slots decorativos para pegado/autofill/ceros iniciales.
+- En React, props value/page opcionales controlan el estado; al omitirlas los controles conservan edición/selección entre cambios de opciones.
+- Calendario de citas: `createCalendar`/`<Calendar>`/`<mk-calendar>` (`calendar`); eventos `{id,title,start,end?,status?,color?}`, `setEvents`, `mk:select`/`mk:event`/`mk:navigate`; requiere `[data-mk-calendar-grid]`.
+- Reservas/citas: `createSlotPicker`/`<SlotPicker>`/`<mk-slot-picker>` (`slot-picker`); `slots` lista, mapa por día o función/promesa; valor `YYYY-MM-DDTHH:mm` en `[data-mk-slot-value]` y `mk:change`.
+- Titular que adelgaza bajo el puntero: `createWeightHover`/`useWeightHover` (`weight-hover`), fuente variable con eje `wght`.
+- Stickers holográficos que se despegan: `createSticker`/`useSticker` (`sticker`), arte `.mk-sticker__pill`/`__badge`/`__art`, `--mk-sticker-rot`, `aria-hidden` si es decoración.
+- Navegación que aparece con el scroll: `createScrollDock`/`useScrollDock` (`scroll-dock`), `hideWhen` para el footer, `.mk-scroll-dock--sticky` dentro de contenedores con scroll.
+- Hora de otra zona: `createLocalClock`/`useLocalClock` (`local-clock`); píldora de disponibilidad `.mk-status` + `.mk-status__dot` (controles).
+- Cada carpeta src/recipes/<name>/README.md o src/components/<name>/README.md define marcado, valores, eventos y controles. No reconstruir estas APIs por intuición.

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

@@ -8,19 +8,19 @@ A component brings its own markup and styles; recipes animate yours. Each one li
 | `<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. |
+| `README.md` | Markup (HTML and React), options/attributes, events, CSS variables, accessibility and parameter defaults. |
 
 `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
+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`.
+1. Implement the engine with defaults from `TIMING`, reduced-motion support and complete cleanup in `destroy()`.
 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.
@@ -67,7 +67,7 @@ It writes the five files, `test/components/demo-card.test.ts`, `apps/playground/
 ## 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`).
+- CSS: 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)
@@ -83,4 +83,4 @@ Reading a transform (`gsap.getProperty(el, 'y')`, Flip) also writes `translate/r
 
 ## 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`.
+Use `<mk-menu ticket label="Sections">` or `<Menu.Root ticket>` for 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 grid-row panels. The underlying `createMenu` also accepts `ticket: true`.

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

@@ -1,6 +1,6 @@
-# Design line (Stepbro)
+# Design tokens and themes
 
-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.
+Color roles, typography, shape and controls used by the components.
 
 ## Colour
 
@@ -23,22 +23,22 @@ Semantic layer (declared on `:root` and every `[data-mk-theme]`):
 | `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`.
+Note: 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) |
+| Id | Name | Visible by default | Seed (dark surface-tint) |
 |---|---|---|---|
 | blue | Blue | yes | #b3c5ff |
 | purple | Purple | yes | #d2bcff |
-| neogreen | Neogreen (default; Money's default) | yes | #00e563 |
+| neogreen | Neogreen (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 |
+| oled | Oled (dark theme; 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.
@@ -55,15 +55,15 @@ Generator: `generateTheme(seed, { variant, contrast })` (Material Color Utilitie
 | 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`).
+Tokens `--md-sys-typescale-<role>-<size>-{font,size,line-height,weight,tracking}`; classes `.mk-type-<role>-<size>`. Font weights are unitless. 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.
+- Radii: xs 8, sm 12, md 16, lg 24, xl 32 (bubble), 2xl 40 (dialog), 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)
+## Controls
 
 | Control | Values |
 |---|---|
@@ -74,9 +74,9 @@ Tokens `--md-sys-typescale-<role>-<size>-{font,size,line-height,weight,tracking}
 | Menu | radius 16 |
 | Switch | 52 × 32 track, thumb 16 → 24 px |
 
-## Glass (Dousan Miao, v0.5)
+## Glass
 
-`.mk-glass` on any button, link or chip; one element, no JS (`css/controls/glass.css`). Dousan's layers:
+`.mk-glass` on any button, link or chip; one element, no JS (`css/controls/glass.css`). layers:
 
 | Layer | Value |
 |---|---|
@@ -84,9 +84,9 @@ Tokens `--md-sys-typescale-<role>-<size>-{font,size,line-height,weight,tracking}
 | 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`) |
+| Press | `scale(.95)` on 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.
+Light/dark through `light-dark()` (themes set `color-scheme`). Without `backdrop-filter`: an almost opaque background. It is layered CSS, not refraction.
 
-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()`.
+Related tokens: `--mk-ease-glass`, `--mk-ease-sheet`, `--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()`.