Films
Scenes in sequence with Sequence, the duration rule, writing a film against tokens, the product record, dressing a film in a design system, and the registry items to copy.
A film is a scene whose root holds a Sequence: a list of scenes, each with a length. There is no separate film format. Everything on the Scenes page applies.
A film written the way this page describes carries no colour, no typeface and no product copy. A design system supplies the look and a product record supplies the words, so one film serves any brand.
Sequence#
{ "el": "Sequence", "scenes": [
{ "len": 3, "node": { "el": "KineticLine", "text": "$claim" } },
{ "len": 3.4, "transition": "push", "node": { "el": "Checklist", "items": "$checks" } }
] }| Prop | Type | Meaning |
|---|---|---|
scenes | list, required | { "len": seconds, "node": NODE, "transition": name }. transition is optional and says how this scene arrives. |
transition | fade, zoom, push, rise, blur, cut | The default for scenes that do not name one. Default fade. zoom goes through a blur. push is sideways. |
mix | 0 to 2 seconds | How long a scene overlaps the next. Default 0.4. A cut has no overlap. |
What Sequence does with each scene:
- It starts the scene at the sum of the lengths before it.
- It wraps the scene's node in a full-frame stack, so the node is centred in the frame.
- It sets
localon that wrapper. Seconds written inside a scene count from that scene's start."at": 1.3inside the third scene means 1.3 seconds into the third scene. - It shows the scene only during its own length plus the overlap, and adds the transition's entrance and exit.
Local time is what makes a scene movable. Reordering two scenes, or changing a len, never requires touching the times inside any scene.
"w": "fill" or "h": "fill". The node is centred for you, and a full-size wrapper pins its content to the top. To put two things in one scene, wrap them in a plain box: { "el": "box", "gap": 40, "align": "center", "children": [a, b] }.The duration rule#
The scene's duration must equal the sum of every len. The compiler refuses a film whose scenes outrun it by more than half a second:
Sequence: its scenes add up to 9.6 s but the scene's "duration" is 8 s, so what comes after 8 s
is never shown (set "duration" to 9.6 or shorten a scene)When you add or remove a scene, or change a len, change duration in the same edit. A duration longer than the sum compiles, and leaves an empty frame after the last scene ends.
A film written against tokens#
This film has three scenes: a claim, a feature with a screen that proves it, and the closing card. Every word comes from tokens. Every colour, corner and spring comes from names.
panel slot.The root is a full-frame stack so that a background world can sit behind the whole film. Put one DotField before the Sequence in that stack. Do not put one in each scene.
Rules that keep a film copyable#
- Never write a colour value or a font name. Use palette names, surfaces and font roles. See Design systems.
- Never write product copy. Use tokens:
"$name","$tagline","$f1". Inside a sentence:"by {name}". Lists and rows are tokens too:"items": "$bento". - Use only the props a component lists. A prop that is not listed does not exist, and the check says so.
- One idea per scene, 2.5 to 5 seconds. A text card is 3 to 8 words. End on a Lockup of 3 to 4 seconds.
- In a 1920 wide frame a title is 84 to 190 pixels and nothing is under 34.
- Text and interface take turns: a claim, then the screen that proves it.
The product record#
A product record is a flat JSON object of the tokens a film reads. It is set as the film's tokens. Words are strings. The rows of a mock screen are lists and records.
{
"name": "harbor",
"tagline": "Get paid the day you ship",
"cta": "Open an account",
"f1": "Invoices", "f1s": "written from your contracts",
"stat": 2, "statUnit": " days", "statLabel": "from invoice to paid",
"checks": ["Invoice sent", "Reminder sent", "Paid", "Books closed"],
"chat": [
{ "text": "Who still owes us for March?" },
{ "text": "Three clients. I have reminded all three.", "me": true }
],
"cols": ["client", "amount", "status"],
"rows": [["Northwind", "4,200", "paid"], ["Lumen", "1,850", "late"]]
}A token is read in three ways:
| Written | Reads | Example |
|---|---|---|
"$name" | The whole value: a word, a number, a list, a record. | "messages": "$chat" |
"{name}" | A word inside a longer text. | "text": "1 · {s2}" |
"=expr" | A number in arithmetic. | "gap": "=gap*2" |
The three shipped products (reelify, harbor, fieldnote) use the same token names, so any shipped film plays with any of them. A full product record is about 2,400 characters. A token name cannot be t, lt, dur, selfW, selfH, parentW, parentH, or the name of a cue.
"$name" with no token is left as written, so the film shows the text $claim. A missing list token is caught, because the component receives a string where it expects a list. Compare a product record against the film's token list before you ship it.Dressing a film#
Dressing puts a design system under a film and a product's words into it. Neither touches the film's root.
import { SYSTEMS, compile, starter, withConfig, type Spec } from "./motion-kit/src/index";
const dress = (film: Spec, system: string, product: Record<string, unknown>): Spec =>
withConfig({ ...film, tokens: product }, SYSTEMS[system], { force: true });
const compiled = compile(dress(film, "neon", harbor), starter());From the CLI:
npx tsx cli.ts example keynote > film.json # an example film, with the reelify product as its tokens
npx tsx cli.ts dress film.json paper > out.json # the same film under the paper system
npx tsx cli.ts check out.jsondress takes one of reelify, graphite, paper, neon, candy. To change the product from the CLI, replace /tokens with a patch operation. See Editing.
Six films, five systems and three products give 90 combinations. All 90 compile with no problems. A film is 900 to 1,700 characters of JSON, a system about 1,100, a product record about 2,400.
accent must use onAccent) and check that longer words still fit. Fit is measured by mounted.lint() in a browser, not by the compile check.The example films#
| Film | Frame | Length | Scenes | What it is |
|---|---|---|---|---|
| The command film | 1920 × 1080 | 30.2 s | 7 | A shortcut, a command palette that types and picks, then three features in one layout with a screen that acts, a bento, and the name. |
| The keynote film | 1920 × 1080 | 28 s | 7 | No interface until the end: one claim in huge type, a wheel of what it does, one number, a bento that assembles, before and after, the second claim, the name. |
| The walkthrough (9:16) | 1080 × 1920 | 24.8 s | 6 | For a feed: the hook types, then three numbered steps down a phone frame (the cut, the conversation), a checklist, the name. |
| The command line film | 1920 × 1080 | 26.8 s | 6 | A command types, its log and a pipeline run side by side, a table of results with a moving selection, a count, a deck of three, the name. |
| Requests in, work out (written by a model) | 1920 × 1080 | 26.2 s | 7 | A 16:9 film of 24 to 28 seconds in the shape 'requests in, work out': (1) named message bubbles pile up asking for things, from $requests; (2) an 'Introducing {name}' line; (3) a status pill whose verb changes, from $verbs, beside or above the prompt being typed from $ask; (4) the work that came out: the timeline, from $lanes; (5) a second proof: the reply thread, from $chat; (6) a bento of what it does, from $bento; (7) the name, tagline and button. |
| Claim, then proof (written by a model) | 1920 × 1080 | 26 s | 8 | A 16:9 film of 24 to 28 seconds in the shape 'claim, then proof', where words and interface never share a frame and every change is a hard cut: (1) the claim $claim1 typed alone; (2) cut to the sound wave with its pauses closing; (3) a one-line claim about $f2 (use the tokens $f2 and $f2s); (4) cut to the timeline from $lanes; (5) a one-line claim about $f3; (6) cut to the conversation from $chat; (7) a title whose last word swaps through $audiences after the stem 'Made for'; (8) the name, tagline and button. |
Play them under any system and product in the films playground. Edit one scene by scene in the film playground.
Registry items#
motion-kit/kit/r/ holds films, systems and products as single JSON files meant to be copied whole. Each file wraps its record with a name and a type.
| File | Shape |
|---|---|
film-command.json, film-keynote.json, film-walkthrough.json, film-code.json | { "name", "type": "film", "title", "description", "system", "tokens": [names it reads], "film": SCENE } |
system-reelify.json, system-graphite.json, system-paper.json, system-neon.json, system-candy.json | { "name", "type": "system", "description", "system": CONFIG } |
product-reelify.json, product-harbor.json, product-fieldnote.json | { "name", "type": "product", "tokens": RECORD } |
A film item's tokens list is the contract: the names a product record must define for that film. Its system is the design system the film was first shown in, and any of the five can replace it.
To start a new film, copy the nearest film item, replace its scenes, and keep the token names. To add a brand, copy a system item and change its values. To add a product, copy a product item and rewrite the words.