SKILL.md

$2a

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 directly to clarify what you cannot infer.

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 acceleration: Use transform and opacity, avoid layout properties

will-change: Add sparingly for known expensive animations

Reduce paint: Minimize repaints, use contain where appropriate

Monitor FPS: Ensure 60fps on target devices

Accessibility

@media (prefers-reduced-motion: reduce) {

  * {

    animation-duration: 0.01ms !important;

    animation-iteration-count: 1 !important;

    transition-duration: 0.01ms !important;

  }

}

NEVER:

Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself

Animate layout properties (width, height, top, left)—use transform instead

Use durations over 500ms for feedback—it feels laggy

Animate without purpose—every animation needs a reason

Ignore prefers-reduced-motion—this is an accessibility violation

Animate everything—animation fatigue makes interfaces feel exhausting

Block interaction during animations unless intentional

Verify Quality

Test animations thoroughly:

Smooth at 60fps: No jank on target devices

Feels natural: Easing curves feel organic, not robotic

Appropriate timing: Not too fast (jarring) or too slow (laggy)

Reduced motion works: Animations disabled or simplified appropriately

Doesn't block: Users can interact during/after animations

Adds value: Makes interface clearer or more delightful

Remember: 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.

animate