interaction-polish

name

interaction-polish

description

Elevate the feel, polish, and 'juice' of UI interactions and animations, in the craft tradition of Emil Kowalski (sonner, vaul) and Josh Comeau. Apply it WHENEVER the user wants an interface to feel better, smoother, more polished, responsive, satisfying, delightful, or 'alive'; when they say an interaction feels stiff, janky, dead, cheap, flat, or off; when they mention adding animation, motion, micro-interactions, springs, transitions, easing, or hover/press effects; or when they ask to 'add juice', 'make it feel good', 'make it satisfying', or 'polish' a button, modal, toast, drawer, toggle, menu, list, or page transition. Works on existing components (improves them in place) or a described interaction (builds it), CSS-first and adapting to the project's stack, with accessibility (prefers-reduced-motion) and performance (compositor-only) built in, and the taste to know when NOT to animate. Trigger phrases: 'make this feel nicer', 'add some juice', 'this feels stiff', 'this feels janky', 'polish this interaction', 'make it satisfying', 'improve the animation', 'it feels cheap', 'make it more delightful', 'give it some life'.

Interaction Polish: the craft of feel

The goal is not "add animations." It is to make an interaction feel considered, responsive, alive, and effortless, the way Emil Kowalski's (sonner, vaul) and Josh Comeau's work feels. Often that means adding one small, well-tuned piece of feedback. Sometimes it means removing animation that's getting in the way. This skill is the taste to tell the difference, plus the concrete technique to execute it well.

"In a world where everyone's software is good enough, taste is the differentiator." (Emil Kowalski)

The one idea: feedback, not decoration

Game designers have a word for this: juice. The same action can feel dead or alive purely from the feedback layered on top, without changing what the action does or slowing the user down. A button that instantly swaps state feels dead; the same button with a 120ms scale-and-spring-back feels alive. In the anatomy of a micro-interaction (Trigger → Rules → Feedback → Loops), juice lives in the feedback layer.

So the operating principle is: add the smallest feedback that confirms the action, and add flourish only at genuine moments (a success, a completion, a first-time delight). Decoration that doesn't answer "did my action register / what changed / where did it go?" is noise.

First, do no harm

The fastest way to make UX worse is to over-animate. Internalize these before touching anything. Most are about restraint, and they're what separate this skill from cargo-cult "add a fade everywhere":

• Never make the user wait. If interaction pauses while motion plays, you've made the app slower. Don't block input on an animation; keep anything on the user's path well under 300ms; prefer non-blocking feedback that the user can interrupt or tap through.
• Frequency-gate every animation. The more often a user triggers an action, the less it should animate. Emil's rule: 100+ times/day (keyboard shortcuts, command palette, core nav) → no animation at all; motion there reads as lag. Tens/day (hovers, list nav) → tiny and fast or none. Occasional (modals, toasts) → standard. Rare/first-time → room for delight. Raycast feeling instant is the goal, not a flourish.
• Every animation needs a job. Spatial continuity, state change, feedback, explanation, or softening a jarring jump. If the only reason is "it looks cool" and the user sees it often, don't.
• Accessibility and performance are not optional. Ship the prefers-reduced-motion path and compositor-only properties by default, not as an afterthought. See references/accessibility-performance.md.
• Delight is rare by nature. A boop, a particle burst, a celebration works because it's uncommon. The litmus test: would this still be charming on the 50th encounter? If no, make it rarer, quieter, or motion-free.

Workflow

1. Read the interaction and its frequency. What is it (button, toggle, modal, drawer, toast, tabs, list, reveal, page transition)? How often will a real user hit it? What does it do now? an instant snap? a transition: all? a slow sluggish fade? The frequency decides how much (or whether) to animate; the current state tells you the highest-leverage fix.

2. Decide what should animate, and what shouldn't. Sometimes the best change is to remove a gratuitous animation or a layout-thrashing one. Pick the 1-3 changes that will move the feel the most rather than touching everything.

3. Apply, CSS-first, in the project's idiom. Default to CSS transitions/animations; they run off the main thread and stay smooth under load. Reach for a spring / JS motion library only when the motion is dynamic, interruptible, or gesture-driven (drag, momentum, physical "alive" elements). Match whatever the codebase already uses (vanilla CSS, Tailwind, Framer Motion / Motion, Vue/Svelte transitions); don't introduce a new dependency unless the interaction genuinely needs it.

4. Make it correct by default. Animate only transform and opacity. Name exact properties (never transition: all). Add the prefers-reduced-motion variant (keep fades, drop movement). Gate hover effects behind (hover: hover).

5. Apply the change AND explain the why. Edit the code, then briefly walk through each change and the principle it serves, so the user gains the taste, not just a diff. Keep explanations tight (a line each). If you removed something, say why that's the improvement.

The core toolkit (condensed, deep tables in references/)

• Easing. ease-out for things entering/exiting (fast start = feels responsive); never ease-in on UI (it delays the moment the user is watching); ease-in-out for things moving across the screen; plain ease is fine for hover color changes; linear only for constant motion (spinners, marquees), never for spatial movement. Built-in curves are weak; prefer a strong custom one like cubic-bezier(0.23, 1, 0.32, 1). Easing is the single highest-leverage variable. Full curves, durations, and spring configs are in references/easing-springs-timing.md.

• Duration. Keep UI under 300ms. Button press 100-160ms · tooltip 125-200ms · dropdown 150-250ms · modal/drawer 200-500ms. Make it asymmetric: respond fast to the user, return to rest a touch slower; generally exits faster than enters.

• The press. Every pressable element should acknowledge touch: :active { transform: scale(0.97) } with a ~150ms ease-out transition. It's the cheapest possible "the UI is listening." Subtle range 0.95-0.98.

• Springs vs. transitions. Springs shine for drag/momentum and "alive" elements because they keep velocity when interrupted: a CSS keyframe restarts from zero, whereas a spring reverses smoothly mid-gesture. Use CSS transitions (not keyframes) for anything retriggered rapidly (toasts, toggles) so it retargets instead of restarting.

• Don't scale from zero. Enter from scale(0.95) + opacity: 0, not scale(0). Real things don't blink in and out of existence.

• Restraint flourishes. The boop (a momentary, self-resetting hover wiggle), particle bursts, confetti, hit-flashes are powerful precisely because they're rare. Recipes in references/patterns.md.

When the input is a description (no code yet)

Build the interaction from scratch applying everything above. Choose the project's stack if one exists; otherwise default to CSS + a minimal motion approach. Produce real, runnable code, not pseudocode, and still explain the choices.

References

Read the relevant one when you need depth; don't load all of them for a small tweak.

• references/easing-springs-timing.md, the easing decision tree, concrete cubic-beziers, the duration table, spring configs (Apple-style & physics), and CSS linear() overshoot for native springs.
• references/patterns.md, per-component recipes: button, toggle, like/favorite, modal, drawer/sheet, toast, tabs, accordion, hover/focus, drag-reorder, loading (optimistic / skeleton), scroll reveal, page transition. Includes the sonner/vaul drag mechanics and Josh's "boop" and "friendly shadow" techniques.
• references/accessibility-performance.md, prefers-reduced-motion (what to keep vs. drop), compositor-only properties, will-change as a scalpel, and the full anti-pattern list.