animation-design

Animation Design

Find and embed brand-coherent animations into web projects. Supports Lottie (decorative motion, looping animations) and Rive (interactive components, state machines). Works with single animations and cohesive series.

Invocation

/animation-design loading spinner — search with intent from $ARGUMENTS
/animation-design rive toggle button — explicitly target Rive
/animation-design UI feedback set — find a cohesive Lottie series
/animation-design — no arguments: ask what kind of animation is needed

Lottie vs Rive — When to Use Which

Use Case	Recommendation	Why
Loading spinners, success/error feedback	Lottie	Huge library, simple embed, no interactivity needed
Decorative hero animations, backgrounds	Lottie	Wider selection, CDN-hosted, lightweight
Interactive buttons, toggles, switches	Rive	State machines handle hover/click/active states
Complex multi-state UI components	Rive	State machines with triggers, booleans, numbers
Animated icons that respond to user input	Rive	Built-in interactivity, no JS event wiring
Onboarding flows, empty states	Lottie	More variety, play-once animations
Game-like UI, character animations	Rive	Bones, mesh deformation, state machines

Default to Lottie unless the animation needs to respond to user interaction. Lottie has a much larger ecosystem of free assets.

Workflow

Step 1: Detect Project Context

Scan the current project to determine framework and brand context.

Framework detection — check package.json dependencies:

react / next → React
vue / nuxt → Vue
svelte / @sveltejs/kit → Svelte
None of the above → plain HTML

Check if any animation packages are already installed:

Lottie: @lottiefiles/dotlottie-react, @lottiefiles/dotlottie-vue, @lottiefiles/dotlottie-svelte, @lottiefiles/lottie-player
Rive: @rive-app/react-webgl2, @rive-app/react-canvas, @rive-app/canvas

Brand context detection — look in this priority order:

DESIGN.md in project root (from brand-skill — richest source)
CSS files with :root custom properties (Grep for :root in *.css)
tailwind.config.* (extract theme.extend.colors)
Any design-guidelines.md or brand*.md files

If no brand context is found, note it to the user and proceed with their description only.

Output a brief summary: "Detected Next.js (React) project with DESIGN.md. Ready to search."

Step 2: Understand Brand Attributes

If brand context was found, extract key signals:

Mood/personality from emotive narrative (e.g., "quiet confidence", "playful energy")
Color palette — dark or light background, warm or cool, muted or vibrant
Aesthetic keywords from visual philosophy (e.g., "minimal", "organic", "brutalist")
Anti-patterns — what the brand is NOT ("not corporate", "not loud")

Load references/brand-to-animation.md for the translation table. Map brand attributes to search modifiers.

Combine brand modifiers with the user's intent ($ARGUMENTS) to form the search strategy.

Step 3: Determine Animation Type

Route to Lottie or Rive based on:

Explicit request — user says "rive" or "lottie" → use that
Interactive intent — "toggle", "button", "hover state", "interactive" → Rive
Decorative intent — "loading", "spinner", "background", "empty state" → Lottie
Ambiguous — present both options with a recommendation

Step 4: Search

Lottie Search (LottieFiles)

⚠️ lottiefiles.com pages are Cloudflare-bot-gated (verified May 2026 — every WebFetch and curl returns 403 regardless of User-Agent). The public GraphQL endpoint at graphql.lottiefiles.com is not gated and serves the full search + animation metadata API. Always query GraphQL — never WebFetch the website.

Single animation mode (GraphQL — primary path):

POST to https://graphql.lottiefiles.com/ with:

query Search($q: String!) {
  searchPublicAnimations(query: $q, first: 8, orderBy: { column: VIEWS_COUNT, order: DESC }) {
    edges {
      node {
        name slug url
        lottieUrl    # .lottie zip (use with @lottiefiles/dotlottie-react etc.)
        jsonUrl      # raw JSON (use with @lottiefiles/lottie-player@2.0.3 — required for plain HTML)
        lottieFileSize bgColor
        createdBy { firstName lastName }
      }
    }
  }
}

via:

curl -s -X POST https://graphql.lottiefiles.com/ \
  -H "Content-Type: application/json" \
  --data '{"query":"...","variables":{"q":"signature pen"}}'

Run 2-4 search variants covering different angles of the intent (e.g. "signature pen", "outline minimal", "wax seal stamp"). The full GraphQL schema is introspectable — __schema{queryType{fields{name args{name}}}} lists every public field.
Filter results in code (don't loop WebFetch — that path is dead):
- Reject anything > 100KB if intended as background (load weight)
- Prefer bgColor: "#FFFFFF" or null (recolorable)
- Prefer animations under "lined", "outline", or single-line names for monochrome
Present the shortlist with the JSON URL exposed so the user can preview by clicking.

Series mode (user says "set", "series", "collection", or requests multiple related animations):

Run the GraphQL search for the first concept; pick the strongest match
Then query publicAnimationsByUser(userId: …, first: 20) for the same creator's full catalogue
Build the set from same-creator animations first (strongest coherence signal)
If the creator doesn't cover all needed purposes, run additional GraphQL searches with style-matched queries
Load references/lottie-categories.md for series templates

Embed URL selection (critical):

If the project will use the plain-HTML <lottie-player> web component (the only one that survives Vercel/Cloudflare-Pages deploys), embed jsonUrl — not lottieUrl. lottie-player@2.0.3 cannot read .lottie zip files.
If the project uses @lottiefiles/dotlottie-react / dotlottie-vue / dotlottie-svelte, embed lottieUrl (the .lottie file).
Both URLs come from the same assets-v2.lottiefiles.com/a/<uuid>/<id>.{json|lottie} CDN and are not bot-gated.

Rive Search (Marketplace)

Run 2-3 WebSearch queries: site:rive.app {intent} {brand-modifier} and site:rive.app/marketplace {intent}
WebFetch promising results to check style, state machine complexity, creator
Note: Rive marketplace has fewer assets than LottieFiles — may need to broaden search
Check creator's other work for series coherence

Present results:

1. **[Animation Name]** by [Creator]
   - Preview: [page URL]
   - CDN/Download: [assets URL]
   - Type: Lottie / Rive (interactive)
   - Colors: [brief palette description]
   - Size: [X KB]
   - Brand fit: [one sentence assessment]
   - State machines: [if Rive — list state machine names and inputs]

For series, present as a grouped set with a coherence note.

Step 5: User Selects

Single mode: "Which would you like to embed? (1-5)"
Series mode: present the set as a group, allow swapping individual items
Offer to refine search with different terms if nothing fits

Step 6: Embed

Load references/embedding-patterns.md (Lottie) or references/rive-embedding-patterns.md (Rive) for exact code patterns.

Lottie Install

Install the appropriate package if not present:
- React: npm install @lottiefiles/dotlottie-react
- Vue: npm install @lottiefiles/dotlottie-vue
- Svelte: npm install @lottiefiles/dotlottie-svelte
- HTML: CDN script tag for @lottiefiles/lottie-player@2.0.3 (NOT dotlottie-wc)

Rive Install

Install the appropriate package if not present:
- React: npm install @rive-app/react-webgl2
- Vue: npm install @rive-app/canvas
- Svelte: npm install @rive-app/canvas
- HTML: CDN script tag via unpkg (@rive-app/canvas)
For Rive: download the .riv file and place in public/animations/ (no public CDN — must self-host)

Common Steps

Generate component(s) with the selected animation's URL or local path.

For series, create a shared animations config:

// animations.ts
export const animations = {
  loading: "/animations/loader.riv",      // or .lottie CDN URL
  success: "/animations/checkmark.riv",
  error: "/animations/cross.riv",
} as const;

Plus a reusable wrapper component that takes a purpose key.

Use the project's spacing system for sizing (CSS variables, Tailwind classes, or explicit px).
Note creator attribution as a code comment.

Animation Coherence Guidelines

Motion matches energy. A "quiet confidence" brand needs subtle, slow animations. A "playful" brand can use bouncy, exaggerated motion. Adjust with the speed prop (0.5 for slower, 2 for faster).

Color compatibility. Both Lottie and Rive animations have baked-in colors. Filter search results for palette fit. Prefer monochrome/outline animations for maximum flexibility across themes.

Purpose over decoration. Every animation communicates something: loading states, success confirmations, empty states, onboarding, transitions. "Add an animation because it feels empty" is not a reason — what is the animation communicating?

Series consistency. When embedding multiple animations, they must feel like they came from the same designer. Same line weight, same motion language, same color approach. Prioritize same-creator animations.

Interactive vs decorative. Don't use Rive for a simple looping spinner — that's Lottie territory. Don't use Lottie for a button that needs hover/active/disabled states — that's Rive territory. Match the tool to the job.

Reference Files

references/embedding-patterns.md — Lottie framework-specific code snippets, speed/event control, series barrel pattern
references/rive-embedding-patterns.md — Rive framework-specific code snippets, state machine control, series pattern
references/brand-to-animation.md — brand personality → search modifier translation tables, Lottie vs Rive selection
references/lottie-categories.md — common categories, series templates, alternative keywords, Rive marketplace notes
examples/workflow-example.md — end-to-end Lottie single + series example, Rive interactive component example

Technical Notes

Lottie

Plain HTML: Use @lottiefiles/lottie-player@2.0.3 (NOT dotlottie-wc — it breaks on live domains/Vercel deploys). Use <lottie-player> tag with self-hosted JSON files extracted from .lottie zips. See embedding-patterns.md for details.
React/Vue/Svelte: The @lottiefiles/dotlottie-react / dotlottie-vue / dotlottie-svelte packages work fine in bundled frameworks. These can use .lottie format directly.
lottie-web is deprecated — don't use it.
CDN URLs from lottie.host or assets-v2.lottiefiles.com are directly embeddable for framework packages.
For plain HTML deploys: download .lottie files, unzip to extract the JSON, self-host in a /lotties/json/ directory. .lottie files are just zips containing JSON + assets.

Rive

All frameworks: Use @rive-app/canvas (base) or @rive-app/react-webgl2 (React). No dedicated Vue or Svelte packages — use canvas runtime directly.
No public CDN for .riv files. Always self-host in public/animations/ or similar.
State machines are the key differentiator — they handle interactivity without custom JS event code.
Always call resizeDrawingSurfaceToCanvas() in the onLoad callback for crisp rendering on high-DPI displays.
.riv files are binary (not JSON). Typically 10-15x smaller than equivalent Lottie JSON.
Rive marketplace has fewer free assets than LottieFiles — may need to broaden searches.

General

Fetch animation pages sequentially (not parallel) to avoid rate limiting. Limit to 5-6 page fetches per search.
If WebFetch fails on a specific page, use the URL from search results directly.