1---
  2name: animate
  3description: "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."
  4argument-hint: "[target]"
  5user-invocable: true
  6---
  7
  8Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
  9
 10## MANDATORY PREPARATION
 11
 12Invoke {{command_prefix}}impeccable — 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 {{command_prefix}}impeccable teach first. Additionally gather: performance constraints.
 13
 14---
 15
 16## Assess Animation Opportunities
 17
 18Analyze where motion would improve the experience:
 19
 201. **Identify static areas**:
 21   - **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.)
 22   - **Jarring transitions**: Instant state changes that feel abrupt (show/hide, page loads, route changes)
 23   - **Unclear relationships**: Spatial or hierarchical relationships that aren't obvious
 24   - **Lack of delight**: Functional but joyless interactions
 25   - **Missed guidance**: Opportunities to direct attention or explain behavior
 26
 272. **Understand the context**:
 28   - What's the personality? (Playful vs serious, energetic vs calm)
 29   - What's the performance budget? (Mobile-first? Complex page?)
 30   - Who's the audience? (Motion-sensitive users? Power users who want speed?)
 31   - What matters most? (One hero animation vs many micro-interactions?)
 32
 33If any of these are unclear from the codebase, {{ask_instruction}}
 34
 35**CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
 36
 37## Plan Animation Strategy
 38
 39Create a purposeful animation plan:
 40
 41- **Hero moment**: What's the ONE signature animation? (Page load? Hero section? Key interaction?)
 42- **Feedback layer**: Which interactions need acknowledgment?
 43- **Transition layer**: Which state changes need smoothing?
 44- **Delight layer**: Where can we surprise and delight?
 45
 46**IMPORTANT**: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments.
 47
 48## Implement Animations
 49
 50Add motion systematically across these categories:
 51
 52### Entrance Animations
 53- **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations
 54- **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
 55- **Content reveals**: Scroll-triggered animations using intersection observer
 56- **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management
 57
 58### Micro-interactions
 59- **Button feedback**:
 60  - Hover: Subtle scale (1.02-1.05), color shift, shadow increase
 61  - Click: Quick scale down then up (0.95 → 1), ripple effect
 62  - Loading: Spinner or pulse state
 63- **Form interactions**:
 64  - Input focus: Border color transition, slight scale or glow
 65  - Validation: Shake on error, check mark on success, smooth color transitions
 66- **Toggle switches**: Smooth slide + color transition (200-300ms)
 67- **Checkboxes/radio**: Check mark animation, ripple effect
 68- **Like/favorite**: Scale + rotation, particle effects, color transition
 69
 70### State Transitions
 71- **Show/hide**: Fade + slide (not instant), appropriate timing (200-300ms)
 72- **Expand/collapse**: Height transition with overflow handling, icon rotation
 73- **Loading states**: Skeleton screen fades, spinner animations, progress bars
 74- **Success/error**: Color transitions, icon animations, gentle scale pulse
 75- **Enable/disable**: Opacity transitions, cursor changes
 76
 77### Navigation & Flow
 78- **Page transitions**: Crossfade between routes, shared element transitions
 79- **Tab switching**: Slide indicator, content fade/slide
 80- **Carousel/slider**: Smooth transforms, snap points, momentum
 81- **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators
 82
 83### Feedback & Guidance
 84- **Hover hints**: Tooltip fade-ins, cursor changes, element highlights
 85- **Drag & drop**: Lift effect (shadow + scale), drop zone highlights, smooth repositioning
 86- **Copy/paste**: Brief highlight flash on paste, "copied" confirmation
 87- **Focus flow**: Highlight path through form or workflow
 88
 89### Delight Moments
 90- **Empty states**: Subtle floating animations on illustrations
 91- **Completed actions**: Confetti, check mark flourish, success celebrations
 92- **Easter eggs**: Hidden interactions for discovery
 93- **Contextual animation**: Weather effects, time-of-day themes, seasonal touches
 94
 95## Technical Implementation
 96
 97Use appropriate techniques for each animation:
 98
 99### Timing & Easing
100
101**Durations by purpose:**
102- **100-150ms**: Instant feedback (button press, toggle)
103- **200-300ms**: State changes (hover, menu open)
104- **300-500ms**: Layout changes (accordion, modal)
105- **500-800ms**: Entrance animations (page load)
106
107**Easing curves (use these, not CSS defaults):**
108```css
109/* Recommended - natural deceleration */
110--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth, refined */
111--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
112--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */
113
114/* AVOID - feel dated and tacky */
115/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
116/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */
117```
118
119**Exit animations are faster than entrances.** Use ~75% of enter duration.
120
121### CSS Animations
122```css
123/* Prefer for simple, declarative animations */
124- transitions for state changes
125- @keyframes for complex sequences
126- transform + opacity only (GPU-accelerated)
127```
128
129### JavaScript Animation
130```javascript
131/* Use for complex, interactive animations */
132- Web Animations API for programmatic control
133- Framer Motion for React
134- GSAP for complex sequences
135```
136
137### Performance
138- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
139- **will-change**: Add sparingly for known expensive animations
140- **Reduce paint**: Minimize repaints, use `contain` where appropriate
141- **Monitor FPS**: Ensure 60fps on target devices
142
143### Accessibility
144```css
145@media (prefers-reduced-motion: reduce) {
146  * {
147    animation-duration: 0.01ms !important;
148    animation-iteration-count: 1 !important;
149    transition-duration: 0.01ms !important;
150  }
151}
152```
153
154**NEVER**:
155- Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
156- Animate layout properties (width, height, top, left)—use transform instead
157- Use durations over 500ms for feedback—it feels laggy
158- Animate without purpose—every animation needs a reason
159- Ignore `prefers-reduced-motion`—this is an accessibility violation
160- Animate everything—animation fatigue makes interfaces feel exhausting
161- Block interaction during animations unless intentional
162
163## Verify Quality
164
165Test animations thoroughly:
166
167- **Smooth at 60fps**: No jank on target devices
168- **Feels natural**: Easing curves feel organic, not robotic
169- **Appropriate timing**: Not too fast (jarring) or too slow (laggy)
170- **Reduced motion works**: Animations disabled or simplified appropriately
171- **Doesn't block**: Users can interact during/after animations
172- **Adds value**: Makes interface clearer or more delightful
173
174Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right.