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