Motion Direction

Motion Direction → the rules everything else obeys

Direction is the judgment layer above craft. It turns a brief into a short set of motion rules, so every shot reads as one hand. Most of the work is subtraction: deciding what does not move.

motion-principles gives the numbers. This decides which numbers the whole piece is allowed to use.

The one rule

Lock the motion language first, then animate to it. Pick one of each row below and reuse it. Consistency reads as confidence; variety reads as noise. When in doubt, repeat rather than invent.

The motion-language spec

Fill every row once, at the top of the job, and state it back to the user before you animate. The rows guide the timeline document; motion-graphics owns the tool calls.

Two easings maximum: one for entrances and landings, one for exits. A third has to justify itself.

Match depth to the brief

For a showcase, hero, launch, or "best" piece, plan each scene with a background bed, midground, foreground, and a grain or grade finish. Group each scene. Use path shapes, masks, repeaters, style tracks, animation links, and effects where they give the composition depth. Read the full document with get_timeline and use set_timeline_document for fields edit_timeline cannot write, including styleTracks and repeater.

Study a shipped reference before building. Call list_example_timelines to choose a slug, then get_example_timeline to read its stats, scene catalog and first scene excerpt. Use scene_id to choose another scene and clip_offset / clip_limit to page through its layers. The CodeAct forms are nodetool.timelines.examples.list() and nodetool.timelines.examples.get("kite", {clip_limit: 12}). No library install or repository filesystem is needed. Kite, Prism, Voltra and Tidewater show different ways to group scenes and combine keyframed layers. Cadence shows a vertical data story built from the chart helpers and a reusable component.

Build with the craft methods, not hand-keyframed fades. video({palette, fonts, ...}) from @nodetool-ai/sandbox-timeline gives every scene s.backdrop(), s.glow(), s.flash(), s.kicker(), s.pill(), s.streaks() and s.finish() — the vocabulary the shipped examples build scenes from. A slam, a rise or a grow is el.enter()/el.animate() with the right from/props (title.enter({from: {scale: 1.35, blur: 26, opacity: 0}}) is a slam), a count-up is el.count(), a draw-on is el.draw(). The depth plan below maps directly onto the API — reach for one of these before a bare animate() custom curve:

Plan every showcase scene across all four before writing the hero's animation. Read the pack documentation (nodetool.packs.docs("@nodetool-ai/sandbox-timeline")) for every method's signature. Budget for a generated still or music bed in a showcase unless the user sets a cost limit.

After saving a showcase, call validate_timeline with {"timeline_id":"<id>","tier":"showcase"}, or nodetool.timelines.validate(id, {tier: "showcase"}). Address its warnings about scene groups, custom keyframes, finish, camera and concurrent visual layers. These checks inspect document structure. Preview the result to judge composition and readability. Standard validation remains appropriate for ordinary edits and intentionally minimal pieces.

Typography

Choose the family and weights in the motion-language spec before building text clips. NodeTool ships Inter, Space Grotesk, Bebas Neue, Playfair Display, Lora, and JetBrains Mono. Use one family across a piece and make the hero visibly heavier than support, such as Inter 800 against 400. Bebas Neue ships only at 400, so use size and spacing for contrast if you choose it.

On a 1920×1080 frame, start a hero title at 96–160 fontSizePx, support at 42–64, and a short kicker at 28–36. Keep large display tracking tight (letterSpacingPx −2 to 1); open an uppercase kicker to 2–5px. Check the actual words at the target frame size and adjust for fit and legibility.

For an existing text clip, edit_timeline can set the type as a set_clip_params patch:

{"timeline_id":"<id>","ops":[{"op":"set_clip_params","target":"Hero title","textStyle":{"fontFamily":"Inter","fontWeight":800,"letterSpacingPx":-1,"fontSizePx":128}}]}

timeline-edit-ops owns the full op contract. frame-composition handles placement and safe areas for each aspect ratio.

Tone and energy

Place the piece on two axes and commit. Mixing cells inside one piece is the usual cause of "inconsistent".

Motion personality

The named preset that fills the spec's easing, timing and intensity rows. Pick one per project and hand it to every later step by name.

Premium sits calm-soft, Corporate calm-sharp, Playful kinetic-soft, Energetic kinetic-sharp. Default to Corporate for product and Playful for lifestyle. easeOutElastic and easeOutBounce belong to Playful alone.

Motion hierarchy

Rank every element, animate down the list, and stop early.

These are the three layers motion-principles names Primary, Secondary and Ambient. If two elements compete for the eye in one frame, the direction failed: demote one before touching its keyframes.

Hierarchy is also a track decision. Lowest track index renders on top, so the hero belongs on a low index and the bed on a high one; a scrim sits between the picture it darkens and the text it carries. For a camera move, set clip transform.depthPx separately from track order. The sequence's camera2d can keyframe position and depth while focusDepthPx and aperturePx decide which plane softens. Keep one plane legible while the others move.

Use layout (a flex container on a group clip, its real children via parentId) for elements whose spacing should survive a text or shape change: flexDirection: "row" | "column" with gap keeps siblings apart, and a plate sized from live text is a flexItem: {position: "absolute", inset: 0} sibling in a padded container. Use animationLinks when one clip should follow another's authored position, scale, rotation, or opacity. Linked followers share one motion decision; they do not chain through a second link.