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.

You activate when:

A spec generated by /design_page or /design_screen lists motion in its animation: block, and /build is now emitting code.
/improve is asked to add or fix motion on user code.
The user explicitly asks for animation help on their web app.
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` → pick library → corresponding `references/web-animations/*.md`
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-cli.md`
Lottie file already exists or the user mentions After Effects / Bodymovin export	either mode	`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`

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:

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.
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.
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.
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.
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 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:

Deterministic — no Math.random(), Date.now(), performance.now(), requestAnimationFrame as source of truth. Use seeded PRNGs (mulberry32) when randomness is needed.
Synchronous setup — build timelines and register them on window.__timelines[<composition-id>] synchronously after page load. No async, no setTimeout, no Promises.
Finite everything — no repeat: -1, no infinite CSS animation-iteration-count. Compute repeats from the composition duration.
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.
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.

Library quick-reference (decision matrix)

Full guidance: 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`	same
WAAPI	Native browser keyframes, no library, JS-driven timing without GSAP weight.	`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`	required for video mode
Anime.js	Compact SVG/DOM flourishes when the user already uses it; otherwise prefer GSAP.	`web-animations/anime.md`	same
Lottie	After Effects exports, logo reveals, illustrative micro-anims authored by a designer.	`web-animations/lottie.md`	same
Three.js	3D, WebGL, shader plates, particles. Heavy — justify the bundle cost.	`web-animations/three.md`	same

Anti-patterns (Layer 2 hook)

When /improve or /review runs, route motion concerns through 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 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 (loaded on demand)

Web-UI mode

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

Video mode

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

Cross-cutting

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.