Wiggle Logo Animator

Before creating any animation, answer these three questions:

1. What personality does this brand have? (playful, professional, bold, elegant, innovative, trustworthy)

2. What emotion should the animation evoke? (excitement, trust, creativity, confidence, curiosity)

3. What motion metaphor fits? (organic growth, mechanical precision, energetic burst, elegant reveal, rhythmic pulse)

Example: "Canva = Creative tool brand → Playful energy + organic growth → Simultaneous entrance with pulse"

See Animation Philosophy section below for detailed framework.

2. Analyze Logo Structure (30 seconds - MANDATORY!)

Before creating animation, understand what you're working with:

# For SVG logos - identify elements
python scripts/extract_svg_elements.py logo.svg --list

Quick decision tree:

Logo has text?
  ├─ YES → Read references/text_animation_guide.md FIRST
  └─ NO  → Continue with standard workflow

Multiple elements (icon + text)?
  ├─ YES → Extract separately, decide timing (simultaneous vs staggered)
  └─ NO  → Animate as single unit

SVG or PNG?
  ├─ SVG → Can extract elements cleanly
  └─ PNG → Limited to single-logo animations

3. Prepare Assets

# Single logo (simple animation)
python scripts/prepare_logo.py logo.png --max-size 500 --optimize
# Creates: logo_optimized.png (30-50KB) + logo_base64.txt

# Multi-element logo (extract FIRST, then convert)
python scripts/extract_svg_elements.py logo.svg --output-dir ./elements/
python scripts/prepare_logo.py elements/icon.svg --max-size 200
python scripts/prepare_logo.py elements/text.svg --max-size 250

Size guidelines:

• Full logo (single): 500-600px
• Icon elements: 100-200px
• Text elements: 200-300px

4. Create Lottie JSON Animation

Use EXTERNAL references during development:

{
  "v": "5.7.4",
  "fr": 60,
  "ip": 0,
  "op": 180,
  "w": 800,
  "h": 800,
  "layers": [{
    "ind": 1,
    "ty": 2,
    "nm": "Logo",
    "refId": "logo_image",
    "ks": {
      "o": {
        "a": 1,
        "k": [
          {"t": 0, "s": [0], "e": [100], "i": {"x": [0.42], "y": [1]}, "o": {"x": [0.58], "y": [0]}},
          {"t": 60, "s": [100]}
        ]
      }
    }
  }],
  "assets": [{"id": "logo_image", "w": 512, "h": 512, "p": "logo_optimized.png", "e": 0}]
}

Critical: Use "e": 0 (external reference) during development to avoid Cairo memory errors.

See Animation Patterns below for common effects, or references/detailed_examples.md for full code examples.

5. Validate

# Check Lottie structure (warns about large embedded assets)
python scripts/validate_lottie.py logo_animation.json

# Check loop quality (if creating looping animation)
python scripts/validate_loop.py logo_animation.json

6. Render

# RECOMMENDED: Preview first (renders only first N frames) - saves time!
python scripts/render_lottie.py logo_animation.json preview.gif --preview-frames 60

# Alternative: Test render mode (200x200, 15fps with confirmation prompt)
python scripts/render_lottie.py logo_animation.json logo.gif --test-render

# If preview looks good → Render full animation
python scripts/render_lottie.py logo_animation.json logo.gif

# Optional: MP4 export (better compression than GIF)
python scripts/render_lottie.py logo_animation.json logo.mp4

# Optional: Batch export all formats
python scripts/batch_export.py logo_animation.json ./output gif,mp4,json

Important notes:

• Assets are resolved relative to the Lottie JSON file location (not current working directory)
• Asset validation runs automatically before rendering
• Output verification detects blank/corrupted files
• Use --preview-frames N to render only first N frames for quick validation

7. Optional: Embed for Distribution

After successful rendering, optionally convert to embedded base64 for standalone distribution:

// Replace external reference with base64 from logo_base64.txt
"assets": [{"id": "logo_image", "p": "data:image/png;base64,...", "e": 1}]

Note: Keep external version for future edits/rendering!

Animation Philosophy

The Two-Phase Approach

Phase 1: Define Philosophy (think before implementing)

1. What personality does this brand have?
2. What emotion should the animation evoke?
3. What motion metaphor fits?

Phase 2: Express Through Technical Choices

• Choose properties that express philosophy (position/scale/rotation/opacity)
• Select easing that matches personality (ease-out=confident, bounce=playful)
• Set timing that aligns with emotion (fast=energetic, slow=elegant)

Philosophy Examples

"Confident Professionalism"

• Philosophy: Trustworthy, established, competent
• Expression: Slow ease-out fade (0→100% opacity) + gentle scale (95%→100%)
• Timing: 2s duration, no overshoot
• Example: references/real-world-examples/slack-hover-pinch.json

"Playful Energy"

• Philosophy: Fun, approachable, memorable
• Expression: Bounce entrance with overshoot
• Timing: 1s duration, back easing (0.6/-0.28)
• Example: references/real-world-examples/reddit-hover-pinch.json

"Audio/Speech Brand"

• Philosophy: Sound, rhythm, waveforms, dynamic
• Expression: Vertical waveform with dense keyframes (30-45 keyframes, 60fps)
• Timing: 3s loop, organic easing (0.25/0.75)
• Critical: See "Organic/Continuous Motion" in Motion Types section below

More examples in references/preset_library.md and references/animation_theory.md.

Motion Type Quick Reference

Choose motion type based on brand personality:

Static/Corporate Motion

Professional brands (B2B, finance, legal)

Parameters:

• Keyframes: 8-12 (sparse, deliberate)
• Easing: 0.42/0.58 (standard ease-in-out)
• FPS: 30
• Duration: 1.5-2s

Use for: Corporate logos, B2B brands, professional presentations

Organic/Continuous Motion

Audio, music, speech AI, nature brands

Parameters:

• Keyframes: 25-45 ← Critical for smoothness
• Easing: 0.25/0.75 (softer, more organic)
• FPS: 60 ← Essential for fluidity
• Duration: 3s

Use for: Audio apps, music platforms, speech AI, organic products

Example: Vertical bar waveform pattern in references/detailed_examples.md

Bold/Attention-Grabbing

Startups, social media, marketing

Parameters:

• Keyframes: 15-25
• Easing: 0.34/1.56 (playful bounce) or 0.6/-0.28 (back overshoot)
• FPS: 60
• Duration: 0.8-1.5s

Use for: Startup logos, social media intros, marketing campaigns

Cinematic/Complex

Premium brands, film production

Parameters:

• Keyframes: 50-120
• Easing: Custom bezier curves, variable timing
• FPS: 60-120
• Duration: 3-5s

Use for: Luxury brands, film intros, high-end agency work

Animation Pattern Quick Reference

Single-Element Patterns

Full code examples: references/detailed_examples.md

Multi-Element Coordination

Pattern 1: Simultaneous Entrance Both elements appear together (cohesive brand)

Icon: {"t": 0, "s": [0]}, {"t": 60, "s": [100]}
Text: {"t": 0, "s": [0]}, {"t": 60, "s": [100]}
// Both start at t:0 → Synchronized

Pattern 2: Staggered Entrance Icon establishes first, text reinforces (storytelling)

Icon: {"t": 0, "s": [0]}, {"t": 45, "s": [100]}
Text: {"t": 30, "s": [0]}, {"t": 75, "s": [100]}
// Text delayed 30 frames (0.5s at 60fps)

Timing guidelines:

• 15 frames (0.25s): Subtle stagger
• 30 frames (0.5s): Noticeable sequence ← Most common
• 45 frames (0.75s): Dramatic two-act reveal

Full patterns: references/detailed_examples.md#multi-element-coordination

User Intent Classification

Always classify user intent to select appropriate animation style:

Default: Provide animation rather than asking questions, unless user explicitly requests options.

Known Limitations

Asset Path Resolution

Current behavior:

• External assets (PNGs/SVGs) are resolved relative to the Lottie JSON file location
• The renderer changes the working directory to the JSON file's directory during rendering
• Asset validation runs automatically before rendering begins

Example:

project/
├── animations/
│   └── logo_animation.json  (references "logo_optimized.png")
└── logo_optimized.png

# This will FAIL - asset not found

Solution: Place assets in the same directory as the JSON file:

project/animations/
├── logo_animation.json
└── logo_optimized.png  # ✅ Correct location

Embedded Base64 vs External References

Embedded base64 ("e": 1):

• Pros: Standalone file, easy distribution
• Cons: Cairo MemoryError for images >100KB, larger file sizes, not editable

External references ("e": 0):

• Pros: No memory issues, smaller JSON files, easy to update assets
• Cons: Requires keeping asset files alongside JSON

Recommended workflow:

1. Use external references during development/rendering
2. Optionally embed base64 AFTER successful rendering for distribution
3. Keep external version for future edits

Critical Warnings

❌ Common Mistakes to Avoid

1. Creating animation before defining philosophy → Random trial-and-error wastes 15-30 minutes
2. Using PIL ImageDraw to recreate logo text → Creates DIFFERENT text, not your logo text
3. Embedding base64 before rendering → Cairo MemoryError crash (images >100KB)
4. Using 1000px for small elements → Huge files (400KB+), memory issues
5. Skipping logo analysis → Wrong workflow, have to restart
6. Forgetting loop validation → Visible jump when animation loops
7. Skipping preview renders → Waste time on full renders before validating concept
8. Rendering full SVG then cropping → Fuzzy edges, massive file sizes

Full list with code examples: references/anti_patterns.md

⚠️ Text in Logos - CRITICAL

If logo contains text, you MUST follow specialized workflow:

1. Extract text from logo SVG (do NOT recreate with PIL ImageDraw)
2. Choose appropriate text animation method (fade/stroke/transform)
3. Implement proper synchronization with other elements

See: references/text_animation_guide.md for complete guide

⚠️ External References Required

Always use external file references during development/rendering:

// ✅ CORRECT: External reference
"assets": [{"id": "logo", "p": "logo_optimized.png", "e": 0}]

// ❌ WRONG: Embedded base64 (causes Cairo crash if >100KB)
"assets": [{"id": "logo", "p": "data:image/png;base64,...", "e": 1}]

Why: Cairo renderer crashes with embedded images >100KB. Use external during development, optionally embed AFTER successful rendering.

Helper Scripts Quick Reference

New features in render_lottie.py:

• ✅ Automatic asset validation (checks for missing external files)
• ✅ Asset path resolution (relative to JSON file location)
• ✅ Output verification (detects blank/corrupted files)
• ✅ Preview mode (--preview-frames N) - renders only first N frames
• ✅ Test mode (--test-render) - small test render with confirmation prompt

Detailed usage: references/script_usage.md

Lottie JSON Fundamentals

Basic Structure

{
  "v": "5.7.4",           // Lottie version
  "fr": 60,               // Frame rate
  "ip": 0,                // In point (start frame)
  "op": 180,              // Out point (end frame)
  "w": 800,               // Width
  "h": 800,               // Height
  "layers": [...],        // Animation layers
  "assets": [...]         // Image/asset references
}

Layer Types

• Type 2 (Image Layer): Most common - animates PNG/SVG images
• Type 4 (Shape Layer): Programmatic geometry (circles, rectangles, paths)

Animated Properties

• o: Opacity (0-100)
• p: Position [x, y]
• s: Scale [x%, y%]
• r: Rotation (degrees)
• a: Anchor point [x, y]

Keyframe Structure

"o": {
  "a": 1,  // Animated (1) or static (0)
  "k": [
    {"t": 0, "s": [0], "e": [100], "i": {...}, "o": {...}},
    {"t": 60, "s": [100]}
  ]
}

• t: Time (frame number)
• s: Start value
• e: End value
• i: In tangent (ease in)
• o: Out tangent (ease out)

Complete specification: references/lottie_spec.md

Easing Functions

Never use linear easing - always use curves for professional motion.

Theory and examples: references/animation_theory.md

Dependencies

Required

pip install lottie[all]    # Lottie manipulation
pip install Pillow         # Image processing
pip install pycairo        # Cairo rendering (for GIF)

Cairo Installation

macOS:

brew install cairo pkg-config
pip install pycairo

Linux (Ubuntu/Debian):

sudo apt-get install libcairo2-dev pkg-config python3-dev
pip install pycairo

Verify:

python3 -c "import cairo; print('Cairo OK')"

Troubleshooting: references/troubleshooting.md#cairo-and-dependencies

Troubleshooting

Quick Fixes

Asset not found errors:

• Cause: Assets not in same directory as Lottie JSON
• Fix: Move assets to JSON file's directory, or use absolute paths
• Validation: Run render_lottie.py - it validates assets before rendering

Blank/corrupted output:

• Cause: Missing assets, wrong paths, or rendering errors
• Fix: Check asset validation messages, verify file sizes (output <1KB indicates failure)
• Detection: Output verification runs automatically after rendering

MemoryError during GIF rendering:

• Cause: Embedded base64 images >100KB
• Fix: Use external reference ("e": 0) instead

Loop has visible jump:

• Cause: Last keyframe doesn't match first
• Fix: Run validate_loop.py and ensure last frame = first frame

Text looks wrong:

• Cause: Used PIL ImageDraw to recreate text
• Fix: Extract text from logo SVG with extract_svg_elements.py

Animation too choppy:

• Cause: Too few keyframes or wrong FPS
• Fix: Add keyframes (25-45 for organic motion), use 60fps for continuous motion

Preview renders save time:

• Tip: Use --preview-frames 60 to validate concept before full render
• Tip: Use --test-render for interactive testing with size warnings

Comprehensive guide: references/troubleshooting.md

Advanced References

Detailed Documentation

• references/detailed_examples.md - Full Lottie JSON code for all patterns
• references/animation_theory.md - Motion design principles and easing theory
• references/preset_library.md - Complete preset collection with real-world examples
• references/lottie_spec.md - Lottie JSON specification details
• references/script_usage.md - Complete script documentation
• references/text_animation_guide.md - Specialized text animation workflows
• references/anti_patterns.md - Common mistakes with full code examples
• references/troubleshooting.md - Comprehensive troubleshooting guide
• references/real-world-examples/ - Production animations from major brands

File Size Guidelines

Target sizes for different use cases:

Optimization: Use scripts/optimize_lottie.py to reduce file sizes by removing redundant keyframes and rounding values.

Curated Presets

Quick reference to common presets (full code in references/preset_library.md):

Branding Styles:

• Corporate Subtle - Fade + gentle scale (1.5s)
• Startup Energetic - Bounce + overshoot (1.2s)
• Luxury Elegant - Slow fade + minimal scale (3s)
• Tech Glitch - Digital disruption effect (1s)

Use Cases:

• Website Hero - Quick professional entrance (0.8s)
• Email Signature - Subtle loop (3s)
• Social Media Intro - Bold entrance (2s)
• Splash Screen - Brand moment with exit (2.5s)

Real-World Examples: Study hover animations from major brands in references/real-world-examples/:

• Reddit - Playful elastic bounce
• Slack - Professional restrained pinch
• Medium - Gentle editorial fade
• Flickr - Camera shutter effect
• Discord - Character wink

Quick Decision Checklist

Before creating animation, verify:

• Defined motion philosophy (personality + emotion + metaphor)
• Analyzed logo structure (text? multi-element? SVG or PNG?)
• Chose correct workflow based on analysis
• If text present: Read references/text_animation_guide.md
• Using external references ("e": 0) during development
• Element sizes appropriate (500px full logo, 100-250px elements)
• Selected motion type (Static/Organic/Bold/Cinematic)
• Chosen timing strategy (simultaneous vs staggered)
• Will validate with preview render before full render
• Will run validate_loop.py if creating loop

If all checked → Proceed with confidence ✅

Tips for Success

1. Philosophy first - 30 seconds planning saves 15-30 minutes iteration
2. Analyze before animating - Understand logo structure upfront
3. Preview early, preview often - Test 30-60 frame versions before full render
4. External references during development - Embed base64 only after successful rendering
5. Match motion to brand - Corporate ≠ startup ≠ audio brand
6. Perfect loops matter - Use validate_loop.py to verify
7. Size elements appropriately - 100-250px for elements, not 1000px
8. Extract, don't recreate - Never use PIL to recreate logo text
9. Validate before rendering - Run validate_lottie.py and validate_loop.py
10. Read references when stuck - Detailed docs available for every topic

Remember: The goal is creating motion that enhances brand identity, not random animation. Philosophy-first workflow ensures alignment from the start.