Web Motion

---
name: Web Motion
description: >-
  Add production-grade motion and animation to any web app. Use when building or
  reviewing UI animation — entrance/stagger, hover/tap/drag gestures, scroll reveals,
  page/layout transitions, SVG draw, or orchestrated timelines — in React, Svelte, Vue,
  or plain HTML/JS. Covers anime.js, motion.dev (Motion), and the kokonut UI / blk UI
  animated component collections. Triggers: "animate", "motion", "transition", "micro-interaction",
  "anime.js", "motion.dev", "framer motion", "kokonut", "blk ui", "scroll animation", "stagger".
---

# Web Motion

Build motion that reads as **premium, intentional, and fast** — never decorative jank.
This skill is framework-agnostic: the *principles* are constant; only the *binding* changes
between React, Svelte, Vue, and vanilla HTML/JS.

## Golden rules (apply to every animation, every framework)

1. **Animate only `transform` and `opacity`** for anything that moves. They run on the GPU
   compositor and hit 60fps. Avoid animating `width/height/top/left/margin` — they trigger
   layout and stutter. Use `transform: scale/translate` and `filter` instead.
2. **Always honor `prefers-reduced-motion`.** Provide a reduced or no-motion path. This is an
   accessibility requirement, not a nicety. See `references/principles.md`.
3. **Motion has meaning.** Entrances guide the eye, transitions preserve context, feedback
   confirms action. If an animation doesn't do one of those, cut it.
4. **Short and eased.** UI motion is ~150–400ms with a natural easing (ease-out for entrances,
   spring for interactive). Long/linear motion feels cheap.
5. **Stagger to show relationships**, not to stall. 30–80ms between items.

## Step 1 — Pick the right tool

Use `references/libraries.md` for the full matrix. Quick guide:

| Need | Reach for |
| --- | --- |
| Declarative React animation, gestures, layout/shared-element, exit animations, scroll | **motion.dev** (`motion/react`) |
| Framework-agnostic JS animation (Svelte/Vue/vanilla), timelines, SVG draw/morph, along-path | **anime.js**, or motion.dev's vanilla `animate()` |
| Prebuilt, copy-paste animated components (heroes, cards, marquees, text effects) | **kokonut UI** / **blk UI** (React + Tailwind + Motion) |
| CSS-only entrance/hover with zero JS | Native CSS transitions/keyframes (see principles) |

**Rule of thumb:** in React, default to **motion.dev** for behavior and pull ready-made pieces
from **kokonut/blk UI**; drop to **anime.js** for timeline-heavy or SVG work. Outside React,
use **anime.js** or motion.dev's vanilla `animate()`.

## Step 2 — Implement with a framework recipe

Open the recipe for the target stack and adapt — do not invent APIs:

- React → `references/recipes-react.md` (motion.dev + kokonut/blk UI)
- Svelte → `references/recipes-svelte.md` (built-in transitions + anime.js / motion `animate()`)
- Vanilla HTML/JS → `references/recipes-vanilla.md` (anime.js + motion `animate()`)
- Principles, performance, a11y, easing tokens → `references/principles.md`
- Library selection deep-dive & install → `references/libraries.md`

## Step 3 — Verify before shipping

- [ ] Only `transform`/`opacity`/`filter` are animated on moving elements.
- [ ] A `prefers-reduced-motion: reduce` path exists and is tested.
- [ ] No animation blocks interaction or delays content > ~400ms.
- [ ] Durations/easings come from a shared token set, not magic numbers scattered around.
- [ ] Scroll/`whileInView` animations run once (don't re-fire on every scroll) unless intended.
- [ ] Exit animations use the framework's presence API (`AnimatePresence`, Svelte `out:`), not
      manual timeouts that race unmount.

## Reproducibility

The same interaction (e.g. "staggered card grid that reveals on scroll") is implemented in all
three recipe files with identical timing tokens, so behavior is consistent when a team ports a
design across stacks. Copy the timing tokens from `references/principles.md` into your design
system and reference them everywhere.