| 1 | > **Additional context needed**: performance constraints. |
| 2 | |
| 3 | Add 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 | |
| 9 | Brand: motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions. The saturated AI default is fade-and-rise reveals on every scrolled section; that's a tell, not a choreography. Reserve scroll-triggered motion for moments that earn it. |
| 10 | |
| 11 | Product: 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 | |
| 17 | Analyze where motion would improve the experience: |
| 18 | |
| 19 | 1. **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 | |
| 26 | 2. **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 | |
| 32 | If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat 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 | |
| 38 | Create 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 | |
| 49 | Add motion systematically across these categories: |
| 50 | |
| 51 | ### Entrance Animations |
| 52 | - **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects) |
| 53 | - **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management |
| 54 | - **List rhythm**: Sibling stagger is legitimate for cards-in-a-grid or list-items-appearing. Whole-section fade-on-scroll is not a list and is not legitimate. Cap total stagger time: 10 items at 50ms each = 500ms total. For more items, reduce per-item delay or cap the staggered count. |
| 55 | |
| 56 | Use CSS custom properties for clean stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"`, `style="--i: 1"`, etc. on each item. |
| 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 | |
| 97 | Use appropriate techniques for each animation: |
| 98 | |
| 99 | ### Timing & Easing |
| 100 | |
| 101 | **Duration: the 100/300/500 rule.** Timing matters more than easing for "feels right": |
| 102 | |
| 103 | | Duration | Use Case | Examples | |
| 104 | |----------|----------|----------| |
| 105 | | **100–150ms** | Instant feedback | Button press, toggle, color change | |
| 106 | | **200–300ms** | State changes | Menu open, tooltip, hover state | |
| 107 | | **300–500ms** | Layout changes | Accordion, modal, drawer | |
| 108 | | **500–800ms** | Entrance animations | Page load, hero reveal | |
| 109 | |
| 110 | **Easing curves (use these, not CSS defaults):** |
| 111 | ```css |
| 112 | /* Recommended: natural deceleration */ |
| 113 | --ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth */ |
| 114 | --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */ |
| 115 | --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */ |
| 116 | |
| 117 | /* AVOID: feel dated and tacky */ |
| 118 | /* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */ |
| 119 | /* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */ |
| 120 | ``` |
| 121 | |
| 122 | **Exit animations are faster than entrances.** Use ~75% of enter duration. |
| 123 | |
| 124 | ### CSS Animations |
| 125 | ```css |
| 126 | /* Prefer for simple, declarative animations */ |
| 127 | - transitions for state changes |
| 128 | - @keyframes for complex sequences |
| 129 | - transform and opacity for reliable movement |
| 130 | - blur, filters, masks, clip paths, shadows, and color shifts for premium atmospheric effects when verified smooth |
| 131 | ``` |
| 132 | |
| 133 | ### JavaScript Animation |
| 134 | ```javascript |
| 135 | /* Use for complex, interactive animations */ |
| 136 | - Web Animations API for programmatic control |
| 137 | - Framer Motion for React |
| 138 | - GSAP for complex sequences |
| 139 | ``` |
| 140 | |
| 141 | ### Motion Materials |
| 142 | |
| 143 | Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties. Match material to effect: |
| 144 | |
| 145 | - **Transform / opacity**: movement, press feedback, simple reveals, list choreography |
| 146 | - **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances |
| 147 | - **Clip-path / masks**: wipes, reveals, editorial cropping, product-like transitions |
| 148 | - **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state |
| 149 | - **Grid-template-rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly |
| 150 | |
| 151 | The hard rule isn't "transform and opacity only." It's: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify smoothness in-browser on target viewports. |
| 152 | |
| 153 | ### Performance |
| 154 | - **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins) |
| 155 | - **will-change**: Add sparingly for known expensive animations only (e.g. on `:hover` or an `.animating` class), never preemptively across the whole page |
| 156 | - **Scroll triggers**: Use Intersection Observer instead of scroll event listeners; unobserve after the animation fires once |
| 157 | - **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate |
| 158 | - **Monitor FPS**: Ensure 60fps on target devices |
| 159 | |
| 160 | ### Perceived Performance |
| 161 | |
| 162 | Nobody cares how fast your site *is*, only how fast it feels. The 80ms threshold: anything under ~80ms feels instant because our brains buffer sensory input for that long to synchronize perception. Target this for micro-interactions. |
| 163 | |
| 164 | - **Preemptive start**: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening. |
| 165 | - **Early completion**: Show content progressively, don't wait for everything (progressive images, streaming HTML, skeleton fade-ins). |
| 166 | - **Optimistic UI**: Update the interface immediately, handle failures gracefully. Use for low-stakes actions (likes, follows). Avoid for payments or destructive operations. |
| 167 | - **Easing affects perceived duration**: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily. Ease-out feels satisfying for entrances. |
| 168 | - **Caution**: Too-fast responses can decrease perceived value for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening. |
| 169 | |
| 170 | ### Accessibility |
| 171 | ```css |
| 172 | @media (prefers-reduced-motion: reduce) { |
| 173 | * { |
| 174 | animation-duration: 0.01ms !important; |
| 175 | animation-iteration-count: 1 !important; |
| 176 | transition-duration: 0.01ms !important; |
| 177 | } |
| 178 | } |
| 179 | ``` |
| 180 | |
| 181 | **NEVER**: |
| 182 | - Use bounce or elastic easing curves; they feel dated and draw attention to the animation itself |
| 183 | - Animate layout properties casually (`width`, `height`, `top`, `left`, margins) when transform, FLIP, or grid-based techniques would work |
| 184 | - Use durations over 500ms for feedback (it feels laggy) |
| 185 | - Animate without purpose (every animation needs a reason) |
| 186 | - Ignore `prefers-reduced-motion` (this is an accessibility violation) |
| 187 | - Animate everything (animation fatigue makes interfaces feel exhausting) |
| 188 | - Block interaction during animations unless intentional |
| 189 | |
| 190 | ## Verify Quality |
| 191 | |
| 192 | Test animations thoroughly: |
| 193 | |
| 194 | - **Smooth at 60fps**: No jank on target devices |
| 195 | - **Feels natural**: Easing curves feel organic, not robotic |
| 196 | - **Appropriate timing**: Not too fast (jarring) or too slow (laggy) |
| 197 | - **Reduced motion works**: Animations disabled or simplified appropriately |
| 198 | - **Doesn't block**: Users can interact during/after animations |
| 199 | - **Adds value**: Makes interface clearer or more delightful |
| 200 | |
| 201 | When the motion clarifies state instead of decorating it, hand off to `$impeccable polish` for the final pass. |
| 202 |