Subtle Motion
Motion is seasoning. The user should feel the site is "smooth", never notice "an animation". Sources: Disney's The Illusion of Life, Jon Yablonski's Laws of UX, Raphael Salaja's userinterface.wiki, Emil Kowalski (frequency of use).
Hard rules (never break)
- Animate only
transformandopacity(plusfilter/clip-pathsparingly). Never animatewidth,height,top,left,margin,padding,box-shadowsize, orfont-size. Need a shadow change? Fade a pseudo-element'sopacity. - Snappy timing: UI motion under 300ms. Press 80–120ms, hover 150ms, enter 200–300ms, exit ≈ 70% of enter. Only a one-time hero may go to 500ms.
- Small distances. Translate 2–16px, scale 0.97–1.03, rotate ≤ 6°. Bigger reads as "animated".
- Slow in & slow out. Never
linearon movement. Ease-out to enter, ease-in to exit. - Frequency of use: the more often it's used, the less it animates. Keyboard navigation, command palettes, tabs used 100x/day, list selection: instant (0ms) or a ≤100ms fade. Animate first-time and rare moments, not repeated ones.
- Doherty threshold: respond within 100ms, finish within 400ms. Feedback (press state, pending state) starts on the same frame as input. Anything slower than 400ms shows progress.
prefers-reduced-motion: reducekills movement. Opacity fades may stay.- Hover effects only under
@media (hover: hover). Touch gets sticky hovers otherwise. - CSS first, no animation libraries unless the project already has one. No JS loops when CSS can do it.
- Never delay or hide content. Reveals must not hide content if JS fails, block clicks, or animate the LCP element on load.
- Staging: one focal motion at a time. Max ~5 motion touchpoints per page; never two things competing for the eye in the same moment.
will-changeonly during the animation (or on ≤3 persistent elements).- Interruptible by default. State that can flip mid-flight (hover, toggle, open/close, tab indicator) uses
transition, which retargets from wherever it is.@keyframesonly for one-shot moments (shake, ring, send) that restart cleanly. - Scale duration to size and initiator. Small elements faster than big ones (icon 100ms, card 250ms, sheet 300ms). User-initiated = immediate; system-initiated (toast, background update) may take the slow end.
- No flashing more than 3×/s; anything looping > 5s needs a pause control (or don't loop).
The principles, as UI rules
Pick the ones that fit the touchpoint; never all at once. Each maps to a pattern below.
| # | Principle | In UI it means | Pattern |
|---|---|---|---|
| 1 | Squash & stretch | Things squish on impact, stretch in motion: weight | Press, Toggle |
| 2 | Anticipation | Tiny pull-back before a big move (send, submit, fly-out) | Send button |
| 3 | Staging | Direct the eye to one thing: dim siblings, one motion at a time | Card focus |
| 4 | Pose to pose | Define start/end states; let the browser tween | transition, not frame-by-frame JS |
| 5 | Follow through | Parts settle after the body stops (small overshoot) | Toast, Badge |
| 6 | Slow in & slow out | Accelerate and decelerate, never constant speed | Tokens |
| 7 | Arcs | Travelling elements move on curves, not straight lines | Fly-to-cart |
| 8 | Secondary action | Small flourish that backs the main action | Success ring |
| 9 | Snappy timing | Duration sets the feel; UI < 300ms | Tokens |
| 10 | Exaggerated feedback | Push past real so the moment lands (errors, success) | Error shake |
| 11 | Solid drawing / 3D | Give flat things depth and volume | Tilt card |
| 12 | Appeal | The sum of every detail, consistent across the site | Verify pass |
| UX law | Motion consequence | Pattern |
|---|---|---|
| Fitts's law | Bigger, closer targets are faster to hit | Hit areas |
| Bigger hit areas | Clickable area ≥ 44×44px, even if the visual is smaller | Hit areas |
| Hick's law | More choices = slower decisions; don't animate many options at once | Stagger cap |
| Miller's law | Chunk content (~7 items); reveal in groups, not item by item | Stagger cap |
| Doherty threshold | <100ms feedback, <400ms total, else show progress | Pending state |
| Postel's law | Accept messy input, return clean output; animate the clean-up gently | Input format |
| Jakob's law | Use conventional motion (menus drop from trigger, modals fade+scale from center) | Overlay |
| Frequency of use | Frequent = less animation | Rule 5 |
Workflow
- Read the site first. Framework, CSS approach (Tailwind, CSS modules, plain), existing motion and tokens. Reuse them.
- Classify each interactive element by frequency: rare (signup, checkout, success), occasional (cards, sections, modals), frequent (nav, tabs, palettes, list rows). Frequent gets ≤100ms or nothing.
- Pick ≤5 touchpoints, ranked by feel-per-cost:
- Buttons/links: press squash + hit area (principles 1, Fitts)
- Form feedback: error shake, success ring, pending state (10, 8, Doherty)
- Cards: hover lift, optional tilt (11)
- Sections: scroll reveal, chunked stagger (6, Miller)
- Overlays/toasts: enter/exit with follow-through (5, Jakob)
- Add the tokens once, globally.
- Apply patterns to the chosen touchpoints only.
- Verify (last section). Not done until verified.
- Report: each touchpoint with file:line, the principle it applies, and how to see it.
Tokens (add once, globally)
:root {
--ease-out: cubic-bezier(.23, 1, .32, 1); /* enter, hover */
--ease-in: cubic-bezier(.55, 0, 1, .45); /* exit */
--ease-in-out: cubic-bezier(.65, 0, .35, 1); /* move on screen */
--ease-settle: cubic-bezier(.34, 1.4, .64, 1); /* follow-through: ~4% overshoot */
/* spring feel, interruptible; browsers without linear() fall back to `ease` */
--ease-spring: linear(0, .07 3%, .29 9%, .62 18%, .86 28%, 1.01 40%, 1.03 50%, 1.015 65%, 1);
--dur-press: 100ms;
--dur-fast: 150ms;
--dur-base: 250ms;
--dur-slow: 300ms;
--rise: 8px;
}
@media (prefers-reduced-motion: reduce) {
:root { --rise: 0px; }
*, *::before, *::after {
animation-duration: 1ms !important;
animation-iteration-count: 1 !important;
transition-duration: 1ms !important;
scroll-behavior: auto !important;
}
}
Tailwind project? Put these in @theme / tailwind.config extend instead of a new CSS file.
Patterns
Press: squash (1) + hit area (Fitts)
.btn {
position: relative;
transition: transform var(--dur-fast) var(--ease-out), background-color var(--dur-fast) var(--ease-out);
}
@media (hover: hover) { .btn:hover { transform: translateY(-1px); } }
.btn:active { transform: scale(.97); transition-duration: var(--dur-press); }
/* Small icon buttons: grow the hit area, not the visual */
.icon-btn { position: relative; }
.icon-btn::before { content: ""; position: absolute; inset: 50% auto auto 50%; width: 44px; height: 44px; translate: -50% -50%; }
Toggle: squash & stretch (1)
The knob stretches while travelling, settles when it lands.
.switch .knob { transition: transform var(--dur-base) var(--ease-settle); }
.switch[aria-checked="true"] .knob { transform: translateX(20px); }
.switch:active .knob { transform: scaleX(1.2); transform-origin: left; }
.switch[aria-checked="true"]:active .knob { transform: translateX(20px) scaleX(1.2); transform-origin: right; }
Send / submit: anticipation (2)
Only on rare "commit" actions. Pull back 2px, then go.
@keyframes send { 0% { transform: none } 30% { transform: translate(-2px, 2px) } 100% { transform: translate(24px, -24px); opacity: 0 } }
.send.is-sending svg { animation: send 280ms var(--ease-in-out) forwards; }
Card focus: staging (3)
@media (hover: hover) {
.grid:has(.card:hover) .card:not(:hover) { opacity: .6; }
}
.grid .card { transition: opacity var(--dur-base) var(--ease-out); }
Use only on dense grids where one choice matters. Skip on content people read.
Card lift + optional tilt: solid drawing (11)
.card { position: relative; transition: transform var(--dur-base) var(--ease-out); }
.card::after {
content: ""; position: absolute; inset: 0; border-radius: inherit; pointer-events: none;
box-shadow: 0 12px 32px -12px rgb(0 0 0 / .25);
opacity: 0; transition: opacity var(--dur-base) var(--ease-out);
}
@media (hover: hover) {
.card:hover { transform: translateY(-3px); }
.card:hover::after { opacity: 1; }
}
Tilt (only for showcase items like a product, pricing or credit card; ≤6°, pointer only, rAF-throttled):
if (matchMedia('(hover: hover) and (prefers-reduced-motion: no-preference)').matches) {
for (const el of document.querySelectorAll('.tilt')) {
let raf = 0;
el.addEventListener('pointermove', (e) => {
cancelAnimationFrame(raf);
raf = requestAnimationFrame(() => {
const r = el.getBoundingClientRect(); // read once per frame, not per transition
const x = (e.clientX - r.left) / r.width - .5, y = (e.clientY - r.top) / r.height - .5;
el.style.transform = `perspective(800px) rotateX(${-y * 6}deg) rotateY(${x * 6}deg)`;
});
});
el.addEventListener('pointerleave', () => { cancelAnimationFrame(raf); el.style.transform = ''; });
}
}
Toast / badge: follow through (5)
.toast { transition: transform var(--dur-slow) var(--ease-settle), opacity var(--dur-fast) var(--ease-out); }
.toast[data-state="closed"] { transform: translateY(12px); opacity: 0; transition-timing-function: var(--ease-in); }
Overshoot only on things that arrive (toasts, badges, counters), never on layout or text blocks.
Fly-to-cart: arcs (7)
Split X and Y across two nested elements with different easings; the path curves.
.fly-x { transition: transform 300ms linear; }
.fly-y { transition: transform 300ms var(--ease-in); }
.flying .fly-x { transform: translateX(var(--dx)); }
.flying .fly-y { transform: translateY(var(--dy)) scale(.4); }
Set --dx/--dy from one getBoundingClientRect() read before adding .flying.
Success ring: secondary action (8)
.btn.is-success::after {
content: ""; position: absolute; inset: -4px; border-radius: inherit; border: 2px solid currentColor;
animation: ring 400ms var(--ease-out) forwards; pointer-events: none;
}
@keyframes ring { from { opacity: .6; transform: scale(.95) } to { opacity: 0; transform: scale(1.15) } }
Error shake: exaggerated feedback (10)
@keyframes shake { 20%,60% { transform: translateX(-4px) } 40%,80% { transform: translateX(4px) } }
.field[aria-invalid="true"] { animation: shake 280ms var(--ease-in-out); }
Re-trigger by removing and re-adding the attribute. Always pair with a text message (accessibility).
Pending state: Doherty threshold
Press feedback immediately; if the action takes >400ms, show a spinner/progress inside the button (keep its width fixed to avoid layout shift). Prefer optimistic UI: show the result, roll back on error.
Messy input → clean output: Postel's law
Format on blur (phone numbers, card numbers, dates), not on every keystroke. Crossfade the value with a 150ms opacity change, no movement.
Scroll reveal: slow in/out (6) + chunking (Miller, Hick)
Content visible by default; only hidden once JS confirms it can reveal it.
.js .reveal {
opacity: 0; transform: translateY(var(--rise));
transition: opacity var(--dur-slow) var(--ease-out), transform var(--dur-slow) var(--ease-out);
transition-delay: calc(min(var(--i, 0), 5) * 50ms);
}
.js .reveal.in { opacity: 1; transform: none; }
document.documentElement.classList.add('js');
const io = new IntersectionObserver((entries) => {
for (const e of entries) if (e.isIntersecting) { e.target.classList.add('in'); io.unobserve(e.target); }
}, { rootMargin: '0px 0px -10% 0px' });
document.querySelectorAll('.reveal').forEach((el) => io.observe(el));
- Stagger with
style="--i: n"; capped at 6 steps (Miller). Long lists reveal as one group. - Reveal once. Skip anything above the fold.
- Frameworks: same CSS; run the observer in a mount effect, disconnect on unmount.
Overlays: Jakob's law
Conventional motion only: dropdowns grow from their trigger (transform-origin on the trigger side), modals fade + scale 0.98→1 from center, sheets slide from their edge. Native first: <dialog> / popover with @starting-style.
dialog, [popover] {
opacity: 0; transform: translateY(4px) scale(.98);
transition: opacity var(--dur-fast) var(--ease-in), transform var(--dur-fast) var(--ease-in),
overlay var(--dur-fast) allow-discrete, display var(--dur-fast) allow-discrete;
}
dialog[open], [popover]:popover-open {
opacity: 1; transform: none;
transition-timing-function: var(--ease-out); transition-duration: var(--dur-base);
}
@starting-style {
dialog[open], [popover]:popover-open { opacity: 0; transform: translateY(4px) scale(.98); }
}
Command palette / menu opened by keyboard many times a day: frequency of use says skip the transition.
Tabs: folder surface that slides (not an accent underline)
The AI/template tell is the thin accent underline, not the motion. Use a familiar physical shape (Jakob) and let that shape do the moving:
- Folder tabs (preferred): the selected tab's surface merges into the panel and slides to the clicked tab.
- Segmented control: for 2–4 options; the pressed-in segment slides the same way.
Make tabs equal width so the surface only needs translateX (no width or scaleX, which distorts radius and border). Use a ≤150ms transition so it stays interruptible. Content swaps instantly (frequency of use).
.tabs { position: relative; display: flex; gap: 2px; border-bottom: 1px solid var(--line); }
.tabs [role=tab] { position: relative; z-index: 1; flex: 0 0 96px; background: none; border: 0;
transition: color var(--dur-fast) var(--ease-out), transform var(--dur-press) var(--ease-out); }
.tabs [role=tab]:active { transform: translateY(1px); }
.tabs .folder { position: absolute; left: 0; top: 0; bottom: -1px; width: 96px; background: var(--panel-bg);
border: 1px solid var(--line); border-bottom: 0; border-radius: var(--r-ctl) var(--r-ctl) 0 0;
transition: transform var(--dur-fast) var(--ease-out); }
const move = (tab) => folder.style.transform = `translateX(${tab.offsetLeft}px)`; // one read per click
Tab labels too uneven for equal widths? Let the surface jump without animating, and keep only the 1px press. Use View Transitions with a shared view-transition-name only for page-level swaps; they can't be interrupted.
Accordion / height: the one layout exception
Height can't be done with transform. Use native <details> and let the browser interpolate to auto; keep it to small subtrees.
:root { interpolate-size: allow-keywords; }
details::details-content { block-size: 0; overflow: clip; opacity: 0;
transition: block-size var(--dur-base) var(--ease-out), opacity var(--dur-base) var(--ease-out), content-visibility var(--dur-base) allow-discrete; }
details[open]::details-content { block-size: auto; opacity: 1; }
Unsupported browsers just open instantly. Never animate height on large lists or anything that reflows the page under the cursor.
Multi-step flow: directional
Steps slide in from the direction of travel (forward = from the right, back = from the left), 12px, with a crossfade. Spatial consistency tells the user where they are.
.step { transition: opacity var(--dur-base) var(--ease-out), transform var(--dur-base) var(--ease-out); }
.step[data-from="next"] { opacity: 0; transform: translateX(12px); }
.step[data-from="prev"] { opacity: 0; transform: translateX(-12px); }
Toast stack: system-initiated
Stack with an index variable; older toasts scale down and tuck behind. Pure transform.
.toast { --i: 0; transform: translateY(calc(var(--i) * -10px)) scale(calc(1 - var(--i) * .05));
transition: transform var(--dur-slow) var(--ease-spring), opacity var(--dur-fast) var(--ease-out); }
.toasts .toast:nth-last-child(n+4) { opacity: 0; } /* max 3 visible (Miller); set --i = distance from newest */
Focus
:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; transition: outline-offset var(--dur-fast) var(--ease-out); }
Page transitions (only if asked)
View Transitions API (@view-transition { navigation: auto; } for MPAs, document.startViewTransition for SPAs). Default crossfade, ≤200ms, feature-detect.
If the project already uses Framer Motion / Motion
Don't add CSS duplicates; map the tokens:
const easeOut = [.23, 1, .32, 1];
const snappy = { type: "spring", stiffness: 400, damping: 30 }; // UI chrome, interruptible
const gentle = { type: "spring", stiffness: 200, damping: 22 }; // larger surfaces
<MotionConfig reducedMotion="user">{app}</MotionConfig> // respects the OS setting
AnimatePresence for exits, layoutId for shared elements, layout for reflow. Same rules: small distances, < 300ms, no bouncy springs (damping < 20) on chrome.
Performance guardrails
- 50+ animated items?
content-visibility: autoon sections; reveal containers, not items. - Scroll-linked effects: CSS
animation-timeline: view()/scroll()inside@supports. Neverscrolllisteners that write styles. Parallax is rarely subtle; ask first. - Never read layout inside an animation path (only once before it starts, as in fly-to-cart).
- No
backdrop-filter: blur()on animated elements.
Verify (required)
- Reduced motion: DevTools > Rendering > emulate
prefers-reduced-motion: reduce. Nothing moves. - Jank: DevTools > Performance, 4x CPU throttle, scroll and hover the touchpoints. No "Layout" during hover/reveal, no long frames. Rendering > Paint flashing: only the animated element should flash. 2b. Slow-mo: DevTools > Animations panel at 10% speed. Check each curve, overshoot and stagger frame by frame; interrupt hover/toggle mid-flight and confirm it reverses smoothly.
- Doherty: every click shows feedback in the same frame; nothing UI-level runs past 300ms.
- Touch: device toolbar on, tap buttons/cards. No stuck hover; hit areas ≥ 44px.
- No JS: disable JS, reload. All content visible.
- Lighthouse mobile: CLS ≈ 0, LCP not worse than before.
- Appeal pass (12): same easing and duration family everywhere; nothing moves that a user does 10x a minute.
If agent-browser is available, run 1, 4 and 5 with it and screenshot. Otherwise list the steps for the user.
Anti-patterns (remove if found)
transition: all, or animations on every element- Whole-page fade-in on load
- Bounce/elastic on buttons or text, typing effects, infinite pulses on CTAs
- Animated keyboard navigation / tab switches (frequency of use)
- Hover-only affordances with no touch equivalent
- A colored bar down the left edge of the selected/active row (palette, sidebar, list). Use a plain background fill and ink-colored text instead.
- A thin accent underline gliding under tabs. Slide a folder or segmented surface instead.
- AOS/WOW/GSAP added just for fade-ups