Design Engineering — How Things Move and Feel

• Design system decides: colors, fonts, surfaces, spacing, border radius, component structure
• This skill decides: easing curves, durations, spring configs, gesture thresholds, animation sequencing, transform-origin, interaction states, perceived performance

If the design system bans box-shadow, backdrop-filter, or blur — respect that. This skill's animation techniques work with transform and opacity alone.

Core Philosophy

Taste is trained, not innate

Good taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. You develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly.

When building UI, don't just make it work. Study why the best interfaces feel the way they do. Reverse engineer animations. Inspect interactions. Be curious.

Unseen details compound

Most details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. That is the goal.

"All those unseen details combine to produce something that's just stunning, like a thousand barely audible voices all singing in tune." — Paul Graham

Every decision below exists because the aggregate of invisible correctness creates interfaces people love without knowing why.

Beauty is leverage

People select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Beauty is underutilized in software. Use it as leverage to stand out.

Review Format (Required)

When reviewing UI animation or interaction code, use a markdown table with Before/After/Why columns:

Never use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table.

The Animation Decision Framework

Before writing any animation code, answer these questions in order:

1. Should this animate at all?

Ask: How often will users see this animation?

Never animate keyboard-initiated actions. These actions are repeated hundreds of times daily. Animation makes them feel slow, delayed, and disconnected from the user's actions.

Raycast has no open/close animation. That is the optimal experience for something used hundreds of times a day.

2. What is the purpose?

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

Valid purposes:

• Spatial consistency: toast enters and exits from the same direction, making swipe-to-dismiss feel intuitive
• State indication: a morphing feedback button shows the state change
• Explanation: a marketing animation that shows how a feature works
• Feedback: a button scales down on press, confirming the interface heard the user
• Preventing jarring changes: elements appearing or disappearing without transition feel broken

If the purpose is just "it looks cool" and the user will see it often, don't animate.

3. What easing should it use?

Is the element entering or exiting? Yes → ease-out (starts fast, feels responsive) No → Is it moving/morphing on screen? Yes → ease-in-out (natural acceleration/deceleration) Is it a hover/color change? Yes → ease Is it constant motion (marquee, progress bar)? Yes → linear Default → ease-out

Use custom easing curves. The built-in CSS easings are too weak. They lack the punch that makes animations feel intentional.

/* Strong ease-out for UI interactions */
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);

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

/* iOS-like drawer curve (from Ionic Framework) */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);

Never use ease-in for UI animations. It starts slow, which makes the interface feel sluggish. 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.

Easing resources: Use easing.dev or easings.co to find stronger custom variants.

4. How fast should it be?

UI animations should stay under 300ms. A 180ms dropdown feels more responsive than a 400ms one. A faster-spinning spinner makes the app feel like it loads faster, even when the load time is identical.

Perceived performance

Speed in animation is not just about feeling snappy — it directly affects how users perceive your app's performance:

• A fast-spinning spinner makes loading feel faster (same load time, different perception)
• A 180ms select animation feels more responsive than a 400ms one
• Instant tooltips after the first one is open (skip delay + skip animation) make the whole toolbar feel faster

The perception of speed matters as much as actual speed. Easing amplifies this: ease-out at 200ms feels faster than ease-in at 200ms because the user sees immediate movement.

Spring Animations

Springs feel more natural than duration-based animations because they simulate real physics. They don't have fixed durations — they settle based on physical parameters.

When to use springs

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

Spring-based mouse interactions

Tying visual changes directly to mouse position feels artificial because it lacks motion. Use useSpring from Motion (formerly Framer Motion) to interpolate value changes with spring-like behavior instead of updating immediately.

import { useSpring } from 'framer-motion';

// Without spring: feels artificial, instant
const rotation = mouseX * 0.1;

// With spring: feels natural, has momentum
const springRotation = useSpring(mouseX * 0.1, {
  stiffness: 100,
  damping: 10,
});

This works because the animation is decorative — it doesn't serve a function. If this were a functional data visualization in a dashboard, no animation would be better. Know when decoration helps and when it hinders.

Spring configuration

Apple's approach (easier to reason about):

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

Traditional physics (more control):

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

Keep bounce subtle (0.1–0.3) when used. Avoid bounce in most UI contexts. Use it for drag-to-dismiss and playful interactions.

Interruptibility advantage

Springs maintain velocity when interrupted — CSS animations and keyframes restart from zero. This makes springs ideal for gestures users might change mid-motion. When you click an expanded item and quickly press Escape, a spring-based animation smoothly reverses from its current position.

Component Interaction Principles

Buttons must feel responsive

Add transform: scale(0.97) on :active. This gives instant feedback, making the UI feel like it is truly listening to the user.

.button {
  transition: transform 160ms var(--ease-out, cubic-bezier(0.23, 1, 0.32, 1));
}

.button:active {
  transform: scale(0.97);
}

This applies to any pressable element. The scale should be subtle (0.95–0.98).

Never animate from scale(0)

Nothing in the real world disappears and reappears completely. Elements animating from scale(0) look like they come out of nowhere.

Start from scale(0.9) or higher, combined with opacity:

/* Bad */
.entering { transform: scale(0); }

/* Good */
.entering { transform: scale(0.95); opacity: 0; }

Make popovers origin-aware

Popovers should scale in from their trigger, not from center. Exception: modals. Modals keep transform-origin: center because they are not anchored to a specific trigger.

Tooltips: skip delay on subsequent hovers

Tooltips should delay before appearing to prevent accidental activation. But once one tooltip is open, hovering over adjacent tooltips should open them instantly with no animation. This feels faster without defeating the purpose of the initial delay.

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

.tooltip[data-starting-style],
.tooltip[data-ending-style] {
  opacity: 0;
  transform: scale(0.97);
}

/* Skip animation on subsequent tooltips */
.tooltip[data-instant] {
  transition-duration: 0ms;
}

Use CSS transitions over keyframes for interruptible UI

CSS transitions can be interrupted and retargeted mid-animation. Keyframes restart from zero. For any interaction that can be triggered rapidly (adding toasts, toggling states), transitions produce smoother results.

Use blur to mask imperfect transitions

When a crossfade between two states feels off, add subtle filter: blur(2px) during the transition. Note: Only use this technique if the project's design system permits blur. If blur is banned (as in some command-center aesthetics), use opacity-only crossfades instead.

Keep blur under 20px when allowed. Heavy blur is expensive, especially in Safari.

Animate enter states with @starting-style

The modern CSS way to animate element entry without JavaScript:

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

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

This replaces the common React pattern of using useEffect to set mounted: true after initial render. Use @starting-style when browser support allows.

CSS Transform Mastery

translateY with percentages

Percentage values in translate() are relative to the element's own size. Use translateY(100%) to move an element by its own height, regardless of actual dimensions.

Prefer percentages over hardcoded pixel values. They are less error-prone and adapt to content.

scale() scales children too

Unlike width/height, scale() also scales an element's children. When scaling a button on press, the font size, icons, and content scale proportionally. This is a feature, not a bug.

3D transforms for depth

rotateX(), rotateY() with transform-style: preserve-3d create real 3D effects in CSS. Use sparingly and purposefully.

clip-path for Animation

clip-path is one of the most powerful animation tools in CSS.

The inset shape

clip-path: inset(top right bottom left) defines a rectangular clipping region:

/* Fully hidden from right */
.hidden { clip-path: inset(0 100% 0 0); }

/* Fully visible */
.visible { clip-path: inset(0 0 0 0); }

Practical patterns

• Hold-to-delete: clip-path: inset(0 100% 0 0) on overlay, animate to inset(0 0 0 0) over 2s linear on :active, snap back 200ms ease-out on release
• Image reveals on scroll: Start inset(0 0 100% 0), animate to inset(0 0 0 0) on viewport entry
• Comparison sliders: Overlay two images, clip the top with inset(0 50% 0 0), adjust on drag

Gesture and Drag Interactions

Momentum-based dismissal

Don't require dragging past a threshold. Calculate velocity: Math.abs(dragDistance) / elapsedTime. If velocity exceeds ~0.11, dismiss regardless of distance. A quick flick should be enough.

Damping at boundaries

When a user drags past the natural boundary, apply damping. The more they drag, the less the element moves. Things in real life don't suddenly stop; they slow down first.

Pointer capture for drag

Once dragging starts, set the element to capture all pointer events. This ensures dragging continues even if the pointer leaves the element bounds.

Multi-touch protection

Ignore additional touch points after the initial drag begins. Without this, switching fingers mid-drag causes the element to jump.

Friction instead of hard stops

Instead of preventing upward drag entirely, allow it with increasing friction. It feels more natural than hitting an invisible wall.

Performance Rules

Only animate transform and opacity

These properties skip layout and paint, running on the GPU. Animating padding, margin, height, or width triggers all three rendering steps.

CSS variables are inheritable

Changing a CSS variable on a parent recalculates styles for all children. In a container with many items, updating --swipe-amount on the parent causes expensive style recalculation. Update transform directly on the element instead.

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

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

Framer Motion hardware acceleration caveat

Framer Motion's shorthand properties (x, y, scale) are NOT hardware-accelerated. They use requestAnimationFrame on the main thread. For hardware acceleration, use the full transform string:

// NOT hardware accelerated
<motion.div animate={{ x: 100 }} />

// Hardware accelerated
<motion.div animate={{ transform: "translateX(100px)" }} />

CSS animations beat JS under load

CSS animations run off the main thread. When the browser is busy, Framer Motion animations (using requestAnimationFrame) drop frames. CSS animations remain smooth. Use CSS for predetermined animations; JS for dynamic, interruptible ones.

Use WAAPI for programmatic CSS animations

The Web Animations API gives you JavaScript control with CSS performance. Hardware-accelerated, interruptible, and no library needed.

element.animate(
  [{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
  { duration: 1000, fill: 'forwards', easing: 'cubic-bezier(0.77, 0, 0.175, 1)' }
);

Accessibility

prefers-reduced-motion

Reduced motion means fewer and gentler animations, not zero. Keep opacity and color transitions. Remove movement and position animations.

@media (prefers-reduced-motion: reduce) {
  .element {
    animation: fade 0.2s ease;
    /* No transform-based motion */
  }
}

Touch device hover states

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

Touch devices trigger hover on tap, causing false positives. Gate hover animations behind this media query.

Stagger Animations

When multiple elements enter together, stagger their appearance with 30–80ms delays between items. Long delays make the interface feel slow. Never block interaction while stagger animations play.

.item {
  opacity: 0;
  transform: translateY(8px);
  animation: fadeIn 300ms var(--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); }
}

Asymmetric Enter/Exit Timing

Pressing should be slow when it needs to be deliberate (hold-to-delete: 2s linear), but release should always be snappy (200ms ease-out). Slow where the user is deciding, fast where the system is responding.

Debugging Animations

Slow motion testing

Temporarily increase duration to 2–5x normal, or use browser DevTools animation inspector. 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 in sync?

Frame-by-frame inspection

Step through animations frame by frame in Chrome DevTools (Animations panel).

Test on real devices

For touch interactions, test on physical devices. The Xcode Simulator is an alternative but real hardware is better for gesture testing.

Cohesion matters

Animation values should match the personality of the component. A playful component can be bouncier. A professional data dashboard should be crisp and fast. Match the motion to the mood.

When in doubt for a data-dense, engineering-grade interface: shorter durations, no bounce, strong ease-out curves. Let the data be the star; motion stays invisible and supportive.

Review Checklist

The Sonner Principles (Building Loved Components)

These principles from Sonner (13M+ weekly npm downloads) apply to any component:

1. Developer experience is key. Minimize setup friction.
2. Good defaults matter more than options. Ship beautiful out of the box.
3. Handle edge cases invisibly. Pause timers on hidden tabs. Capture pointer events during drag. Users never notice these, and that is exactly right.
4. Use transitions, not keyframes, for dynamic UI. Rapidly-added elements need interruptible animation.
5. Review your work the next day. Fresh eyes notice imperfections you missed during development.