# Motion

> Web animation + short-video knowledge for design-builder. Two modes: (1) UI motion in production web apps — GSAP / WAAPI / CSS / Anime.js / Lottie / Three.js library patterns, easing, stagger, performance, prefers-reduced-motion, motion anti-slop; (2) short video generation via HyperFrames (HTML compositions, CLI, scene transitions, captions). Activated by /build, /improve, /design_page, /design_screen when motion is part of the spec — and standalone when the user asks for animation help or a video. Sister skill to `design`; lives under skills/motion/.

- Skill: `app-builders-club/motion` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add app-builders-club/motion`
- Raw SKILL.md: https://api.skillmd.com/api/skills/app-builders-club/motion/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: app-builders-club (https://skillmd.com/u/app-builders-club)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/app-builders-club/motion

---


# Motion Knowledge Base — for design-builder

You are the motion knowledge layer of `design-builder`. The sister `design` skill owns the three-layer architecture (Layer 1 facts → Layer 2 filters → emit). This skill plugs into both:

- **Layer 1 (`KB-EXTENSION`)** — library-level animation knowledge that the `animations` MCP type alone does not cover (easing curves, registration patterns, performance, accessibility).
- **Layer 2 (Anti-Patterns)** — motion-specific anti-slop rules listed in [`references/anti-patterns.md`](references/anti-patterns.md).

You activate when:

1. A spec generated by `/design_page` or `/design_screen` lists motion in its `animation:` block, and `/build` is now emitting code.
2. `/improve` is asked to add or fix motion on user code.
3. The user explicitly asks for animation help on their web app.
4. The user asks for a short video — switch to **video mode** (HyperFrames pipeline).

If motion is not part of the request, do nothing. **Don't volunteer animation suggestions from this skill** unless the spec calls for them — gratuitous motion is the #1 way design-builder produces AI slop.

---

## Mode router (read first)

| Signal | Mode | Primary refs |
|---|---|---|
| Production web app, React/Next/Svelte/etc., motion is incidental to the UI | **web-ui** | [`references/selection.md`](references/selection.md) → pick library → corresponding [`references/web-animations/*.md`](references/web-animations/) |
| User asked for a short video, intro/outro, social ad, product promo, hero loop rendered to MP4/WebM | **video** | [`references/video/hyperframes.md`](references/video/hyperframes.md) + [`references/video/hyperframes-cli.md`](references/video/hyperframes-cli.md) |
| Lottie file already exists or the user mentions After Effects / Bodymovin export | either mode | [`references/web-animations/lottie.md`](references/web-animations/lottie.md) |
| 3D / WebGL hero, product spin, shader plate | **web-ui** (if interactive) or **video** (if pre-rendered) | [`references/web-animations/three.md`](references/web-animations/three.md) |

If the request is ambiguous ("can you make the landing more dynamic?"), default to **web-ui** mode. Switch only when the user explicitly says "render", "video", "MP4", or names a length in seconds with a delivery target (Instagram, Twitter, YouTube short).

---

## Web-UI mode — the contract

You are writing motion that ships in a real web app. That means:

1. **Honor `prefers-reduced-motion: reduce`** — every motion path must collapse to a non-motion variant. For GSAP use `gsap.matchMedia()`; for CSS use `@media (prefers-reduced-motion: reduce)`; for WAAPI gate `element.animate()` behind a JS check.
2. **Stay on the compositor** — animate `transform` and `opacity` only. `width`, `height`, `top`, `left`, `margin` cause layout thrash. The library refs all repeat this rule; enforce it.
3. **Finite duration, finite repeats** — even for "ambient" loops, prefer a finite repeat count tuned to a known cycle length, with a clean exit. Infinite animations break tab-switch heuristics, drain battery on mobile, and hide animation bugs.
4. **No render-blocking JS** — initialize animations after the relevant DOM exists, but don't gate first paint on an animation library load. Lazy-import GSAP/Anime.js for non-above-the-fold motion.
5. **Pick one library per concern** — don't mix GSAP and Anime.js in the same file. Don't drive a CSS keyframe with WAAPI's `animate()`. The selection table in [`references/selection.md`](references/selection.md) is the decision tree.

## Video mode — the contract

You are emitting an HTML composition that HyperFrames will seek and screenshot frame-by-frame, then encode to MP4/WebM with FFmpeg. That means:

1. **Deterministic** — no `Math.random()`, `Date.now()`, `performance.now()`, `requestAnimationFrame` as source of truth. Use seeded PRNGs (mulberry32) when randomness is needed.
2. **Synchronous setup** — build timelines and register them on `window.__timelines[<composition-id>]` synchronously after page load. No `async`, no `setTimeout`, no Promises.
3. **Finite everything** — no `repeat: -1`, no infinite CSS `animation-iteration-count`. Compute repeats from the composition duration.
4. **Library adapters** — HyperFrames seeks GSAP via `window.__timelines`, Anime.js via `window.__hfAnime`, Lottie via `window.__hfLottie`, Three.js via the `hf-seek` event. Each library ref documents its registration contract.
5. **CLI workflow** — every video composition ends with `npx hyperframes lint && npx hyperframes inspect && npx hyperframes render`. Skip lint and you'll ship broken frames. See [`references/video/hyperframes-cli.md`](references/video/hyperframes-cli.md).

---

## Library quick-reference (decision matrix)

Full guidance: [`references/selection.md`](references/selection.md). One-line summary:

| Library | When to reach for it | Web-UI ref | Video ref |
|---|---|---|---|
| **CSS animations** | Decoration, shimmer, glow, single-element entrances. No JS dependency. | [`web-animations/css.md`](references/web-animations/css.md) | same |
| **WAAPI** | Native browser keyframes, no library, JS-driven timing without GSAP weight. | [`web-animations/waapi.md`](references/web-animations/waapi.md) | same |
| **GSAP** | Scene choreography, complex stagger, timeline sequencing, scroll-driven motion. The default for non-trivial UI motion. | [`web-animations/gsap.md`](references/web-animations/gsap.md) | required for video mode |
| **Anime.js** | Compact SVG/DOM flourishes when the user already uses it; otherwise prefer GSAP. | [`web-animations/anime.md`](references/web-animations/anime.md) | same |
| **Lottie** | After Effects exports, logo reveals, illustrative micro-anims authored by a designer. | [`web-animations/lottie.md`](references/web-animations/lottie.md) | same |
| **Three.js** | 3D, WebGL, shader plates, particles. Heavy — justify the bundle cost. | [`web-animations/three.md`](references/web-animations/three.md) | same |

---

## Anti-patterns (Layer 2 hook)

When `/improve` or `/review` runs, route motion concerns through [`references/anti-patterns.md`](references/anti-patterns.md). The list includes:

- Linear easing on UI motion (always reads as "AI default" — use `power2.out` / `cubic-bezier(0.2, 0, 0, 1)` etc.)
- Motion without a `prefers-reduced-motion` fallback
- Animating layout properties when transforms work
- Infinite loops without a defined cycle exit
- Parallax/scroll-driven motion that ignores reduced-motion or mobile
- Multiple competing animation libraries in the same component
- Entrance animations on every element on first paint (delay above-the-fold motion to after LCP)
- Decorative motion that interferes with reading (auto-rotating carousels < 8s, infinite text marquees)

---

## Integration with `/build`, `/improve`, `/design_page`, `/design_screen`

- `/design_page` and `/design_screen` may include an `animation:` block in the spec. If they do, this skill is the source for what library to recommend and the patterns the spec should reference.
- `/build` reads the spec and, when the `animation:` block exists, consults this skill to emit production-ready library code. **The skill does not emit code itself** — `/build` does, this skill informs.
- `/improve` consults the [`references/anti-patterns.md`](references/anti-patterns.md) checklist when motion is in scope of the improvement target.
- When the user asks for a video, this skill is the primary skill (not `design`). The video pipeline is self-contained under [`references/video/`](references/video/).

---

## References (loaded on demand)

### Web-UI mode

- [`references/selection.md`](references/selection.md) — pick the right library for a given motion job. Decision tree.
- [`references/web-animations/css.md`](references/web-animations/css.md) — CSS keyframes, `animation-fill-mode`, `prefers-reduced-motion`.
- [`references/web-animations/waapi.md`](references/web-animations/waapi.md) — `element.animate()`, KeyframeEffect, currentTime seeking.
- [`references/web-animations/gsap.md`](references/web-animations/gsap.md) — tweens, timelines, easing, stagger, `matchMedia`, performance.
- [`references/web-animations/anime.md`](references/web-animations/anime.md) — Anime.js v4 patterns.
- [`references/web-animations/lottie.md`](references/web-animations/lottie.md) — `lottie-web` and dotLottie players.
- [`references/web-animations/three.md`](references/web-animations/three.md) — Three.js scenes, GLTF + AnimationMixer.

### Video mode

- [`references/video/hyperframes.md`](references/video/hyperframes.md) — composition authoring contract: data-attributes, timeline registration, scene transitions, layout-before-animation rule.
- [`references/video/hyperframes-cli.md`](references/video/hyperframes-cli.md) — `npx hyperframes init / lint / inspect / preview / render / transcribe / tts`.
- [`references/video/tailwind-runtime.md`](references/video/tailwind-runtime.md) — Tailwind v4 browser runtime when `init --tailwind` is used.

### Cross-cutting

- [`references/anti-patterns.md`](references/anti-patterns.md) — motion anti-slop rules. Consumed by `/improve` and `/review`.

---

## Source attribution

The library and HyperFrames knowledge in `references/` is adapted from the open-source `heygen-com/hyperframes` skill set (vendored at `.agents/skills/`, lockfile `skills-lock.json`). Original skills are HyperFrames-contract-first; the references in this folder strip the seek/contract sections for web-UI mode and keep them for video mode. License attribution lives in `NOTICE.md`.