emilkowal-animations

SKILL.md

Emil Kowalski Animation Best Practices

Comprehensive animation guide for web interfaces based on Emil Kowalski's teachings, open-source libraries (Sonner, Vaul), and his animations.dev course. Contains 58 rules across 8 categories, prioritized by impact.

When to Apply

Reference these guidelines when:

Adding animations to React components

Choosing easing curves or timing values

Implementing gesture-based interactions (swipe, drag)

Building toast notifications or drawer components

Optimizing animation performance

Ensuring animation accessibility

Expressing any of the above with Tailwind CSS v4 utilities (see the tw- category)

Rule Categories by Priority

Priority
Category
Impact
Prefix

1
Easing Selection
CRITICAL
ease-

2
Timing & Duration
CRITICAL
timing-

3
Property Selection
HIGH
props-

4
Transform Techniques
HIGH
transform-

5
Interaction Patterns
MEDIUM-HIGH
interact-

6
Strategic Animation
MEDIUM
strategy-

7
Accessibility & Polish
MEDIUM
polish-

8
Tailwind v4 Utilities
MEDIUM
tw-

Quick Reference

1. Easing Selection (CRITICAL)

ease-out-default - Use ease-out as your default easing

ease-custom-curves - Use custom cubic-bezier over built-in CSS

ease-in-out-onscreen - Use ease-in-out for on-screen movement

ease-spring-natural - Use spring animations for natural motion

ease-spring-config - Configure springs with duration and bounce

ease-ios-drawer - Use iOS-style easing for drawer components

ease-context-matters - Match easing to animation context

2. Timing & Duration (CRITICAL)

timing-300ms-max - Keep UI animations under 300ms

timing-faster-better - Faster animations improve perceived performance

timing-asymmetric - Use asymmetric timing for press and release

timing-tooltip-delay - Delay initial tooltips, instant subsequent ones

timing-drawer-500ms - Use 500ms duration for drawer animations

3. Property Selection (HIGH)

props-transform-opacity - Animate only transform and opacity

props-hardware-accelerated - Use hardware-accelerated animations when main thread is busy

props-will-change - Use will-change to prevent 1px shift

props-avoid-css-variables - Avoid CSS variables for drag animations

props-clip-path-performant - Use clip-path for layout-free reveals

4. Transform Techniques (HIGH)

transform-scale-097 - Scale buttons to 0.97 on press

transform-never-scale-zero - Never animate from scale(0)

transform-percentage-translate - Use percentage values for translateY

transform-origin-aware - Make animations origin-aware

transform-scale-children - Scale transforms affect children

transform-3d-preserve - Use preserve-3d for 3D transform effects

transform-starting-style - Animate enter states with @starting-style

5. Interaction Patterns (MEDIUM-HIGH)

interact-interruptible - Make animations interruptible

interact-momentum-dismiss - Use momentum-based dismissal

interact-damping - Damp drag at boundaries

interact-scroll-drag-conflict - Resolve scroll and drag conflicts

interact-snap-points - Implement velocity-aware snap points

interact-friction-upward - Allow upward drag with friction

interact-pointer-capture - Use pointer capture for drag operations

interact-multitouch - Ignore extra touch points during drag

interact-touch-hover - Gate hover animations behind a pointer media query

6. Strategic Animation (MEDIUM)

strategy-keyboard-no-animate - Never animate keyboard-initiated actions

strategy-frequency-matters - Consider interaction frequency before animating

strategy-purpose-required - Every animation must have a purpose

strategy-feedback-immediate - Provide immediate feedback on all actions

strategy-marketing-exception - Marketing sites are the exception

strategy-cohesion - Match motion to the component's personality

strategy-review-fresh-eyes - Review animations in slow motion and the next day

7. Accessibility & Polish (MEDIUM)

polish-reduced-motion - Respect prefers-reduced-motion

polish-opacity-fallback - Use opacity as reduced motion fallback

polish-framer-hook - Use useReducedMotion hook in Framer Motion

polish-dont-remove-all - Keep gentle animation for reduced motion

polish-blur-bridge - Use blur to bridge animation states

polish-clip-path-tabs - Use clip-path for tab transitions

polish-toast-stacking - Implement toast stacking with scale and offset

polish-scroll-reveal - Trigger scroll animations at appropriate threshold

polish-hover-gap-fill - Fill gaps between hoverable elements

polish-stagger-children - Stagger child animations for orchestration

8. Tailwind v4 Utilities (MEDIUM)

Express the principles above with proper Tailwind CSS v4 utilities. Applies only to Tailwind v4 projects; the raw-CSS and Framer Motion rules above remain the source of truth.

tw-ease-duration-defaults - Set ease-out and a sub-300ms duration explicitly

tw-custom-easing-theme - Register custom easing curves as @theme tokens

tw-press-scale - Use active:scale-[0.97] for button press feedback

tw-asymmetric-timing - Split press and release timing with active:duration

tw-starting-enter - Animate enter states with the starting: variant

tw-reduced-motion - Gate movement behind motion-safe / motion-reduce

tw-origin-aware - Set transform-origin with origin-* utilities

tw-will-change - Scope will-change-transform to the active gesture

Key Values Reference

Value
Usage

cubic-bezier(0.23, 1, 0.32, 1)
Strong ease-out for UI interactions

cubic-bezier(0.77, 0, 0.175, 1)
Strong ease-in-out for on-screen movement

cubic-bezier(0.32, 0.72, 0, 1)
iOS-style drawer/sheet animation

scale(0.97)
Button press feedback

scale(0.95)
Minimum enter scale (never scale(0))

200ms ease-out
Standard UI transition

300ms
Maximum duration for UI animations

500ms
Drawer animation duration

0.11 px/ms
Velocity threshold for momentum dismiss

100px
Scroll-reveal viewport threshold

14px
Toast stack offset

Duration by Element

Pick duration by how often the element is seen and how much it moves. Keep UI animations under 300ms.

Element
Duration

Button press feedback
100–160ms

Tooltips, small popovers
125–200ms

Dropdowns, selects
150–250ms

Modals, drawers
200–500ms

Marketing / explanatory
Can be longer

Reference Files

File
Description

references/_sections.md
Category definitions and ordering

assets/templates/_template.md
Template for new rules

metadata.json
Version and reference information