A CV site is a strange thing to over-engineer. Most visitors stay for under a minute. That is exactly why I spent so much time on how mine moves: in a short visit, the feel of the interface is part of the message. A button that gives under your finger and springs back, or a menu selection that glides instead of flickering, says "someone cared" faster than any paragraph.
My thesis: an interface should behave like a small physical world with one set of rules. One material, one gravity, one press, one spring. Those rules should be written down as tokens, checked by the build, and switched off as a set when the user asks for less motion.
This is how I did that on my CV site (live, source), a prerendered Angular 22 app with signals and no zone.js. It covers what research and platform guidelines say, what I took from them, where I deviated, the easter eggs I added on purpose, and the bugs that taught me the most.
TL;DR
- One material. Every duration, curve, radius and state colour is a CSS custom property. A Node script fails the build when a component uses a raw number of milliseconds or a hand-mixed hover colour.
- Springs without JavaScript. A damped spring is sampled into a CSS
linear()easing. A little bounce for small things, a no-overshoot variant meant for size and layout, no bounce at all on exits. - Feedback timing follows the research. A press responds within 80 ms, tooltips wait 400 ms and then "warm up", exits are shorter than entrances, and a navigation jump glides once instead of hopping through every section.
- Scroll-driven choreography in CSS.
animation-timeline: view()with the easing inside the keyframe. One scroll-derived number,--p, drives three elements of the header hand-over. - Reduced motion removes movement as a set, because every movement duration token goes to zero. The figure, the confetti and the pointer effects are not mounted at all.
- The easter eggs are deliberate. They form a discoverable second layer: never required, hidden from assistive tech, off under reduced motion, no data collected. The reasoning draws on the peak–end rule. It is design intent, not a measured result.
- The engineering keeps it sustainable. Pure TypeScript logic at 100 % coverage, a thin rendering layer, 220 unit and 114 end-to-end tests, axe, a strict CSP with build-time script hashes, and a Lighthouse gate.
1. One material: tokens, and a build that enforces them
The first decision was to think in kinds of motion rather than milliseconds: a press, a short state change, a medium move, a ring spreading out, something big arriving, a playful flourish. Each kind gets one token:
// app/src/styles/_tokens.scss (trimmed) // Spring: stiffness 220, damping 22, mass 1 (about 3 % overshoot), sampled for linear(). --ease-spring: linear(0, 0.049, 0.164, 0.308, 0.458, 0.597, 0.717, 0.815, 0.891, 0.947, 0.985, 1.009, 1.023, 1.03, 1.031, 1.029, 1.025, 1.02, 1.016, 1.012, 1.008, 1.005, 1.003, 1.001, 1); --ease-out: cubic-bezier(0.22, 1, 0.36, 1); /* entering */ --ease-in: cubic-bezier(0.3, 0, 0.8, 0.15); /* leaving: the exit is quicker than the entrance */ --ease-in-out: cubic-bezier(0.2, 0, 0, 1); /* a move across the screen, and loops */ --ease-spring-smooth: linear(0, 0.079, 0.236, /* … */ 0.998, 1); /* no overshoot: size, layout, big surfaces */ --dur-tap: 80ms; /* a press goes in within a tenth of a second */ --dur-fade: 200ms; /* opacity and colour only */ --press-scale: 0.96; --tip-delay: 400ms; --dur-press: 150ms; --dur-short: 250ms; --dur-med: 400ms; --dur-ring: 600ms; --dur-long: 700ms; --dur-play: 900ms; The curves are borrowed. --ease-in-out is Material 3's emphasized cubic-bezier(.2, 0, 0, 1) and --ease-in is its emphasized accelerate (.3, 0, .8, .15), from the material-web motion tokens. The durations sit on Material's 50 ms grid but use fewer steps: six are easy to choose between, sixteen are not.
Tokens only help if they are used, so scripts/check-design.mjs fails the build when:
- a corner radius above 6 px is not a token (or a full round),
- a
transitionduration is a number rather than a--dur-*token, - an animation under one second is not a token (long and endless ones are allowed),
- a hover, pressed, selected or current state is painted with an on-the-spot
color-mix()instead of a--tint-*token.
The transition rule is the interesting one. It has to tell a duration apart from a delay:
// app/scripts/check-design.mjs (trimmed) for (const m of text.matchAll(/(?<![\w-])transition:\s*([^;}]*)/g)) { // each property's first time is its duration (a second one is a delay): it must be a token, not a number for (const item of m[1].split(/,(?![^(]*\))/)) { const first = item.match(/(\d*\.?\d+m?s)|var\(--(?:dur|lag|lead)[^)]*\)|calc\([^)]*\)/); if (first?.[1]) at(m.index, 'duration', `"transition: ${item.trim().slice(0, 60)}" … use a --dur-* token`); } } left var(--lag) var(--ease-spring) 90ms passes (the 90 ms is a delay) and opacity 200ms ease fails. It is a regex linter, not a CSS parser, and it has still caught me several times.
2. The physics
Springs in CSS with linear()
linear() takes a list of progress points and connects them with straight segments. MDN points out that with enough points it approximates any curve, and the values may go above 1, which is all an overshoot needs. I simulated a damped spring once (stiffness 220, damping 22, mass 1) and pasted 25 samples into the token.
The numbers behind it: the damping ratio is ζ = 22 / (2·√220) ≈ 0.74, and the overshoot of an underdamped spring with that ratio is about e^(−ζπ/√(1−ζ²)) ≈ 3 %. You can read that off the curve, which peaks at 1.031.
Is 3 % right? Apple's WWDC23 session Animate with springs describes a spring by duration (pacing) and bounce. Bounce 0 is the default ("a great general purpose spring"), around 15 % "doesn't feel very bouncy yet" but brisker, 30 % gives "noticeable bounciness", and above about 0.4 "may feel too exaggerated for a UI element". Apple's bounce is not my damping ratio, so I don't claim an exact mapping. My spring is gentle and reserved for small things: a press releasing, a chip label flipping, the menu pill, a commit dot growing. Anything that changes size or layout should get --ease-spring-smooth (no overshoot) or an ease-out, because bouncing layout makes text wobble. That is Apple's zero-bounce default where it matters.
linear() is a shape, not a time, so the duration is chosen per use: 250 ms for a press release, 400 ms for the menu pill. Pacing first, then bounce, as the talk suggests.
What CSS springs cannot do is keep velocity. Apple notes that a retargeted spring "uses the velocity it had when it was retargeted". A reversed CSS transition starts again from rest. That is acceptable for a menu pill, and it is one reason the figure in section 5 lives in TypeScript.
Press: in within 80 ms, out with a spring
NN/g's response-time limits (going back to Miller 1968 and Card et al. 1991) say that 0.1 s is "about the limit for having the user feel that the system is reacting instantaneously". NN/g's animation and attention article applies the same number to feedback: the effect "must begin within 0.1 seconds of the initial user action". So the press goes in within --dur-tap (80 ms) with an ease-out, and goes back over 250 ms with the spring:
// app/src/styles/_motion.scss .chip, .btn { transition: scale var(--dur-short) var(--ease-spring), background-color var(--dur-short) var(--ease-out), box-shadow var(--dur-short) var(--ease-out); } .chip:active, .btn:active { scale: var(--press-scale); transition-duration: var(--dur-tap); transition-timing-function: var(--ease-out); } The trick is that the transition declared on the state you are going to wins. Going into :active, the 80 ms ease-out applies. Leaving it, the base rule's 250 ms spring applies. One property, two different physics, no script.
On iOS Safari none of this showed up at first. WebKit bug 138816, filed in 2014, documents that :active on touch only applies when the page has a touch event listener. The fix is one passive no-op listener in home.ts, with a comment explaining why it is there.
Exits are shorter than entrances
NN/g's animation duration guidance says most UI motion belongs in 100–500 ms, that entrances "usually need a subtly longer duration" than exits, that ease-out suits things arriving and ease-in things leaving, and that "completely linear motion looks weird". The role cards in the Experience section follow it with the native ::details-content pseudo-element and interpolate-size:
// app/src/app/sections/experience.ts (styles, trimmed) @media (prefers-reduced-motion: no-preference) { details { interpolate-size: allow-keywords; } details::details-content { /* the state it goes to when closing */ block-size: 0; opacity: 0; overflow: clip; transition: block-size var(--dur-short) var(--ease-in), opacity var(--dur-press) var(--ease-in), content-visibility var(--dur-short) allow-discrete; } details[open]::details-content { /* the state it goes to when opening */ block-size: auto; opacity: 1; transition: block-size var(--dur-med) var(--ease-spring), opacity var(--dur-short) var(--ease-out) 50ms, content-visibility var(--dur-med) allow-discrete; } } Opening takes 400 ms with the spring and a text fade that starts 50 ms late. Closing takes 250 ms with ease-in and no spring. content-visibility … allow-discrete keeps the content painted while it collapses (the MDN ::details-content page shows the same pattern). Browsers without these features simply open the card at once, which is a fine fallback.
Tooltips: a delay, then a warm-up
A tooltip that appears the instant the pointer crosses it turns a row of icons into flicker. NN/g's mega-menu guidance uses a 0.5 s rest before showing hover content. PatternFly defaults to a 300 ms entry delay. I picked 400 ms (--tip-delay). Keyboard focus shows the tip at once, because NN/g's tooltip guidelines warn that hover-only tooltips are inaccessible.
The delay becomes annoying once the reader is looking for tooltips, for example when running along the menu. So core/tips.ts adds a warm-up: once a tip has really been shown (it listens for the animationstart of tip-in), leaving it puts html.tips-warm on the page for 300 ms, and in that window the CSS sets animation-delay: 0s. Escape sets html.tips-off until the pointer or the focus moves. The script only toggles classes. The timing stays in CSS.
A selection pill that travels, stretches and waits
The desktop menu has one selection pill. It is a real element positioned with CSS anchor positioning on whichever link currently holds anchor-name: --nav-target. When the anchor changes, left and right transition. To make it feel like something with mass, the leading edge moves fast with an ease-out and the trailing edge follows with the spring, so the pill stretches in the direction of travel:
// app/src/app/shell/header.ts (styles, trimmed) .links { --lead: calc(var(--dur-short) * 0.75); --lag: var(--dur-med); } .links[data-dir='right'] .sel { transition: left var(--lag) var(--ease-spring) 90ms, right var(--lead) var(--ease-out) 90ms, …; } .links[data-dir='left'] .sel { transition: left var(--lead) var(--ease-out) 90ms, right var(--lag) var(--ease-spring) 90ms, …; } @media (hover: hover) { .links:has(a:hover) a[aria-current]:not(:hover) { anchor-name: none; } .links a:hover { anchor-name: --nav-target; } .links:has(a:hover) .sel { transition-delay: 0s; } } The 90 ms delay is a small piece of hover intent. It applies only on the way back to the current item, so a pointer that crosses the menu's edge for a moment does not send the pill away and back. Following the pointer is immediate. The only script involved sets data-dir.
A navigation jump glides once
Clicking "Contact" in the menu smooth-scrolls past four sections. In the first version the active-section tracker named each of them in turn, and the pill hopped across the whole menu. Accurate, and wrong. holdActive(id) in core/active.ts now names the destination at once and ignores everything in between until scrollend fires, or after 1.2 s if the page didn't have to scroll. The smooth scroll itself is scroll-behavior: smooth in CSS, which reduced motion turns off. No script animates a scroll.
Scroll-driven reveals, with the easing inside the keyframe
Section content settles in as it enters the viewport, using animation-timeline: view(). No IntersectionObserver and no script:
// app/src/styles/_motion.scss @media (prefers-reduced-motion: no-preference) { @supports (animation-timeline: view()) { .reveal { animation: reveal linear both; animation-timeline: view(); animation-range: entry 0% entry 40%; } } } @keyframes reveal { from { transform: translateY(18px); animation-timing-function: var(--ease-out); } to { transform: none; } } On a scroll timeline the animation's own linear is correct, since the element should track the scroll 1:1. But a linear ramp stops dead at the end of its range. An ease-out on the keyframe (it applies from that keyframe to the next) lets the element settle while still being driven by the scroll. It is transform-only, so a contrast audit never catches faded text mid-reveal.
One scroll number, three elements
As you scroll past the hero, the large portrait drains from the top, the header's avatar slot fills from the bottom like a progress bar, and the name is written out beside it. An earlier version flew a cloned image across the page, which meant layout reads every frame, a duplicate image and z-index fights with the glass header. The current version computes one number and lets CSS do the rest:
// app/src/app/shell/avatar-dock.ts (trimmed) const distance = img.getBoundingClientRect().bottom + window.scrollY - slot.getBoundingClientRect().bottom; const raw = distance > 0 ? clamp01(window.scrollY / distance) : 1; const p = reduce.matches ? (raw >= 1 ? 1 : 0) : raw; box?.style.setProperty('--p', p.toFixed(3)); // the hero portrait brand.style.setProperty('--p', p.toFixed(3)); // the header avatar and the name .portrait img { clip-path: inset(calc(var(--p, 0) * 100%) 0 0 0 round var(--radius)); } /* drains */ .fill { clip-path: inset(calc((1 - var(--p, 0)) * 100%) 0 0 0); } /* fills */ .mark { --edge: calc(var(--p, 0) * 140%); /* is written */ mask-image: linear-gradient(90deg, #000 calc(var(--edge) - 40%), transparent var(--edge)); } It runs backwards when you scroll back up. The header image reuses the hero's currentSrc (no second request), nothing reads layout at scrollY === 0, and under reduced motion p simply jumps from 0 to 1.
Time-based easing, not per-frame easing
The animated background draws contour lines with marching squares on a canvas. They drift with the scroll and bend around the pointer. Its first version eased with per-frame factors, t += (goal - t) * 0.12. On a 120 Hz display that runs twice as often and settles twice as fast. The fix is exponential easing with time constants:
// app/src/app/shell/backdrop.ts const dt = Math.min(100, stamp ? now - stamp : 16.7); stamp = now; const ease = (ms: number): number => 1 - Math.exp(-dt / ms); t += (g.t - t) * ease(130); // 0.12 per frame at 60 Hz ≈ a 130 ms time constant bump = { x: bump.x + (aim.x - bump.x) * ease(85), y: …, k: bump.k + (aim.k - bump.k) * ease(200) }; The constants come from the old factors (−16.7 / ln(1 − 0.12) ≈ 130 ms), so 60 Hz looks exactly as before. And the loop stops once everything has settled.
3. What the research says, and what I did with it
Most of these are guidelines or conventions, not controlled studies. The table says which is which.
| Finding | Source (kind) | What I did | Where |
|---|---|---|---|
| 0.1 s feels instantaneous; feedback should start within 0.1 s | NN/g response times (Miller 1968; Card et al. 1991), NN/g animation & attention (guideline) | Press goes in within --dur-tap 80 ms | _tokens.scss, _motion.scss |
| UI motion mostly 100–500 ms; exits shorter than entrances; ease-out in, ease-in out; avoid linear; frequent motion should be subtler | NN/g animation duration (guideline) | Six durations 150–900 ms (900 only for playful one-offs); cards open 400 ms spring, close 250 ms ease-in | _tokens.scss, experience.ts |
| Emphasized / accelerate curves and a duration scale | Material 3 motion tokens (design-system convention) | --ease-in-out and --ease-in copied; durations on Material's 50 ms grid | _tokens.scss |
| Springs by duration + bounce; bounce 0 by default, ~0.15 brisk, ~0.3 noticeable, > 0.4 too much for UI | Apple WWDC23 Animate with springs (platform guidance) | Gentle spring (~3 % overshoot) for small things only; no-overshoot spring for size/layout; none on exits | --ease-spring, --ease-spring-smooth |
| Hover content waits ~0.5 s; tooltips ~300 ms entry delay; tooltips must work with keyboard | NN/g mega menus, PatternFly, NN/g tooltips (guidelines) | 400 ms tip delay, 300 ms warm-up window, instant on focus, Escape hides all | _base.scss, core/tips.ts |
| Motion in the periphery pulls attention; don't animate just because you can | NN/g animation & attention (article) | The hero aurora swings twice and then rests; the backdrop loop stops when settled; no endless loops beside text | hero.ts, backdrop.ts |
| Large-area motion, parallax and scroll-jacking are risky for vestibular disorders; opacity and colour are low-risk | A List Apart, Val Head (expert article) | No parallax, no scroll-jacking; reveals are 14–18 px; reduced motion zeroes every movement token | _motion.scss |
reduce means removing "non-essential movement" | web.dev, Thomas Steiner (documentation) | Decorative motion is not mounted at all under reduce | buddy.ts, confetti.ts, lit.ts |
| Moving content > 5 s in parallel with other content needs pause/stop/hide (AA); interaction-triggered motion can be disabled (AAA) | WCAG 2.2.2, 2.3.3 (standard) | Aurora pauses off-screen and ends after two swings; all interaction motion respects prefers-reduced-motion | hero.ts, everywhere |
iOS :active needs a touch listener | WebKit bug 138816 (bug report) | One passive no-op touchstart | home.ts |
Where I deviated:
- I use bounce at all. Apple's default is zero. I use a little, on small, user-initiated things, where it reads as "this object has mass". I would not defend it on anything big.
- Some motion is longer than 500 ms.
--dur-ring(600),--dur-long(700) and--dur-play(900) exceed NN/g's range. They are used for one-off flourishes, never for something the user waits on. - I have no user research of my own. Everything above was verified by tests and by watching. Nothing was measured with real users.
4. Reduced motion, done as a set
Because every movement uses a token, reduced motion is mostly one rule:
// app/src/styles/_motion.scss @media (prefers-reduced-motion: reduce) { :root { --dur-tap: 0s; --dur-press: 0s; --dur-short: 0s; --dur-med: 0s; --dur-ring: 0s; --dur-long: 0s; --dur-play: 0s; } .chip:active, .btn:active { scale: none; } ::view-transition-group(*), ::view-transition-old(*), ::view-transition-new(*) { animation: none !important; } } Everything that uses a duration token becomes instant. States still change and nothing is left half-animated. On top of that:
- Scroll-driven reveals sit inside
prefers-reduced-motion: no-preference, so they never apply. -
scroll-behaviorgoes back toauto, so menu jumps are instant. - The figure, the confetti, the pointer-lit surfaces and the portrait tilt are not started. Each checks
matchMedia('(prefers-reduced-motion: reduce)')and returns before attaching anything. - The background contour lines are drawn once and stay still. An end-to-end test scrolls and moves the mouse, then compares a checksum of the canvas pixels before and after....
