Lottie Animator

Lottie is JSON, which makes it easy to write and easy to write wrongly. The failure mode is specific and nasty: a broken Lottie still parses. A missing os on a polystar, an easing handle one level too high, a layer without ip/op — the file loads, the player reports no error, and the canvas stays empty.

So do not judge an animation by whether the JSON is valid. Judge it by looking at it.

The loop

convert  →  lint  →  render  →  LOOK  →  revise

Never skip the render. "The JSON is valid" is not a claim about what the user sees.

python3 scripts/svg2lottie.py logo.svg -o build/logo.json --size 512
python3 scripts/lottie_lint.py build/logo.json --allow-static
node scripts/render.mjs build/logo.json
# then Read the filmstrip PNG it prints and actually look at it

render.mjs writes filmstrip.png: labelled frames across the timeline, each with a shape count and canvas coverage. Read that image. It reports EMPTY FRAME when nothing paints, off canvas when the art has left the frame, and clipped when it runs past an edge.

If the tools are unavailable (another repository, no Node), say so and fall back to python3 -c "import json; json.load(open('a.json'))" — but tell the user the result is unverified rather than implying it was checked.

Start from real geometry

Do not hand-write bezier vertices. svg2lottie.py converts SVG paths, rects, circles, ellipses, lines, polygons, polylines, groups, transforms, strokes, and linear/radial gradients into Lottie shape layers. Each element becomes its own named layer anchored at its own centre, so scale and rotation pivot correctly.

python3 scripts/svg2lottie.py icon.svg -o icon.json --size 512 --current-color "#a855f7"

Icon sets paint with currentColor; pass --current-color or the art comes out black. <text>, <use>, clipPath, and mask are reported as warnings — flatten them in the source SVG first. The output is deliberately static; you add the motion.

When there is no SVG, write the JSON directly — but lint and render it the same way.

Before keyframing, decide the motion

Answer these before touching a keyframe. It takes thirty seconds and prevents most revision cycles:

1. Feeling — what should the viewer feel? (trust, delight, urgency, calm)
2. Personality — pick exactly one: Playful, Premium, Corporate, or Energetic.

See [references/motion-personality.md](references/motion-personality.md).

1. Hero property — one of position, scale, rotation, opacity. One. The rest support it.
2. Timing — functional feedback under 150 ms; expressive motion 300–600 ms.
3. Easing — entrance eases out, exit eases in, loop eases in-out.
4. Staging — the hero enters 100–200 ms after its background.

Motion that competes with the subject is noise. Cut it.

Technique by intent

Structure, property names, and worked JSON: [lottie-structure.md](references/lottie-structure.md) · [svg-to-lottie.md](references/svg-to-lottie.md) · [bezier-easing.md](references/bezier-easing.md) · [examples.md](references/examples.md) · [lottie-tools-ecosystem.md](references/lottie-tools-ecosystem.md)

Easing

Handles belong inside a keyframe, never on the property that holds them. x must stay within 0–1; y may overshoot, and that overshoot is exactly what makes a bounce. Handles on keyframe n shape the segment from n to n+1 — putting them on the wrong keyframe eases the wrong half of the move.

The defects that render blank

Every one of these shipped in this repository at some point and passed a JSON-parse check. The linter now catches all of them; the tests pin them.

Every layer needs ip, op, and st. Miss any one and the layer is hidden at every frame.

Properties whose absence makes a player drop the layer — each verified by removing it from a working file and rendering the result:

fill c,o · stroke c,o,w · gradient fill s,e,g,o · polystar p,r,pt,or,os plus ir,is when sy is 1 · ellipse p,s · rect p,s,r · trim s,e,o · transform o, plus sa whenever sk is present.

The spec also lists a,p,s,r on a transform and t on a gradient. lottie-web supplies defaults for those, so the linter reports them as warnings (SH003) rather than errors — but other players are not guaranteed to be as forgiving.

Finishing

Before saying it is done:

• lottie_lint.py reports no errors (use --strict to fail on warnings too).
• render.mjs shows the intended motion at the start, middle, and end.
• For a loop, the first and last frames match — check the filmstrip, not the numbers.
• Nothing is clipped or off canvas unless that was the intent.

Report what you verified and what you did not. If you could not render it, say that plainly instead of implying the motion was checked.