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:

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)

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

Library quick-reference (decision matrix)

Full guidance: references/selection.md. One-line summary:

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.