lottie-animator

Lottie Animator - SVG to Motion Graphics

Professional skill to create advanced Lottie animations from SVGs, eliminating the After Effects workflow entirely by using intelligent motion design.

Quality Gate: Generate → Inspect → Revise

Do not stop when the JSON parses. Every generated animation must pass three checks:

1. Structural — required Lottie metadata exists, timing is valid, layers is an array, and all referenced assets resolve.
2. Motion — preview the first, middle, and final loop states. Check that the hero is visible, the loop closes cleanly, and no element clips the canvas.
3. Intent — compare the result with the chosen motion personality and emotional target. Remove decorative motion that competes with the subject.

When working in this repository, run:

python3 scripts/validate_lottie.py examples/your-animation.json

Use a small first pass, inspect it, then revise timing, easing, staging, or layer order. Do not claim visual quality from JSON alone.

---

Quick Reference: 8-Step Animation Checklist

Before creating or writing any animation keyframes, you MUST align on the following checklist:

1. Emotional target? — What should the viewer feel? (joy, calm, trust, excitement, urgency)
2. Motion Personality? — Select exactly one archetype: Playful, Premium, Corporate, or Energetic.
3. Primary property? — Focus on the hero transition first: position (p), scale (s), rotation (r), or opacity (o).
4. Distance and Timing? — Calculate target frames based on the 1/3 spatial scaling rule.
5. Easing family? — Map curve constants: entrance = ease-out, exit = ease-in, loop = ease-in-out.
6. Hero elements? — Plan staging offsets (hero enters 100-200ms after background).
7. Secondary & ambient layers? — Plan secondary accents (shadow shifts, spark wiggles).
8. Volume Preservation? — Keep X/Y scale multiplication constant (~10,000) for wiggles and squashes (skip for premium).

---

When to Activate

Activate this skill when the user requests:

• Animate a logo, icon, or SVG graphic
• Create motion graphics or vector animations
• Generate Lottie JSON files
• Effects: wiggle, bounce, rotate, pulse, fade, scale, morph
• Entrance, loop, loading animations, or transitions
• Path drawing/reveal animations (Trim Path)
• Character animation, walking cycles, run cycles
• Shape morphing (icon transitions)
• Replace After Effects workflow

Decision tree:

1. Does it serve a functional purpose (feedback, guidance)? → Apply strict responsive timing rules (<150ms).
2. Does it express brand personality? → Select and stick to a single Motion Personality archetype.
3. Does it tell a story or guide attention? → Apply adapted Disney principles (anticipation, arcs, staging).
4. Is this a complex multi-element scene? → Plan layers, parenting bone systems, and stagger offsets.

---

Critical: SVG Understanding

Before animating ANY SVG, you MUST understand its path structure.

See: references/svg-to-lottie.md

SVG Path Command Quick Reference

Command	Description	Lottie Conversion
M x,y	Move to	Starting vertex
L x,y	Line to	Vertex with zero tangents
C cp1 cp2 end	Cubic bezier	Native support
Q ctrl end	Quadratic bezier	Convert to cubic
A rx ry ...	Arc	Split into cubic segments
Z	Close path	Set c: true

Path to Lottie Vertex Formula

For C x1,y1 x2,y2 x,y from point (px, py):
- Previous vertex outTangent: [x1-px, y1-py]
- Current vertex: [x, y]
- Current vertex inTangent: [x2-x, y2-y]

---

Main Workflow

Phase 1: Motion Philosophy (30 seconds)

MANDATORY before any code. Define:

1. Brand Personality: Professional, playful, elegant, energetic (see references/motion-personality.md)
2. Emotional Response: Trust, excitement, calm, urgency
3. Motion Metaphor: Fluid like water, solid like rock, light like air

Example: "Fintech Logo → professional + trust → precise and controlled movement"
Example: "Music App → creative + energy → organic with rhythmic pulses"
Example: "Healthcare → calm + reliable → smooth, slow easings"

Phase 2: SVG Deep Analysis

Before animating, thoroughly analyze:

1. Structure: Elements, groups, paths, viewBox dimensions
2. Path Complexity: Vertex count, curve types (C, Q, A commands)
3. Hierarchy: Primary elements vs. secondary details
4. Animation Opportunities: Independent parts, stroke-based vs fill-based

# Analyze SVG structure
cat icon.svg | grep -E '<(path|g|rect|circle|ellipse|line|polyline)' | head -30

Key Questions:

• Is it stroke-based? → Consider Trim Path animation.
• Multiple paths? → Consider staggered entrance.
• Complex shape? → Consider scale/rotate instead of morph.
• Icon library (Phosphor/Lucide)? → Clean, minimal vertices.

Phase 3: Animation Strategy Selection

Strategy	Best For	Technique	Reference
Draw On	Stroke icons, signatures	Trim Path	references/shape-modifiers.md
Pop In	Logos, buttons	Scale + Opacity	references/disney-principles.md
Morph	Icon transitions (hamburger→X)	Path keyframes	references/professional-techniques.md
Stagger	Multiple elements	Delayed start times	references/disney-principles.md
Character	People, mascots	Parenting + bone hierarchy	references/professional-techniques.md
Loader	Progress, spinners	Rotation + Trim Path	references/shape-modifiers.md
Frame-by-Frame	Walk/run cycles, complex characters	ip/op layer switching	references/professional-techniques.md

---

Phase 4: Create Lottie JSON

See: references/lottie-structure.md

Base Structure:

{
  "v": "5.12.1",
  "fr": 60,
  "ip": 0,
  "op": 120,
  "w": 512,
  "h": 512,
  "nm": "Animation Name",
  "ddd": 0,
  "assets": [],
  "layers": []
}

---

Phase 5: Apply Professional Easing and Timing

Map bezier curves and frame durations strictly using your selected archetype.

See: references/bezier-easing.md

Use Case	Out Tangent (o)	In Tangent (i)	Rationale
Entrance (Ease Out)	[0.33, 0]	[0.67, 1]	Fast start, gentle settle
Exit (Ease In)	[0.55, 0.055]	[0.675, 0.19]	Gentle start, explosive departure
Loop (Ease In Out)	[0.645, 0.045]	[0.355, 1]	Seamless symmetrical timing
Bounce (Playful)	[0.34, 1.56]	[0.64, 1]	Bouncy overshoot, soft settle
Spring (Elastic)	[0.5, 1.5]	[0.5, 0.9]	High responsiveness, dynamic tension

---

Phase 6: Validate and Export

# Validate the complete Lottie contract when working in this repository
python3 scripts/validate_lottie.py animation.json

# Fallback: validate JSON syntax in any project
python3 -c "import json; json.load(open('animation.json'))"

# Preview
echo "Open in: https://lottiefiles.com/preview"

Before delivery, verify the animation at 0%, 50%, and 100% of its loop. If the final frame visibly jumps, shorten the loop or match the first and last poses; never hide a bad loop behind autoplay.

---

Shape Modifiers

See: references/shape-modifiers.md

Trim Path (Icon Drawing Animation)

{
  "ty": "tm",
  "s": {"a": 0, "k": 0},
  "e": {
    "a": 1,
    "k": [
      {"t": 0, "s": [0], "o": {"x": [0.33], "y": [0]}, "i": {"x": [0.67], "y": [1]}},
      {"t": 45, "s": [100]}
    ]
  },
  "o": {"a": 0, "k": 0},
  "m": 1
}

Repeater (Radial/Linear Patterns)

{
  "ty": "rp",
  "c": {"a": 0, "k": 8},
  "tr": {
    "r": {"a": 0, "k": 45},
    "so": {"a": 0, "k": 100},
    "eo": {"a": 0, "k": 30}
  }
}

Offset Path (Glow/Outline Effects)

{
  "ty": "op",
  "a": {"a": 1, "k": [{"t": 0, "s": [0]}, {"t": 30, "s": [8]}]},
  "lj": 2
}

---

Advanced Techniques & Reference Links

Ensure you consult specific reference documents for complex animation behaviors:

• Disney Principles: Apply squash/stretch, anticipation, and arcs correctly.
  • references/disney-principles.md
• Brand Personalities: Select Playful, Premium, Corporate, or Energetic.
  • references/motion-personality.md
• Bone Parenting & Rigs: Rig layers using parenting offsets.
  • references/professional-techniques.md
• Frame-by-Frame Switching: Implement walk cycles using layered ip/op sprite frames.
  • references/professional-techniques.md
• GSAP & ScrollTrigger Integration: Bind Lottie scrub parameters, canvas pools, and 3D spring deflections to mouse/scroll events.
  • references/lottie-gsap-integration.md
• Lottie Tools & Ecosystem: Select editing workflows, leverage dotLottie (.lottie) compression packaging, and audit run-time rendering.
  • references/lottie-tools-ecosystem.md
• Bezier Easing Reference: Map snappiness using custom cubic bezier coordinates.
  • references/bezier-easing.md