Scenes
The scene record, the five elements and their props, how layout works, how time works, and how ids and parts are named.
A scene is one JSON object. compile(spec, registry) expands its components into elements, works out when everything starts, checks it, and returns frame(t). This page is the reference for the record.
The scene record#
| Field | Type | Meaning |
|---|---|---|
size | [width, height] | The frame in pixels. Default [1080, 1920]. |
duration | seconds | Required. |
background | colour | A palette name or a colour value. Default "ground". |
root | node | Required. The tree. |
cues | { name: seconds } | Named times. Behaviors and start point at them by name. Expressions read them as numbers. |
transcript | [{ w, start, end }] | Timed words. Word 0 supplies the cues word0In and word0Out, word 1 supplies word1In and word1Out, and so on. |
audio | path or URL | The matching sound, for a host that plays it. The kit does not play or mix it. |
signals | { name: definition } | Named values over time. See Expressions. |
speed | number | 2 makes every curve twice as quick. Times pinned with at do not move. |
The kit fields#
These fields give names their values. A scene can carry them itself, or a design system can supply them.
| Field | Meaning |
|---|---|
palette | Colour names to values: ink, paper, ground, accent, accent2, onAccent, muted, good, bad, night, white, black. |
fonts | The CSS family behind each font role: display, body, mono, serif. |
typefaces | Remaps one font role to another for the whole scene: { "display": "mono" }. |
tokens | Named numbers, words, lists and records. Read as "$name", inside "=expr", or as "{name}" in text. |
surfaces | Named box styles. A box with "surface": "card" takes that style. |
curves, poses | Named curves and poses. Redefining a built-in name changes it everywhere. |
defaults | Default props per component. "*" applies to every component that has the prop. |
components, behaviors | Components and behaviors defined for this scene. See Custom components and Behaviors. |
Nodes#
{ "el": "NAME", "id": "optional", "start": 0.5, "motion": [], "children": [] }el is an element, a component, or "Motion": a bare box that exists to carry behaviors around its children. Every other key is a prop. Every node takes these:
| Prop | Meaning |
|---|---|
id | A name other things can point at. |
start | When the node's clock starts. See Time, below. |
w, h | Pixels, or "fill". grow takes the free space in the parent. |
place | [x, y] as fractions of the parent (0 to 1). Puts the node's centre there, out of the flow. |
scale, rotate, opacity, origin | A fixed transform. origin is the point scale and rotation happen around: center, left, top left and so on. |
glow | A soft light of this colour around the node. |
aperture | A circular reveal, 0 closed to 1 open. |
local | true makes seconds written inside this node count from its own start. |
backface | false hides the node while it is turned away from the camera. |
The five elements#
| Element | What it is | Main props |
|---|---|---|
box | A container. | dir, gap, pad, align, justify, wrap, cols; surface, fill, radius, border, borderW, shadow, hard, frost, pattern; clip, perspective, space; spotX, spotY, spotR; rtl |
text | Words. | text (required), size (default 56), weight (default 700), color (default "ink"), font (a role, default "display"), align, maxW, leading, tracking, upper, italic, outline, outlineW; split (word, char, line), mark, markColor, markStyle, markMotion |
shape | A drawn shape. | kind: rect, circle, ring, check, arrow, line, path, spark; fill, stroke, strokeW, radius, progress (ring), d and vb (path), values (spark) |
icon | A line icon. | name (required): check, x, plus, arrow, heart, star, bolt, play, clock, user, chat, mic, sparkle, search, bell, scissors, music, send, cursor; size, color, strokeW, fill |
img | A picture, a sprite sheet or a video. | src, fit, radius, shadow, label, sheet, frame, clip. See Media. |
A colour is a palette name, a colour value, or "a>b" for a gradient in a fill. Prefer palette names: the scene then works under every design system. A misspelt prop is a problem, and the message lists the props the element takes.
Layout#
Layout is flow layout, like a column or a row in a design tool.
- The root box is the frame. It fills the frame and centres its children.
- Every other box is only as big as its content unless it has
wandh. "fill"needs a parent that has a size.h: "fill"under a parent with no height is reported as a note.diris"col"(default),"row"or"stack". In a stack, children sit on top of each other, centred. Later children draw on top.gapis the space between children in pixels.padis pixels, or[vertical, horizontal].alignis across the direction:start,center,end,stretch.justifyis along it:start,center,end,between.colslays children out as a grid that many columns wide.placetakes a node out of the flow and puts its centre at a fraction of its parent.
mounted.lint(), the overlap audit) need a mounted scene.Time#
Every node has a clock that begins at its start. Its behaviors and its children count from there.
| Written as | Meaning |
|---|---|
"start": 1.2 | Seconds. |
"start": "hit" | A cue: an entry in the scene's cues, or a word cue from transcript. |
"start": { "after": "first", "gap": 0.3 } | Once the node with that id has finished arriving, plus the gap. The other node must come earlier in the tree. Motion that never stops (loop, drive) does not count as arriving. |
no start | The parent's start, plus the node's slot in the parent's stagger if it has one. |
A behavior has its own at: seconds, a cue name, or "end" for the scene's last second. Left out, the behavior starts at its node's start. delay adds to that. at moves only that behavior. start moves the node and everything inside it, which is how a whole component is delayed.
- A node with
enterdoes not exist before it enters. A node withexitis gone after it leaves. - A node with no
enteris there from the first frame, whatever itsstart. duringshows a node and its children only inside a window:{ "do": "during", "at": 2.4, "until": 4.2 }."local": trueon a node makes numbers written inside it count from its own start. Sequence sets this on every scene, so a scene can be moved or retimed whole.- A behavior that starts after the scene ends is reported as a note.
Ids and parts#
An id names a node. Three things use it: { "after": "id" } in a start, a camera focus written "#id", and messages from the check. Two nodes with the same id are a problem.
A component instance takes the id you give it, or one made from its name and a counter (statReveal1). The nodes inside it are named instance.part, for example statReveal1.value.
The ids inside a component's tree are its parts. parts on an instance restyles them or adds motion to them. A part takes the props of the element it is, plus motion. root is the whole component.
{ "el": "StatReveal", "value": 82, "suffix": "%",
"parts": {
"value": { "color": "bad" },
"label": { "upper": true, "motion": [{ "do": "loop", "kind": "pulse" }] }
} }A part name the component does not have is a problem, and the message lists the parts it does have. npx tsx cli.ts catalog StatReveal prints a component's parts and what element each one is. The component pages list them too.