Good Practices

A short list of habits that keep a Wiggle composition clear and predictable. None of these are rules the tool enforces; they are what tends to work.

Think of the composition as a function of the frame

A composition is rebuilt as a pure function of the frame number. The script runs once to produce a document, and the engine draws any frame by sampling that document. So describe motion declaratively, with tweens, keyframe tracks, and springs, rather than mutating state between frames. This is what makes scrubbing instant: any frame is computed directly, never by replaying the ones before it.

Size with size, move with scale

Set how big something is with its size (or loadSVG(path, { size })). Use scale and scaleTo only for motion, since scale is a multiplier on the size, not a way to set it. Reaching for scaleTo(500) to make a 1px shape large works by accident and then surprises you the moment the shape already has a size. Size the shape, then animate scale around 1.

Let timing stay relative

Write durations as seconds ("0.5s" or a number) and place entrances relative to other elements with .after(ref, gap) and .with(ref). When you retime a layout, the relationships hold instead of every number needing an edit.

Concurrent or sequential, by property

Animations on different properties run at once; animations on the same property chain, each continuing from where the last ended. Give two tweens the same at to play them together, or different at times on one property to order them. A keyframe track expresses any combination when you need full control.

Reuse with components, drive with data

When a piece repeats (a lower-third, a chart bar, a row), write it once as a component and instantiate it in a loop over your data. The result changes when the data changes, and the Studio shows each instance as a named lane. Name the parts with node.name(...) so you can reach them with find. See Components.

Use effects sparingly

blur, backdropBlur, and composition motionBlur are effective in small amounts. Motion blur in particular costs several renders per frame, so leave its preview toggle off while scrubbing and turn it on to check a paused frame.

Colors are hex or rgb, and a typo is an error

A color is a hex string, rgb(...), or rgba(...). Named colors and hsl(...) are not accepted in a script, and an unrecognized color stops the build rather than drawing black, so a mistake is caught at once. Imported SVG colors are more forgiving and report problems in the Studio log.

Let it fail loudly

The Studio halts on a script error and shows it over the preview, rather than running the last good output. That is intentional: a contradiction (a property set by both a keyframe track and a tween) or a malformed value should stop you, not be guessed around. Fix the script and playback resumes from where it paused.

Keep the script the source of truth

The Studio previews, scrubs, and inspects, but the script is what defines the composition. Treat the file as the single source of truth and keep it readable, so the document and its result always come from one place.