text-to-lottie

---
name: text-to-lottie
description: Create, edit, or fix Lottie/Bodymovin JSON animations for the local Skia Skottie player. Use for text-to-Lottie, SVG/logo/type animation, loaders/icons, state feedback, UI microinteractions, lower thirds, diagrams, data/stat/chart animations, product promos, scene/camera motion, visual effects, scene edits, slots/controls, and Skottie debugging.
---

# Text To Lottie

Author production-ready Lottie JSON for the official local Skia Skottie player.
The deliverable is a renderable scene in the player, not isolated JSON.

## Operating Model

- Use the official player project and verify in Skia Skottie. Do not hand-roll a
  custom viewer or switch renderers for verification.
- Keep the skill portable across Agent Skills clients. Avoid host-specific
  commands, command modes, or orchestration conventions in skill instructions.
- Prefer fewer questions and stronger defaults. Ask only when a decision changes
  the output materially, such as transparent vs full-frame background, brand
  constraints, target format, or supplied source assets.
- Prioritize clean, intentional, professional motion over merely satisfying the
  literal prompt.

## Reference Loading

This `SKILL.md` is the thin control plane. Load only one-level references that
match the task. Do not open the whole reference library.

Always read `references/player-contract.md` before creating, editing, fixing, or
verifying a scene. If a routed reference is unavailable, continue using the
inline rules in this file.

| User intent | References to read when present |
| --- | --- |
| Any new/edit/fix Lottie scene | `references/player-contract.md` |
| JSON structure, keyframes, slots, shapes, assets | `references/lottie-spec-map.md` |
| Logo animation | `references/recipe-logo.md`, `references/motion-taste.md`, `references/design-taste.md` |
| Typography, title, quote, text reveal | `references/recipe-typography.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Lower third, name tag, caption bar, overlay | `references/recipe-lower-thirds.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Loader, icon, spinner, badge animation | `references/recipe-loaders-icons.md`, `references/motion-taste.md` |
| Success, error, warning, completion, empty state | `references/recipe-loaders-icons.md`, `references/design-taste.md`, `references/motion-taste.md` |
| UI microinteraction | `references/recipe-ui-microinteractions.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Generic "animate this SVG" or SVG-to-Lottie | `references/recipe-svg-animation.md`, `references/svg-compatibility.md`, `references/motion-taste.md` |
| Camera follow, pan, zoom, parallax, scene motion | `references/recipe-camera-scene-motion.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Diagram, technical line animation, callout, flow trace | `references/recipe-diagram-technical.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Data, stats, KPIs, charts, metrics, dashboard figures | `references/recipe-data-stats.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Product launch, feature announcement, social promo | `references/recipe-product-promo.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Long text, multiple ideas, list/features/steps, timeline, before/after, problem/solution, quote+proof, recap/story, product walkthrough, multi-language variations, chapters, multi-beat sequence, episode, jump/hard cuts, transition grammar | `references/chapterization-transition-grammar.md`, `references/motion-taste.md` |
| Glow, glass, metal, gradient, fill, bubble/burst effects | `references/recipe-visual-effects.md`, `references/design-taste.md`, `references/motion-taste.md` |
| SVG input inside logo/icon/UI/lower-third work | The task recipe plus `references/svg-compatibility.md` |
| Starter brief or reusable project direction | `references/recipe-starter-projects.md`, `references/design-taste.md`, `references/motion-taste.md` |
| Any "premium", "clean", "minimal", "modern", "sleek", or "polished" qualifier | `references/design-taste.md` (restraint defaults), plus the routed recipe |

For mixed prompts, choose one primary recipe from the main deliverable, then add
secondary references for source format or visual treatment. Examples: SVG logo
with glow uses logo as primary plus SVG compatibility and visual effects;
product launch with pan/zoom uses product promo plus camera scene motion;
technical SVG diagram tracing uses diagram/technical plus SVG compatibility;
kinetic title with glass sweep uses typography plus visual effects.

## Workflow

1. Route the task using the table above. Read only the relevant references that
   exist.
2. Locate the official player project and resolve the target scene using the
   target precedence below. Before editing, verify the resolved path is
   `public/projects/<project>/<scene-N>/lottie.json`; re-read that current file
   immediately before overwriting because the UI can write slot edits back to
   source.
3. Decide the background policy before authoring.
4. Write or update `public/projects/<project>/<scene-N>/lottie.json` and, when
   useful, `controls.json`.
5. Validate JSON, run or reuse the dev server, inspect exact frames with
   `?frame=N`, and fix render/design/motion issues before finishing.

## Inline Rules

### Design Defaults (always apply)

These few defaults are non-negotiable and apply to every designed scene. Load
`references/design-taste.md` for the full reasoning, especially for any
"premium", "clean", "minimal", "modern", or "card" prompt.

- Premium means subtract, not add. When a prompt says premium, clean, minimal,
  modern, sleek, or sophisticated, default to restraint: remove chrome before
  adding it. Premium is carried by scale, weight, brightness, spacing, and
  timing, never by cards, borders, dividers, shadows, glow, or stacked tints.
- Chrome/container budget is `0` by default. Do not add a framing card,
  container, border, or divider unless it does a job that whitespace and
  alignment cannot. Separate grids and columns with negative space and alignment
  first, a single hairline second, and a filled or bordered card last and only
  when explicitly warranted.
- One surface tone. Use one background tone. Do not stack two near-black or two
  near-white tints to fake a "surface"; it reads muddy. If a card surface must
  differ from the background, make it one deliberate step with a clear purpose.
- One divider treatment, one color. If dividers are truly needed, use one weight
  and one color for all of them, title rule and column rules included. Never use
  slightly different colors or weights per divider.

### Scene Rules

- Scene files live at `public/projects/<project>/<scene-N>/lottie.json`.
- Resolve target scenes by authority: an explicit file path wins; a browser URL
  route like `/<project>/<scene>` wins next; an already-known project/scene for
  the task wins next; otherwise create a new safe scene. Use `/__context` only
  for discovery, verification, or playback state unless the task explicitly says
  to edit what is currently on screen and no more specific target exists. Do not
  let `/__context.live` override a known file path, URL, or project/scene.
  Overwrite `main-project/scene-1` only if it is still the untouched placeholder;
  otherwise create a new scene.
- Full-frame standalone compositions should include a visible background layer
  with a `bgColor` slot and `controls.json` entry.
- Transparent-by-default outputs include logos, icons, loaders, overlays, lower
  thirds, and SVG-derived assets unless the user asks for a background.
- Include top-level `v`, `fr`, `ip`, `op`, `w`, `h`, `nm`, `assets`, and
  `layers`. Treat `op` as exclusive.
- Use purposeful easing and staging. Avoid defaulting to linear motion. Derive
  easing from the behavior-based anchors in `motion-taste.md` (chosen by motion
  behavior, focal element strongest); do not fall back to one uniform ease for
  every layer.
- Use slots for important editable values and add `controls.json` labels/ranges
  when they improve the properties panel.
- For SVG input, preserve the viewBox, normalize styling, watch fill rules and
  intersections, and verify the result in Skottie.
- Native Lottie text/text slots (`ty:5`) render in this player when the scene
  ships its font: drop a `.ttf`/`.otf`/`.ttc` next to `lottie.json`, declare it in
  `fonts.list` with `fFamily` matching the font's embedded family name, and
  reference it from text documents. The loader passes every scene font to Skottie.
  Prefer native text; reach for vector/shape text only for deliberate path effects
  (stroke-on, glyph morphs, handwriting). See the player-contract "Native Text"
  reference.

## Verification

Before finishing:

1. Confirm the intended target file path is
   `public/projects/<project>/<scene-N>/lottie.json`.
2. Validate JSON:

   ```bash
   node -e "JSON.parse(require('fs').readFileSync('public/projects/<project>/<scene-N>/lottie.json','utf8'))"
   ```

3. Confirm the official player is running and the scene appears in
   `GET /__context`.
4. Inspect pinned frames in the browser. For new scenes, check frame `0`,
   midpoint, and `op - 1`.
5. Confirm the background policy matches the use case.
6. Check for blank canvas, missing assets, unstyled shapes, wrong layer order,
   bad easing, awkward timing, cropped content, text overflow, and visible SVG
   artifacts.
7. Finish only when the animation renders cleanly and feels intentional.

## Maintenance Evals

Do not read eval files during normal animation work. Use them only when testing
or changing this skill:

- `evals/trigger-prompts.json`
- `evals/routing-prompts.json`
- `evals/reference-loading-prompts.json`
- `evals/output-rubric.md`

From diffusionstudio/lottie at 3c72912, shown as plain text under its license: MIT (permissive). The license text is in LICENSE.

• SKILL.md9.9 KB · d2e5e6151f07
• evals/
• output-rubric.md11 KB · 997cc9ae21a2
• reference-loading-prompts.json5.6 KB · 83223c6792ba
• routing-prompts.json9.3 KB · c4f3f3b22abd
• trigger-prompts.json3.1 KB · 110b57abab15
• references/
• chapterization-transition-grammar.md8.9 KB · faf753c1950a
• design-taste.md15 KB · 07f070118733
• lottie-spec-map.md3.3 KB · 44615a817bd0
• motion-taste.md13 KB · f0c8e080be17
• player-contract.md14 KB · dfc5c2eabe86
• recipe-camera-scene-motion.md2.6 KB · ec09e5f8bc03
• recipe-data-stats.md5.1 KB · 8b3ed850c367
• recipe-diagram-technical.md5.0 KB · 7a9281f91a27
• recipe-loaders-icons.md2.8 KB · bd5bd60c2df8
• recipe-logo.md2.9 KB · 625a6b9b314e
• recipe-lower-thirds.md2.2 KB · d7adaa82f722
• recipe-product-promo.md4.4 KB · 4dc5197f9a93
• recipe-starter-projects.md2.6 KB · c5e0a7c53fb1
• recipe-svg-animation.md2.6 KB · eb650af24063
• recipe-typography.md7.9 KB · fcee6e899fae
• recipe-ui-microinteractions.md2.6 KB · 4ac3c915bf27
• recipe-visual-effects.md4.9 KB · 79eb0ec0ebff
• svg-compatibility.md3.6 KB · 49803663d905

23 files, 143 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.