motion-craft

Motion Craft

Animations that communicate, not decorate. Every frame must earn its place.

Inspired by Emil Kowalski (Linear, Sonner, Vaul), Paul Lewis (Google Chrome), and the CSS Animation Working Group.

Workflow

The Animation Decision Framework

Before writing any animation code, answer these four questions in order.

1. Should this animate at all?

Never animate keyboard-initiated actions. These repeat hundreds of times daily.

2. What is the purpose?

Every animation must have a clear answer to "why does this animate?"

3. What easing should it use?

Critical: never use ease-in for UI entering animations. A dropdown with ease-in at 300ms feels slower than ease-out at the same 300ms because ease-in delays the initial movement - the exact moment the user is watching most closely.

4. How fast should it be?

Rule: UI animations should stay under 300ms. A 180ms dropdown feels noticeably more responsive than a 400ms one.

Custom easing curves

The built-in CSS ease / ease-in / ease-out are too weak. Use these stronger custom variants:

:root {
  --ease-out-strong: cubic-bezier(0.23, 1, 0.32, 1);     /* UI interactions, Emil's signature */
  --ease-in-out-strong: cubic-bezier(0.77, 0, 0.175, 1);  /* On-screen movement */
  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);          /* iOS-like drawer */
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);         /* Slow reveals, dramatic */
  --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);       /* Alternative strong ease-out */
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);       /* Slight overshoot, sparingly */
}

Sources: easing.dev, easings.co

---

The 60fps Golden Rule

16.67ms per frame. Verify with Chrome DevTools Performance tab. Only animate transform and opacity.

Review Format (Required)

When reviewing UI animation code, you MUST use a markdown table with Before | After | Why columns. Do NOT use a list with "Before:" and "After:" on separate lines.

Correct format:

Wrong format (never do this):

Before: transition: all 300ms
After: transition: transform 200ms ease-out

---

CSS Transitions (preferred for UI)

CSS transitions are interruptible - they can be retargeted mid-animation. Keyframes restart from zero. For any interaction that can be triggered rapidly (toasts, toggles, dropdowns), transitions produce smoother results.

.button {
  transition: transform 160ms ease-out;
}
.button:active {
  transform: scale(0.97);
}

.tooltip {
  transition: transform 125ms ease-out, opacity 125ms ease-out;
  transform-origin: var(--transform-origin);
}

Asymmetric enter / exit timing

Enter can be slower (user is deciding), exit must be fast (system responding):

.overlay {
  transition: clip-path 200ms ease-out;  /* release: fast */
}
.button:active .overlay {
  transition: clip-path 2s linear;       /* press: slow and deliberate */
}

Tooltips: skip delay on subsequent hovers

.tooltip {
  transition: transform 125ms ease-out, opacity 125ms ease-out;
  transform-origin: var(--transform-origin);
}
.tooltip[data-instant] {
  transition-duration: 0ms;
}

Enter states with @starting-style (Chrome-only as of 2026, not yet Baseline)

.toast {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 400ms ease-out, transform 400ms ease-out;

  @starting-style {
    opacity: 0;
    transform: translateY(100%);
  }
}

Note: @starting-style and scroll-driven animations (animation-timeline: view(), animation-timeline: scroll()) are Chrome-only as of 2026. Use JavaScript fallbacks for cross-browser support.

Hold-to-delete pattern

.overlay {
  clip-path: inset(0 100% 0 0);
  transition: clip-path 200ms ease-out;   /* release: fast */
}
.button:active .overlay {
  clip-path: inset(0 0 0 0);
  transition: clip-path 2s linear;        /* press: slow and deliberate */
}

---

BUTTONS - Tactile Feedback

Every pressable element needs physical response.

.button {
  transition: transform 160ms cubic-bezier(0.23, 1, 0.32, 1);
}
.button:active {
  transform: scale(0.97);
}

The scale must be subtle (0.95-0.98). Applied to all pressable elements - buttons, cards, list items, tabs.

---

POPOVERS - Origin-Aware

Popovers scale from their trigger, not center. Modals stay centered.

/* Radix UI */
.popover {
  transform-origin: var(--radix-popover-content-transform-origin);
}
/* Base UI */
.popover {
  transform-origin: var(--transform-origin);
}
/* Modals (always centered) */
.modal {
  transform-origin: center;
}

Whether the user notices individually does not matter. In the aggregate, unseen details compound.

---

Stagger Animations

When multiple elements enter together, stagger their appearance.

.item {
  opacity: 0;
  transform: translateY(8px);
  animation: fadeIn 300ms ease-out forwards;
}
.item:nth-child(1) { animation-delay: 0ms; }
.item:nth-child(2) { animation-delay: 50ms; }
.item:nth-child(3) { animation-delay: 100ms; }
.item:nth-child(4) { animation-delay: 150ms; }

@keyframes fadeIn {
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

Keep stagger delays short (30-80ms between items). Never block interaction while stagger plays.

---

CSS Animations (keyframes)

Use for predetermined, non-dynamic animations. Keyframes restart from zero on interruption - avoid for UI.

@keyframes enter-right {
  from { opacity: 0; transform: translateX(16px); }
  to   { opacity: 1; transform: translateX(0); }
}
.enter {
  animation: enter-right 300ms ease-out forwards;
}

---

Spring Animations

Springs feel more natural than duration-based animations because they simulate real physics. They maintain velocity when interrupted.

When to use springs

• Drag interactions with momentum
• Elements that feel "alive" (Apple Dynamic Island style)
• Gestures that can be interrupted mid-animation
• Decorative mouse-tracking interactions

Apple approach (recommended - easier to reason about)

{ type: "spring", duration: 0.5, bounce: 0.2 }

Traditional physics (more control)

{ type: "spring", stiffness: 100, damping: 10, mass: 1 }

Keep bounce subtle (0.1-0.3). Avoid bounce in most UI. Use for drag-to-dismiss and playful interactions only.

Spring-based mouse interactions

import { useSpring } from 'framer-motion'

const springX = useSpring(mouseX * 0.1, { stiffness: 100, damping: 10 })

Without spring: feels artificial, instant. With spring: feels natural, has momentum.

---

WEB ANIMATIONS API (WAAPI)

Programmatic CSS animations. Hardware-accelerated, interruptible, no library needed.

const element = document.querySelector('.card')

const animation = element.animate([
  { transform: 'scale(1)', opacity: 1 },
  { transform: 'scale(0.95)', opacity: 0.7 },
], {
  duration: 200,
  easing: 'cubic-bezier(0.23, 1, 0.32, 1)',
  fill: 'both',
})

animation.pause()
animation.play()
animation.reverse()
animation.finish()
animation.finished.then(() => console.log('done'))

WAAPI beats Framer Motion under heavy load - it runs off the main thread. Use for dynamic, interruptible animations where CSS keyframes fall short.

---

SCROLL-DRIVEN ANIMATIONS

Browser support note: Scroll-driven animations (animation-timeline: view() and scroll()) are Chrome/Edge-only as of 2026, not yet Baseline. Provide JS fallbacks via IntersectionObserver for Firefox/Safari.

ViewTimeline (element enters/leaves viewport)

@keyframes fade-up {
  from { opacity: 0; transform: translateY(20px); }
  to   { opacity: 1; transform: translateY(0); }
}
.reveal {
  animation: fade-up 600ms linear both;
  animation-timeline: view();
  animation-range: entry 0% entry 100%;
}

ScrollTimeline (page scroll position)

@keyframes shrink {
  from { height: 80px; }
  to   { height: 50px; }
}
.site-header {
  animation: shrink 300ms linear both;
  animation-timeline: scroll();
  animation-range: 0 200px;
}

Scroll-linked parallax (vanilla JS)

const layers = document.querySelectorAll('[data-parallax]')
window.addEventListener('scroll', () => {
  const scrollY = window.scrollY
  layers.forEach(layer => {
    const speed = parseFloat(layer.dataset.parallax) || 0.3
    layer.style.transform = `translateY(${scrollY * speed}px)`
  })
})

---

FLIP Technique

For layout animations - animating elements that change position/size.

function animateLayout(element, callback) {
  const first = element.getBoundingClientRect()
  callback()
  const last = element.getBoundingClientRect()

  const dx = first.left - last.left
  const dy = first.top - last.top
  const dw = first.width / last.width
  const dh = first.height / last.height

  element.animate([
    { transform: `translate(${dx}px, ${dy}px) scale(${dw}, ${dh})` },
    { transform: 'translate(0, 0) scale(1, 1)' },
  ], {
    duration: 300,
    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
  })
}

---

CLIP-PATH for Animation

One of the most powerful animation tools in CSS. Hardware-accelerated.

.overlay {
  clip-path: inset(0 100% 0 0);
  transition: clip-path 200ms ease-out;
}
.visible {
  clip-path: inset(0 0 0 0);
}

Use for: hold-to-delete, image reveals on scroll, comparison sliders, seamless color transitions on tabs.

---

PERCEIVED PERFORMANCE

Speed in animation directly affects how users perceive your app:

---

PERFORMANCE RULES

Only animate transform and opacity

These skip layout and paint, running on GPU.

CSS variables are inheritable - avoid for animation

// Bad: triggers recalculation on all children
element.style.setProperty('--swipe-amount', `${distance}px`)

// Good: only affects this element
element.style.transform = `translateY(${distance}px)`

CSS animations beat JS under load

When the browser is busy loading a new page, Framer Motion animations (using requestAnimationFrame) drop frames. CSS animations remain smooth - they run off the main thread.

Framer Motion: use transform string, not shorthand

// NOT hardware accelerated (requestAnimationFrame on main thread)
<motion.div animate={{ x: 100 }} />

// Hardware accelerated (GPU, stays smooth even under load)
<motion.div animate={{ transform: "translateX(100px)" }} />

will-change: use sparingly

.will-animate {
  will-change: transform, opacity;
}

Each will-change creates a new compositor layer, consuming GPU memory. Apply before animation, remove after.

---

ACCESSIBILITY

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

WCAG 2.1 Success Criterion 2.3.3 - Animation from Interactions.

For fine-grained control:

const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches
const userPrefersReduced = localStorage.getItem('reduced-motion') === 'true'
const shouldReduce = prefersReduced || userPrefersReduced

Touch device hover states

@media (hover: hover) and (pointer: fine) {
  .element:hover { transform: scale(1.05); }
}

Touch devices trigger hover on tap. Gate hover animations behind this media query.

---

DEBUGGING ANIMATIONS

Slow motion testing

Play animations at reduced speed to spot issues invisible at full speed. Temporarily increase duration to 2-5x normal, or use browser DevTools animation inspector.

Things to look for:

• Do colors transition smoothly, or do you see two distinct states overlapping?
• Does the easing feel right, or does it start/stop abruptly?
• Is the transform-origin correct?
• Are multiple animated properties (opacity, transform, color) in sync?

Frame-by-frame inspection

Chrome DevTools Animations panel. Step frame by frame. Reveals timing issues between coordinated properties invisible at full speed.

Test on real devices

For touch interactions (drawers, swipe gestures), test on physical devices. Connect phone via USB, visit local dev server by IP address, use Safari remote devtools.

---

REVIEW CHECKLIST

---

PRE-FLIGHT CHECKLIST

Before delivering animated UI code:

• No animation on keyboard-initiated actions
• Every animation has a stated purpose (why does this animate?)
• Easing curve matches scenario (entering ? ease-out, exiting ? ease-in)
• UI duration under 300ms (button 100-160ms, dropdown 150-250ms, modal 200-300ms)
• Exit faster than enter (asymmetric timing)
• Only transform and opacity animated (GPU composite)
• prefers-reduced-motion respected
• Hover animations gated behind @media (hover: hover)
• Touch targets 44x44mm minimum
• No scale(0) entries - start from scale(0.95)
• Popover transform-origin anchors to trigger
• Stagger delays under 80ms
• No transition: all - exact properties only
• Framer Motion: transform string over x/y shorthand
• will-change removed after animation completes
• Button press: scale(0.97) on :active
• Tested on real device for touch interactions

---

Anti-Patterns

BANNED PATTERNS

---

Error Handling

Checklist

• Animation uses compositor-only properties (transform, opacity) where possible
• prefers-reduced-motion respected — fallback to static or reduced variant
• Easing curve appropriate for the motion type (spring for UI, ease for enter/exit)
• Before/After states compared — animation solves a real UX problem
• Tested on mobile and with throttled CPU to verify 60fps

Sources

• Emil Kowalski - animations.dev, Sonner, Vaul (Linear team)
• Paul Lewis - "Stick to compositor-only properties" (Google Chrome)
• Web Animations API Specification (W3C)
• CSS Scroll-Driven Animations Specification (W3C)
• WCAG 2.1 Guideline 2.3.3 - Animation from Interactions
• easing.dev, easings.co - custom easing curve builders
• motion.dev - Animation reference
• Framer Motion documentation