Quick start
Use the kit from the repository today: write a scene, check it with the CLI, compile it and draw it in a page.
Reelify Motion Kit is not on a package registry yet. Today it is used from the Reelify repository, where it lives in the motion-kit/ folder. You import from motion-kit/src and run the CLI with tsx.
What is in the folder#
| Path | What it is |
|---|---|
motion-kit/src/index.ts | The library. Everything on this site is exported from here. |
motion-kit/cli.ts | The CLI: catalog, check, patch, dress, example, snapshot, apply, guide. |
motion-kit/examples/films.ts | Example films written against tokens, and three product records. |
motion-kit/kit/ | The agent kit: an index, task files, reference files and registry items to copy. See Agents. |
Write a scene#
Save this as hello.json. A scene needs duration and root. size defaults to [1080, 1920] and background defaults to "ground".
What each part does:
- The root
boxis the frame. It fills it and centres its children.gapis the space between them in pixels. "split": "word"breaks the text into pieces.staggerstarts each piece 0.14 seconds after the one before and gives every piece the sameenter."from"is a pose: a name ("rise","fade") or an object of channels ({ "scaleX": 0 })."at"is a time in seconds or the name of a cue. Left out, a behavior starts when its node does."accent"and"muted"are palette names."body"is a font role. The values come from the scene's kit fields or from a design system.
Check it#
Run the CLI from the motion-kit directory:
npx tsx cli.ts check hello.json{
"problems": [],
"notes": [],
"size": [1280, 720],
"duration": 4,
"nodes": 6,
"cues": {}
}nodes counts what the scene expanded to: the root, three children, and the two words of the split headline. The command exits with code 1 when problems is not empty.
Reading problems and notes#
A problem must be fixed. A note will play, and is probably not what was meant. This node list has four mistakes and one late entrance:
{ "el": "box", "gap": 28, "align": "middle", "children": [
{ "el": "text", "text": "Hello, motion", "size": 128, "colour": "accent",
"motion": [{ "do": "enter", "from": "rize" }] },
{ "el": "StatReveal", "label": "no value" },
{ "el": "text", "text": "late", "size": 40, "motion": [{ "do": "enter", "at": 6 }] }
] }In a four second scene, check reports these messages (shown here one per entry, with long lines wrapped):
problems
root (box)[1] (StatReveal): "value" is required
box #b1.align: "middle" is not one of start, center, end, stretch
text #t2: no option "colour" (it takes id, motion, start, place, at, w, h, grow, rotate, scale,
opacity, aperture, glow, local, backface, origin, text, size, weight, color, align, font, italic,
leading, tracking, maxW, upper, outline, outlineW, split, mark, markColor, markMotion, markStyle,
family, group)
text #t2 enter.from: no pose named "rize" (use fade, rise, drop, slide-left, slide-right, pop,
shrink, stamp, zoom-out, blur, wipe-up, wipe-down, wipe-right, wipe-left, flip, swing, spin, fly,
fly-past, fall, or an object like {y: 80, opacity: 0})
text #statReveal1.value count: "to" is required
notes
text #t4: "enter" starts at 6.00 s, after the scene ends (4 s)Each message starts with the place: an element and its id (text #t2), or a path from the root. Nodes without an id get one from their element's first letter and a counter. Each message ends with the options that exist. Fix, run again, and stop when problems is empty.
value on StatReveal also leaves the count behavior inside it without a target. Fix the first message of a pair and the second goes with it.Compile and draw it#
starter() returns a registry with the five elements, every behavior and the 89 components. compile takes the scene and the registry. mount builds the DOM once. seek(t) writes every node's pose for that second.
import { compile, mount, starter, type Spec } from "./motion-kit/src/index";
import scene from "./hello.json";
const registry = starter();
const compiled = compile(scene as Spec, registry);
if (compiled.problems.length) throw new Error(compiled.problems.join("\n"));
const host = document.querySelector<HTMLElement>("#stage")!;
const fonts = { display: "Geist, sans-serif", body: "Geist, sans-serif", mono: "Geist Mono, monospace" };
const mounted = mount(host, compiled, fonts);
const began = performance.now();
const tick = (now: number) => {
mounted.seek(((now - began) / 1000) % compiled.duration);
requestAnimationFrame(tick);
};
requestAnimationFrame(tick);mountgives the host the scene's aspect ratio and scales the frame to the host's width. Give the host a width.fontsis the CSS family behind each font role. A scene's or a config's ownfontsoverride it.- The fourth argument maps the paths a scene uses to URLs:
mount(host, compiled, fonts, { "assets/interview.webp": "/media/interview.webp" }). A path with no entry is used as written. seekcan be called with any second in any order. Nothing is stepped, so a frame can be asked for on its own.mounted.destroy()empties the host.
Without a browser#
compile does not need a DOM. compiled.frame(t) returns a map from node id to its pose, visibility and text at that second. trace(compiled) returns the scene's timeline as text: one line per behavior with its start and end. Both run in Node.
import { compile, starter, trace } from "./motion-kit/src/index";
const compiled = compile(scene, starter());
console.log(trace(compiled));
console.log(compiled.frame(1.2).get("t2")?.pose);With a browser#
A mounted scene can be measured. mounted.inspect(t) returns each node's rectangle, text and visibility at a second. mounted.lint() samples the scene and reports text that sits partly outside the frame, text on top of other text, text too small for a phone, and text that is on screen too briefly to read.
The other CLI commands#
npx tsx cli.ts catalog # every component: name, category, description
npx tsx cli.ts catalog StatReveal # one component: props, tree, parts
npx tsx cli.ts example keynote > film.json # an example film (command, keynote, walkthrough, code)
npx tsx cli.ts dress film.json graphite # the film under a design system
npx tsx cli.ts patch film.json ops.json # apply edit operations, all or none
npx tsx cli.ts snapshot hello.json # what is in a scene and what can be done to each thing
npx tsx cli.ts guide # the full written guide, generated from the registryEvery command reads JSON files and prints JSON to standard output. - in place of a file reads standard input.
Next#
- Scenes: the record, the elements, layout and time.
- Films: scenes in sequence, tokens and design systems.
- Components: the catalog, with every prop.
- Scene playground: paste a scene and play it.