lottie_animation v1.0.0

name: "lottie_animation" description: "Producing Lottie animations for web and apps: vector discipline that survives export, timing and easing for loops and micro-interactions, file size budgets, interactive triggers and fallbacks, and delivery checks across players. Use when creating, exporting, optimizing, embedding, or reviewing a Lottie JSON or dotLottie animation, when a Lottie file is too large or plays wrong in a player, or when wiring hover, click, or scroll triggers to an animation." metadata: { "includeInPrompt": true }

Lottie Animation

Purpose

Ship Lottie animations that play the same in the product as they did in the preview, at a size the page can afford. This skill covers the whole delivery path: authoring inside the features the format actually supports, export, size budgets, player choice, triggers, accessibility fallbacks, and a final check on the shipped file. It works for files authored in After Effects and exported with Bodymovin, files built in Lottie editors, and files generated as JSON by code. Two scripts in scripts/ do real work: lottie_build.py generates two valid working animations, and lottie_audit.py grades any Lottie JSON against the budgets in this skill.

Workflow

1. Decide if Lottie is the right tool

• Use Lottie when a designed vector timeline needs to play, pause, seek or react identically on web and native apps from one file.
• Use CSS or inline SVG instead for a simple hover, fade or spinner. A player plus a JSON file is a heavy price for a fade.
• Use video instead for photographic content, particles or detailed faces. Forcing footage into vectors gives a large file that still looks wrong.
• Write the job in one line before authoring: loop, one shot or interactive, target players, and where it sits on the page. That line decides the format, the budget and the tests.

2. Author inside the supported set

Full rules in references/vector-and-export.md. The short version:

• Build with shape layers. Convert text and Illustrator layers to shapes unless the text must stay live, in which case write down where the font loads.
• Safe material: paths, ellipses, rectangles, stars, fills and strokes, gradient fills and strokes, dashes, trim paths, masks (additive is safe, other modes need a test), transforms, solids, nulls and precomps.
• Risky until proven in an exported test: expressions beyond sliders, camera moves, and the five renderer bound effects (Fill, Pro Levels, Drop Shadow, Tint, Tritone), which only work in the SVG and HTML renderers.
• Out: image sequences, video, audio, negative layer stretching, and most blur and glow effects.
• Animate transforms instead of path shapes when the shape itself does not change, keep anchor points low, and delete hidden layers instead of hiding them.

3. Time it and ease it

• Keyframes in the format carry a frame time t, a hold flag h, and cubic bezier easing handles: o leaving the keyframe, i entering the next one, running from [0,0] to [1,1]. Linear is o x [0,0] and i x [1,1]. Ease in out is o x [0.333] and i x [0.667]. The y value may pass 1, which overshoots on purpose.
• Never ship visible motion on linear easing. Defaults: ease out for entrances, ease in for exits, ease in out for a move between two resting states.
• Budgets for duration: the moving part of a micro-interaction stays under about 0.8 seconds, a one shot status animation runs 1 to 2 seconds and then holds, a UI loop runs 1 to 3 seconds.
• Loops are built at the seam: the first and last frame hold identical values for every animated property, and the easing hands off cleanly across the seam. Check the seam by watching five loops in a row and looking at nothing else.
• Author at 30 fps for web and UI work. Higher frame rates add keyframes and size with little visible gain for most icons and loaders.

4. Build or export, then audit the file

• Export one composition per deliverable as Lottie JSON (.json), the plain text format every player reads.
• Run the audit on the exported file, not the project: python3 scripts/lottie_audit.py animation.json --budget-kb 50
• Fix every FAIL before continuing. A FAIL means a missing top level field, an embedded base64 raster asset, or a file over budget. Treat WARN lines (frame rate above 30, hidden layers, external assets to confirm) as work items, not noise.
• Worked examples, generated and verified with the bundled scripts: python3 scripts/lottie_build.py --out-dir examples writes pulse-loop.json, a seamless 2 second ring loop at 30 fps (1.1 KB raw, 0.4 KB gzipped, audit PASS at the 50 KB icon budget), and checkmark.json, a 1.5 second one shot with a trim path draw on and a marked reduced motion frame (1.8 KB raw, audit PASS). Read them as minimal correct structure: shape layers only, a transform object last in every group, eased keyframes, first frame equal to last frame on the loop.

5. Cut size at the source, then pick the format

Budgets and the full pass are in references/size-and-delivery-checks.md:

• Raw JSON budgets: icon or micro-interaction 50 KB, inline content 100 KB, hero 150 KB. Count the player on top of the file.
• Cut in this order: simplify paths, delete unused layers, remove or externalize raster images, drop to 30 fps, shorten the timeline, minify a shipping copy.
• Still over budget, or the job needs several animations in one package, theming, or state machines: convert to dotLottie (.lottie), a ZIP package that stores images as files and carries themes and state machines. It needs a dotLottie player, and that player carries a WebAssembly engine cost on first load, so it earns its place on multi animation pages and loses on a single small icon.

6. Wire the player, triggers and fallbacks

Player choice, API and patterns are in references/players-and-interactivity.md:

• Load once per page with lottie.loadAnimation({ container, renderer: 'svg', loop, autoplay, path }) and keep the instance. SVG is the default renderer. Call destroy() when the element leaves the page.
• Triggers: hover plays and reverses out, click toggles play segments with playSegments, scroll scrubs with goToAndStop, in view playback runs through IntersectionObserver. State machines exist only in dotLottie packages. Plain JSON gets its logic from page code.
• Fallbacks are part of the build, not polish: respect reduced motion in JavaScript with matchMedia because CSS cannot pause a Lottie render loop, add a pause control to autoplaying loops that sit beside content, mark decorative files aria-hidden, label meaningful ones, and ship a still poster frame for no JavaScript and player failure.

7. Run the delivery check

• Test the shipped file in every target player: current Chrome, Safari and Firefox on web, one mid range Android phone for mobile web, and the real app build for native. Players differ in feature support, and a web preview proves nothing about a native player.
• Walk the states: first play, the loop point, hover in and out, click toggle both ways, reduced motion on, JavaScript off.
• Close with the checklist in references/size-and-delivery-checks.md. If any item fails, the animation is not delivered, whatever the preview looked like.

Output Contract

• The animation file (.json or .lottie), plus the readable master if a minified copy ships.
• A one line job record per animation: purpose (loop, one shot or interactive), canvas size, frame rate, duration, raw and gzipped size, player and renderer, trigger, reduced motion frame, and poster frame file.
• The audit output for each shipped file, with PASS verdict at its budget.
• The player test results: which players and states were checked, and any feature that behaves differently per player, stated plainly.

Operating Rules

1. Verify claims against primary sources: the Lottie specification, the LottieFiles format documentation, the Bodymovin feature list, and the player documentation. Sources for this skill are in ~/workspace/skill-production/scratch/lottie-animation-sources.md. Unverifiable means cut it or label it as a working rule of this skill, the way the size budgets are labelled.
2. Never judge an animation from its After Effects comp or a single web preview. The shipped file in the target player is the only evidence that counts.
3. Budgets are gates, not targets to argue with. A file over budget gets fixed at the source, converted, split or cut. It does not ship heavy.
4. Accessibility fallbacks ship with the animation, every time: reduced motion handling, a pause route for long loops, and a poster frame. An animation without them is unfinished.
5. The format and the players are open source under MIT. Individual animation files carry their own licences. Check the licence of any stock or client file before shipping it, and keep it on file.
6. No em dashes in any copy, caption or UI text produced with this skill. Plain sentences, commas and colons do the job.