@yewdiel21/motion-kit 0.9.1 → 0.10.0

package/skills/motion-kit/SKILL.md

@@ -1,189 +1,209 @@
----
-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.
+---
+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/src/auto/auto-init.ts

@@ -1,3 +1,22 @@
+import { createQuantity } from '../components/quantity/engine';
+import { createPagination } from '../components/pagination/engine';
+import { createHoverCard } from '../components/hover-card/engine';
+import { createInputOtp } from '../components/input-otp/engine';
+import { createJoinedCta } from '../recipes/joined-cta/create-joined-cta';
+import { createImageZoom } from '../recipes/image-zoom/create-image-zoom';
+import { createFontCycle } from '../recipes/font-cycle/create-font-cycle';
+import { createThumbnailNav } from '../recipes/thumbnail-nav/create-thumbnail-nav';
+import { createActionButton } from '../recipes/action-button/create-action-button';
+import { createFilmHero } from '../recipes/film-hero/create-film-hero';
+import { createEditorialReveal } from '../recipes/editorial-reveal/create-editorial-reveal';
+import { createStudioDock } from '../components/studio-dock/engine';
+import { createCalendar } from '../components/calendar/engine';
+import { createSlotPicker } from '../components/slot-picker/engine';
+import { createWeightHover } from '../recipes/weight-hover/create-weight-hover';
+import { createSticker } from '../recipes/sticker/create-sticker';
+import { createScrollDock } from '../recipes/scroll-dock/create-scroll-dock';
+import { createLocalClock } from '../recipes/local-clock/create-local-clock';
+import { createTrailer } from '../components/trailer/engine';
 import { ScrollTrigger } from '../core/gsap';
 import { warnOnce, type Instance } from '../core/types';
 import { createSpringCards } from '../recipes/spring-cards/create-spring-cards';
@@ -39,6 +58,25 @@ import { createDockPill } from '../recipes/dock-pill/create-dock-pill';
 type Factory = (el: HTMLElement, options: Record<string, unknown>) => Instance;
 
 const factories = {
+  'joined-cta': createJoinedCta,
+  'image-zoom': createImageZoom,
+  'font-cycle': createFontCycle,
+  'thumbnail-nav': createThumbnailNav,
+  'action-button': createActionButton,
+  'film-hero': createFilmHero,
+  'editorial-reveal': createEditorialReveal,
+  'studio-dock': createStudioDock,
+  'trailer': createTrailer,
+  'quantity': createQuantity,
+  'pagination': createPagination,
+  'hover-card': createHoverCard,
+  'input-otp': createInputOtp,
+  'calendar': createCalendar,
+  'slot-picker': createSlotPicker,
+  'weight-hover': createWeightHover,
+  'sticker': createSticker,
+  'scroll-dock': createScrollDock,
+  'local-clock': createLocalClock,
   'spring-cards': createSpringCards,
   'curved-carousel': (el, options) =>
     createCurvedCarousel(el, {

package/src/components/calendar/README.md

@@ -0,0 +1,82 @@
+# calendar
+
+El calendario de Melon Mind. Tiene vista de mes y de semana, día de hoy marcado y eventos como chips con estado (pendiente, completado o cancelado), hora y color propio.
+
+- **Al cargar:** los días entran desde arriba con blur (y −20 px, blur 16 → 0, 0.5 s), 5 ms uno tras otro, y después los eventos, 20 ms uno tras otro. Es el `flowChilds` del `CalendarComponent` original.
+- **Cambiar de mes o semana:** la rejilla vieja sale 30 px hacia un lado (0.12 s) y, cuando ya casi no se ve, la nueva entra 30 px desde el otro (0.25 s `ease-out`), como los horarios de su selector de citas. Van en secuencia, sin fundido cruzado, para que no se mezclen dos meses llenos de eventos. Luego vuelven a entrar los eventos.
+- **Hover:** el fondo del día cambia en 0.3 s y el número tiene resorte de radio y escala (`cubic-bezier(.38,.49,0,2)`).
+
+Origen: patrón observado en la app de Melon Mind.
+
+## HTML / Astro
+
+```html
+<mk-calendar class="mk-calendar" locale="es" first-day="0"
+  events='[{"id":1,"title":"Ana","start":"2026-10-23T10:00","status":"pending"}]'>
+  <div class="mk-calendar__header">
+    <h3 class="mk-calendar__title" data-mk-calendar-title>Calendario</h3>
+    <div class="mk-calendar__views" role="group" aria-label="Vista">
+      <button type="button" data-mk-calendar-view="month">Mes</button>
+      <button type="button" data-mk-calendar-view="week">Semana</button>
+    </div>
+    <button type="button" class="mk-calendar__nav" data-mk-calendar-prev aria-label="Anterior">←</button>
+    <button type="button" class="mk-calendar__nav" data-mk-calendar-today>Hoy</button>
+    <button type="button" class="mk-calendar__nav" data-mk-calendar-next aria-label="Siguiente">→</button>
+  </div>
+  <div data-mk-calendar-grid></div>
+</mk-calendar>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-calendar']);
+</script>
+```
+
+Sólo `[data-mk-calendar-grid]` es obligatorio. Las demás piezas del header son opcionales. Si cambias el atributo `events`, los eventos se actualizan sin perder el mes ni el foco. Sin custom element: `createCalendar(root, opciones)`.
+
+## React
+
+```tsx
+<Calendar
+  events={citas}
+  onSelect={(day) => abrirDia(day)}
+  onEventClick={(event) => abrirCita(event.id)}
+/>
+```
+
+`events` y `selected` se actualizan en el sitio. `date` y `view` son iniciales: el usuario navega libremente.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `date` | `date` | hoy | Mes o semana inicial (`Date` o `"2026-10-23"`) |
+| `view` | `view` | `'month'` | `'month'` o `'week'` |
+| `firstDay` | `first-day` | `0` | Primer día de la semana (0 = domingo) |
+| `locale` | `locale` | `'es'` | Nombres de mes y día, formato de hora |
+| `events` | `events` (JSON) | `[]` | `{ id, title, start, end?, allDay?, status?, color? }` |
+| `maxEvents` | `max-events` | `3` | Chips por día en la vista de mes antes de «+N más» |
+| `selected` | `selected` | — | Día seleccionado |
+| `today` | `today` | — | Fija «hoy» (demos, pruebas) |
+| `labels` | — | español | `more(n)`, `events(n)`, `status` |
+| `onSelect(date)`, `onEventClick(event)`, `onNavigate({start, end, view})` | — | — | Callbacks |
+
+API: `next()`, `prev()`, `goToday()`, `setDate(d)`, `setView(v)`, `setEvents(list)`, `select(d | null, notify)`, `date`, `view`, `selected`, `range`, `destroy()`. Eventos DOM: `mk:select` `{date, key}`, `mk:event` `{event}` y `mk:navigate` `{start, end, view}`.
+
+Un evento con `end` en otro día aparece en cada día que cubre, hasta dos meses.
+
+## Variables CSS
+
+`--mk-calendar-gap`, `--mk-calendar-radius`, `--mk-calendar-day-height` y `--mk-calendar-event-color` (por evento, con `color`).
+
+## Accesibilidad
+
+Rejilla ARIA (`grid` / `row` / `columnheader` / `gridcell`) con un solo botón de día en el orden de tabulación:
+
+| Tecla | Acción |
+|---|---|
+| Flechas | Día anterior/siguiente, misma semana anterior/siguiente |
+| Inicio / Fin | Principio/fin de semana |
+| RePág / AvPág | Mes anterior/siguiente (con Mayúsculas, año) |
+| Enter / Espacio | Seleccionar el día |
+
+Cada día anuncia la fecha completa y cuántos eventos tiene. Hoy lleva `aria-current="date"`. Los chips son botones con título, hora y estado. En móvil (< 680 px) los chips del mes se reducen a puntos de color. Con movimiento reducido no hay entradas, deslizamiento ni transiciones.