Motion workspace
This workspace renders repeatable motion graphics with Remotion through the mg CLI (pnpm mg <command>). Designs are code in templates; every job-specific value lives in JSON. A text, color or font change is a JSON edit plus pnpm mg render, never a code change.
Layout
mg.json workspace video defaults (fps, size)
brand/house.tokens.json house tokens: base colors, fonts, easing, durations, safe areas
brand/fonts/ brand/logos/ files the house tokens reference
clients/<client>/
client.json display name, optional video override
brand/tokens.json client overrides (deep-merged over house)
brand/fonts/ brand/logos/
brand/variants/<variant>/ named alternative look reused by several projects: tokens.json, fonts/, logos/
templates/<name>/index.tsx client-only templates, id "<client>/<name>"
projects/<project>/
project.json { title?, extends?: "client"|"none", brand?: "<variant>", video?, preset? }
tokens.json project-only overrides (optional)
tokens.lock.json present when frozen: renders ignore the live chain
fonts/ logos/ assets/ project files; props reference assets as "asset:<path>"
shots/<shot>.props.json { template, props, durationSeconds?, preset?, video? }
renders/ output, git-ignored; manifest.json tracks versions
Toolkit code (engine, house templates, these skills) lives in node_modules/motion-toolkit, pinned by package.json. Never edit it there; house template changes go to the toolkit repository.
House templates
Every house template has a look prop: minimal (clean, light weights, blur-rise, no panels), bold (heavy uppercase type, solid color blocks, spring pop), corporate (panels, accent bars, mask reveals). The default "brand" uses the look token, so a client sets its style once in brand/tokens.json ("look": "minimal").
| Id | Use |
|---|---|
lower-third | Name and title strap, optional logo |
title-card | Chapter or section title, optional kicker and subtitle; overlay or full-frame |
callout | Line from a point in the footage (x, y as frame fractions) to a label |
end-card | Closing card: logo, headline, CTA, URL, 0–2 YouTube end-screen slots |
kinetic-text | Quote or statement revealed word by word; *word* emphasizes |
logo-sting | Short animated logo reveal (intro/outro) |
counter | Number counting up (value, prefix, suffix, decimals) with a label |
social-handle | Platform icon plus @handle in a corner (YouTube, Instagram, TikTok, X, LinkedIn, …) |
typewriter | Text typed key by key with typewriter or keyboard sounds in the render's audio |
corner-branding | Persistent logo bug in any corner, optional tag such as LIVE |
pnpm mg new-shot … --template <id> writes every prop with its default. Each prop's meaning is in its .describe() text in node_modules/motion-toolkit/templates/<id>/index.tsx.
Token chain
toolkit → house → client → variant (if project.json "brand") → project tokens.json → shot props. The toolkit layer only supplies defaults (the look, a mono font, typing sounds). Objects merge key by key, null deletes an inherited key, and the most specific layer wins. "extends": "none" skips client and variant. Font, logo and sound files are found in the most specific layer's fonts/, logos/ or sounds/ folder that has them.
Rules
- Every visible value comes from shot props or tokens. No hard-coded colors, fonts, sizes in px without a prop, or timings in templates.
- Projects hold data, not code. A new design is a template; a new job is a project with shot files.
- Put a value at the lowest layer that owns it: one shot → shot props; one project → project
tokens.json; several projects of a client → a variant; the whole client → client tokens. - Never edit
tokens.lock.jsonby hand. Delivered projects are frozen; they change only throughmg rebrand(seemotion-render). - After every JSON or template edit, run
pnpm mg checkand fix what it reports before rendering. - Finish every visual change with the
motion-qaprocedure before reporting it done. - Ask the user before
mg rebrand --applyand before editing client or variant tokens used by frozen projects. - If a render or doctor check fails, run
pnpm mg doctorbefore changing code.
Route
| Task | Read |
|---|---|
| New client, variant, logo, font, color palette | motion-brand |
| New project or shots from a brief; change text/colors on existing shots | motion-project |
| New template or a change to how a template animates | motion-template, then motion-style |
| Motion feel: easing, timing, stagger, safe areas | motion-style |
| Rendering, presets, versions, delivering, applying brand changes | motion-render |
| Checking output before handing it over | motion-qa |
Commands
pnpm mg templates list template ids
pnpm mg new-client|new-variant|new-project …
pnpm mg new-shot <client>/<project> <shot> --template <id> shot file with all props at defaults
pnpm mg new-template <client> <name> starter template
pnpm mg check [<client> | <client>/<project>] validate everything without rendering
pnpm mg render <client>/<project> [shot…] skips unchanged shots; --force, --preset
pnpm mg still <client>/<project> [shot…] review PNGs on a checkerboard (all shots by default)
pnpm mg studio <client>/<project> live preview; Studio "Save" writes the shot file
pnpm mg deliver <client>/<project> render, verify, freeze, copy finals to deliver/<date>/
pnpm mg rebrand <client | client/project> [--apply] brand changes for delivered work
pnpm mg freeze|unfreeze|diff <client>/<project>
pnpm mg doctor environment, mg check, smoke render