Templates
A template is a reusable design. It reads shot props and resolved tokens and nothing else. Read motion-style before choosing timings or easing. For Remotion API details, use the Remotion skills if installed (npx remotion skills add) or https://www.remotion.dev/docs.
Where it goes
- Client-specific: start with
pnpm mg new-template <client> <name>. It writes a working starter atclients/<client>/templates/<name>/index.tsx(id<client>/<name>) that follows the contract below; replace its design. - House (all clients):
templates/<name>/index.tsxin the motion-toolkit repository, registered intemplates/index.ts, released with a new toolkit version. Do not write intonode_modules.
Before writing animation code, propose the schema (the props the user will be able to change without an agent) and confirm it with the user.
Contract
import { interpolate, useCurrentFrame } from "remotion";
import { z } from "zod";
import { color, defineTemplate, font, motion, px, safeArea } from "motion-toolkit/engine";
const schema = z.object({
headline: z.string().min(1).default("Headline"),
holdSeconds: z.number().positive().default(3),
accent: z.string().default("accent").describe("Color token name or #hex"),
});
export const template = defineTemplate({
title: "Title card",
schema,
durationSeconds: ({ props, tokens }) => {
const m = motion(tokens, 1);
return m.seconds("enter") + props.holdSeconds + m.seconds("exit");
},
check: ({ props, tokens }) => {
color(tokens, props.accent); // throws on unknown token names; runs in `mg check`
},
component: ({ props, tokens, video }) => {
const frame = useCurrentFrame();
const m = motion(tokens, video.fps);
// ...
},
});
Requirements:
- Export
template(client templates) built withdefineTemplate. - Every schema field has a
.default()so new shots and Studio start valid. Add.describe()for the Studio form. - Colors through
color(tokens, nameOrHex), fonts throughfont(tokens, role), durations and easing throughmotion(tokens, fps), positions insidesafeArea(tokens, video), sizes throughpx(sizeAt1080, video). - Animate only from
useCurrentFrame()withinterpolate/spring. No CSS transitions,setTimeout,Date.now()orMath.random()(userandom(seed)from remotion). Renders must be identical every time. - Leave the background transparent unless the template is full-frame; lower thirds and overlays render with alpha. Every element must be gone on the last frame.
- Fail loudly: throw an
Errorwith a fix hint when text cannot fit or a token is missing. UseassertFits/wrapLinesfrom the engine; they measure with the loaded font and throw on overflow. - Props that name tokens (colors, logos, fonts, sounds) are validated in
checkwithcheckRefs, somg checkcatches typos before rendering. durationSecondsandcheckrun in Node (mg check) and before fonts load: never measure text there.- Images and logos:
<Img src={staticFile(tokens.logos[name])} />orstaticFile(props.someAsset). Sounds:<Html5Audio src={staticFile(file)} />inside a<Sequence from={frame}>, files fromtokens.sounds[name]. The CLI stages the files.
Looks
House templates, and client templates meant to match them, take look: lookSchema and resolve it with resolveLook(props.look, tokens). Build them from the shared helpers so all three looks stay consistent (see motion-style):
choreo(tokens, look, fps)givesbeat(frame, index, exitStart, steps)→{ inP, outP }for each element in entry order;choreoSeconds(...)gives the matching duration.reveal(look, beat, video)is the look's entrance style for an element (wrap it inoverflow: hiddenforcorporate).typo(tokens, look, "display" | "title" | "body" | "label", size)is the look's type style;onColor(hex)picks readable text on a color block;cornerPlacement(corner, inset)positions corner graphics.
Read a house template such as node_modules/motion-toolkit/templates/title-card/index.tsx as a worked example.
Verify
pnpm mg new-shot <client>/<project> <shot> --template <client>/<name>in a test project, plus a second shot with the longest realistic text.pnpm mg check <client>/<project>.pnpm mg still <client>/<project> <shot>and look at the frames. Thenpnpm mg render.- Follow
motion-qa.
Working from a reference clip
When the user supplies a reference video, extract frames before designing. Create renders/reference/ first; the bundled ffmpeg is a minimal build without filters, so use -r for the frame rate:
pnpm mg ffmpeg -i reference.mp4 -r 10 renders/reference/f_%03d.png
Describe from the frames what moves, in which order, how long each phase takes (count frames at 10 fps), and the easing feel. Confirm that breakdown with the user, then map it to tokens: durations to motion.durations, curves to motion.easings.