Communitygithub.com

remotion-motion-design

Designs and implements compositions, timelines, scene systems, 2D/3D animation, typography, transitions, and reusable components with Remotion.

What is remotion-motion-design?

remotion-motion-design is a Claude Code agent skill that designs and implements compositions, timelines, scene systems, 2D/3D animation, typography, transitions, and reusable components with Remotion.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/achmdfzn/motionforge-atelier/tree/main/.claude/skills/remotion-motion-design

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

REMOTION MOTION DESIGN — Implementation Skill

1. Review before coding

  • Read CLAUDE.md, MASTER_PROMPT.md, and the architecture docs.
  • Check the actual Remotion/React/TypeScript versions and package manager.
  • Find the existing entry point and composition registry.
  • Follow the repository's conventions; do not swap dependencies without need.
  • Use the output of beyond-video, the script, storyboard, and Style Bible as the production spec.
  • Verify the APIs you use against the Remotion source of the installed version (e.g. packages/core/src in a reference clone) before relying on memory.

2. Composition profile

Defaults:

  • width: 1080
  • height: 1920
  • fps: 60
  • aspect: 9:16
  • duration: positive integer in frames

Every composition needs a unique ID and explicit metadata. Do not store different FPS values in several layers without a reason.

<Composition> accepts id, fps, width, height, durationInFrames, defaultProps, and optionally calculateMetadata (dynamic duration/metadata from props) and schema. durationInFrames must be positive.

3. Timeline engineering

  • Keep durations and start frames in centralized data/config.
  • Use one frame-interval convention; [start, end) is recommended.
  • Scene durationInFrames must be positive.
  • Make sure the composition's total duration holds every scene plus the tail/closing.
  • Validate overlaps and gaps; overlap only when it is intended for a transition/compositing.
  • Do not rely on floating point for the final frame boundary.

4. Deterministic animation — time/frame APIs (Remotion 4.x)

Time sources:

  • useCurrentFrame() — the current frame, 0-indexed. Only usable inside a composition component; outside a composition it throws.
  • useVideoConfig() — returns {width, height, fps, durationInFrames, id, defaultProps, defaultVideoImageFormat, ...}; throws outside a composition.

Interpolation and spring:

  • interpolate(input, inputRange, outputRange, options?) — overloads for number, string, boolean, and array output. Options: easing, extrapolateLeft / extrapolateRight ('extend' | 'identity' | 'clamp' | 'wrap'), output, outputType, posterize. Clamp extrapolation when motion must not run past the range.
  • spring({frame, fps, config?, from=0, to=1, durationInFrames?, durationRestThreshold?, delay=0, reverse=false}). SpringConfig: damping (default 10), mass (1), stiffness (100), overshootClamping (false). damping <= 0 makes the animation never settle (infinite-loop error).
  • measureSpring({fps, config?, threshold=0.005}) — number of frames until the spring settles; threshold=0 yields Infinity.

Rules:

  • Motion must be a function of frame and props.
  • Seed particle/noise/random values.
  • Avoid setInterval, setTimeout, requestAnimationFrame, Date.now(), and self-running CSS keyframes as the main source of video motion.
  • Do not fetch network data while the composition renders.
  • Do not include audio/video from unstable URLs or URLs that require login.
  • delayRender(label?, options?) holds the render until continueRender(handle) is called (e.g. async assets); its timeout is set with the CLI --timeout.

5. Sequence, Series, and local vs global frames

This is the rule most often gotten wrong — a real bug once happened because a component computed the global frame inside a Series.Sequence:

  • Inside a <Sequence>, useCurrentFrame() returns the frame RELATIVE to the start of the Sequence: (frame - (cumulatedFrom + relativeFrom)) * playbackRate. Components inside a Sequence do NOT see the global frame.
  • <Sequence> props: from?, name?, durationInFrames? (must be positive; required when using loop), layout ('absolute-fill' | 'none'), premountFor, loop, and crop props (only with layout="absolute-fill").
  • <Series.Sequence> may ONLY be used inside <Series>; a Series.Sequence outside <Series> throws "This component must be inside a <Series /> component."
  • Two valid routing patterns — pick one and stay consistent:
    • Global frame router (used in the video project): one router component uses the global useCurrentFrame() and picks the beat by its [start, end) range; beat components compute from the global frame.
    • Series: each Series.Sequence holds one beat; beat components compute from the local frame (0 at the start of the Sequence).
  • Do not mix both patterns in one composition without an explicit reason.

6. Scene/component structure

  • One scene has one narrative/visual responsibility.
  • Scene props are defined in TypeScript.
  • Reusable components solve a clear visual task.
  • Avoid a single file holding the whole video.
  • Separate content config, renderer, style tokens, and asset references.
  • Add designed fallbacks for optional assets; never hide a missing critical asset.

7. Media components and assets

  • <Img src> — an image that fails to load without onError cancels the render (cancelRender). Always provide onError for critical assets, or make sure the asset exists before rendering.
  • staticFile(path) — maps a file in public/; use it for every local asset (images, audio, video).
  • <Audio> — see sound-design for mapping a cue sheet to props (trimBefore/After — older alias startFrom/endAt — volume, playbackRate). A cue's position on the timeline is set by <Sequence from>; the trim props only cut which part of the file plays. <Audio> has no muted prop; mute is a CLI flag (--muted).
  • <Video> / <OffthreadVideo> and <Still> follow the same frame rules; media duration must be scheduled from frames, not from file metadata.

8. 2D motion

Use SVG/shapes/CSS/rasters as needed. Mind anchors, transform origins, anti-aliasing, layering, clipping, and the safe area. Every transform must be frame-driven.

9. Pixel and stickman support

Pixel art:

  • lock the logical canvas and pixel scale;
  • use nearest-neighbor when scaling sprites;
  • snap positions to the grid when needed;
  • lock the palette and sprite dimensions;
  • avoid blur and subpixel shimmer.

Stickman:

  • keep proportions and pivots consistent;
  • use a pose/rig library when the project's scale justifies it;
  • animate silhouette and gesture so they read;
  • sync expressions/poses with story beats.

For walk cycles, follow-through, and idle motion, see character-animation.

10. 3D motion

  • Add 3D only when it brings creative value.
  • Check the versions of three, @react-three/fiber, @remotion/three, and their docs.
  • For Remotion ThreeCanvas integration, follow the frame-driven approach of the installed API version; do not assume real-time R3F patterns are automatically deterministic.
  • Drive camera, transforms, materials, lighting, and particles from the frame.
  • Consider renderer/headless compatibility, texture size, geometry, and compute cost.
  • Separate the 3D layer from 2D typography/overlays when it helps readability and maintainability.
  • For directing 3D scenes in detail, see 3d-scene-director.

11. Typography and transitions

  • Prioritize hierarchy and readability.
  • Never cover important copy with a transition.
  • Every transition connects two beats; do not add effects without a function.
  • Keep motion curves and intensity consistent through the Style Bible.
  • Match text duration to reading needs.

12. Closing implementation

Implement the closing logo + CTA according to the beyond-video worksheet. The logo must come from an official asset or an approved placeholder. Copy, timing, motif, and compositing must feel made for the video at hand.

13. QA before handoff

Check composition ID, metadata, frame ranges, imports, types, static assets, fonts, style consistency, safe area, closing, and asset licenses. Run the available lint/typecheck/tests. Do not render MP4. Do not commit/push.

Output format

  • Composition registry: ID, 1080×1920, 60 FPS, durationInFrames, scene list + frame ranges.
  • APIs used: API name + relevant signature + where it was verified (installed Remotion version).
  • Frame routing pattern: global or Series — one choice, consistent across the composition.
  • Asset register: file, staticFile, fallback/onError per critical asset.
  • QA checklist + typecheck/lint results.

Mini example

Global frame router (video project pattern):

const frame = useCurrentFrame();
const beat = BEATS.find((b) => frame >= b.start && frame < b.end);
return (
  <AbsoluteFill>
    {beat?.id === 'S01-B01' && <Hook />}
    {beat?.id === 'S01-B02' && <Problem />}
  </AbsoluteFill>
);

Spring with a measured duration:

const settle = measureSpring({fps, config: {damping: 12}});
const progress = spring({frame, fps, config: {damping: 12}});

Failure modes

  • A component inside Series.Sequence computes the global frame → wrong beat, scenes show at the wrong time. Fix: compute from the local frame, or switch to a global frame router.
  • Series.Sequence used without <Series> → throws at render. Wrap it in <Series>, or use <Sequence> directly (not Series.Sequence).
  • spring with damping <= 0 → the animation never settles. Keep damping > 0.
  • Missing image without onError → the render is cancelled. Add onError or make sure the asset exists before rendering.
  • useCurrentFrame()/useVideoConfig() outside a composition → throws. Call them only inside composition components.

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

Related Skills