/animate

name: animate
description: "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive."
argument-hint: "[target]"
user-invocable: false

Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.

MANDATORY PREPARATION

Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: performance constraints.

---

Assess Animation Opportunities

Analyze where motion would improve the experience:

1. **Identify static areas**:

• **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.)
• **Jarring transitions**: Instant state changes that feel abrupt (show/hide, page loads, route changes)
• **Unclear relationships**: Spatial or hierarchical relationships that aren't obvious
• **Lack of delight**: Functional but joyless interactions
• **Missed guidance**: Opportunities to direct attention or explain behavior

2. **Understand the context**:

• What's the personality? (Playful vs serious, energetic vs calm)
• What's the performance budget? (Mobile-first? Complex page?)
• Who's the audience? (Motion-sensitive users? Power users who want speed?)
• What matters most? (One hero animation vs many micro-interactions?)

If any of these are unclear from the codebase, Ask the user using AskUserQuestion.

**CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.

Plan Animation Strategy

Create a purposeful animation plan:

• **Hero moment**: What's the ONE signature animation? (Page load? Hero section? Key interaction?)
• **Feedback layer**: Which interactions need acknowledgment?
• **Transition layer**: Which state changes need smoothing?
• **Delight layer**: Where can we surprise and delight?

**IMPORTANT**: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments.

Implement Animations

Add motion systematically across these categories:

Entrance Animations

• **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations
• **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
• **Content reveals**: Scroll-triggered animations using intersection observer
• **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management

Micro-interactions

• **Button feedback**:
• Hover: Subtle scale (1.02-1.05), color shift, shadow increase
• Click: Quick scale down then up (0.95 → 1), ripple effect
• Loading: Spinner or pulse state
• **Form interactions**:
• Input focus: Border color transition, slight scale or glow
• Validation: Shake on error, check mark on success, smooth color transitions
• **Toggle switches**: Smooth slide + color transition (200-300ms)
• **Checkboxes/radio**: Check mark animation, ripple effect
• **Like/favorite**: Scale + rotation, particle effects, color transition

State Transitions

• **Show/hide**: Fade + slide (not instant), appropriate timing (200-300ms)
• **Expand/collapse**: Height transition with overflow handling, icon rotation
• **Loading states**: Skeleton screen fades, spinner animations, progress bars
• **Success/error**: Color transitions, icon animations, gentle scale pulse
• **Enable/disable**: Opacity transitions, cursor changes

Navigation & Flow

• **Page transitions**: Crossfade between routes, shared element transitions
• **Tab switching**: Slide indicator, content fade/slide
• **Carousel/slider**: Smooth transforms, snap points, momentum
• **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators

Feedback & Guidance

• **Hover hints**: Tooltip fade-ins, cursor changes, element highlights
• **Drag & drop**: Lift effect (shadow + scale), drop zone highlights, smooth repositioning
• **Copy/paste**: Brief highlight flash on paste, "copied" confirmation
• **Focus flow**: Highlight path through form or workflow

Delight Moments

• **Empty states**: Subtle floating animations on illustrations
• **Completed actions**: Confetti, check mark flourish, success celebrations
• **Easter eggs**: Hidden interactions for discovery
• **Contextual animation**: Weather effects, time-of-day themes, seasonal touches

Technical Implementation

Use appropriate techniques for each animation:

Timing & Easing

**Durations by purpose:**

• **100-150ms**: Instant feedback (button press, toggle)
• **200-300ms**: State changes (hover, menu open)
• **300-500ms**: Layout changes (accordion, modal)
• **500-800ms**: Entrance animations (page load)

**Easing curves (use these, not CSS defaults):**

/* Recommended - natural deceleration */
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth, refined */
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */

/* AVOID - feel dated and tacky */
/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */

**Exit animations are faster than entrances.** Use ~75% of enter duration.

CSS Animations

/* Prefer for simple, declarative animations */
- transitions for state changes
- @keyframes for complex sequences
- transform + opacity only (GPU-accelerated)

JavaScript Animation

/* Use for complex, interactive animations */
- Web Animations API for programmatic control
- Framer Motion for React
- GSAP for complex sequences

Performance

• **GPU acceler