Appearance
Motion
Animation in an admin panel is a functional tool. Every rule here exists to keep it that way.
The three questions
An animation ships only if it answers one of these:
- Where did this come from / where is it going? — spatial continuity
- What changed? — directing attention to a state change
- Is the system working? — communicating progress
If it answers none, it is deleted. "It looks nice" is not an answer.
Duration tokens
| Token | Value | Use |
|---|---|---|
--av-duration-instant | 0ms | Reduced-motion replacement |
--av-duration-fastest | 80ms | Colour changes, tooltip fade-in |
--av-duration-fast | 140ms | Hover, focus, small state changes |
--av-duration-normal | 220ms | Default — dropdowns, accordions, tabs |
--av-duration-slow | 320ms | Modals, drawers, page transitions |
--av-duration-slower | 480ms | Large-surface entrances, onboarding |
Choosing a duration
Perceived speed scales with distance travelled, not with importance.
Distance Duration
< 40px 80–140ms
40–200px 140–220ms
200–600px 220–320ms
Full viewport 320–480msImportant — anything over 500 ms feels broken in an interface used all day. Marketing sites can afford 800 ms hero animations; an admin panel cannot.
Exits are faster than entrances. The user has already decided to dismiss; make it get out of the way.
scss
.av-drawer {
transition: translate var(--av-duration-slow) var(--av-ease-decelerate); /* in */
&:not(.is-open) {
transition-duration: var(--av-duration-normal);
transition-timing-function: var(--av-ease-accelerate); /* out */
}
}Easing tokens
| Token | Curve | Use |
|---|---|---|
--av-ease-linear | linear | Continuous motion only — spinners, progress bars |
--av-ease-standard | cubic-bezier(.2, 0, 0, 1) | Default — movement within the viewport |
--av-ease-decelerate | cubic-bezier(0, 0, 0, 1) | Entering the screen |
--av-ease-accelerate | cubic-bezier(.3, 0, 1, 1) | Leaving the screen |
--av-ease-emphasized | cubic-bezier(.2, 0, 0, 1) | Large, important transitions |
--av-ease-spring | linear(0, .68 28%, 1.03 46%, .995 70%, 1) | Playful confirmations only |
ease-in-out is never used. It is slow at both ends, which makes short animations feel sluggish and long ones feel floaty.
The spring is a CSS linear() easing — a real spring curve with no JS. It overshoots to 1.03 then settles, giving a subtle bounce. Reserve it for success confirmations and toggle switches.
What can be animated
Only properties the compositor can handle without layout or paint:
| ✅ Compositor-only | ❌ Triggers layout | ❌ Triggers paint |
|---|---|---|
transform / translate / scale / rotate | width, height | background-color * |
opacity | top, left, right, bottom | color * |
filter | margin, padding | box-shadow * |
backdrop-filter | border-width | border-color * |
font-size |
* Paint-only properties are acceptable for small elements over short durations — a button's background on hover is fine. They are unacceptable on large surfaces or in long lists.
scss
/* ❌ Layout thrash on every frame */
.av-panel { transition: height var(--av-duration-normal); }
/* ✅ Composited */
.av-panel {
transition: grid-template-rows var(--av-duration-normal) var(--av-ease-standard);
display: grid;
grid-template-rows: 0fr;
> * { overflow: hidden; }
&.is-open { grid-template-rows: 1fr; }
}The grid-template-rows: 0fr → 1fr technique animates to auto height without JS measurement. It is the correct modern solution to the "animate to height: auto" problem.
Reduced motion
prefers-reduced-motion: reduce is respected everywhere. It is not a global "animations off" switch — that removes useful feedback. It removes motion, keeping opacity and colour.
scss
// src/scss/base/_motion.scss
@media (prefers-reduced-motion: reduce) {
*,
*::before,
*::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
scroll-behavior: auto !important;
}
/* Keep opacity feedback — it is not vestibular-triggering */
.av-fade,
.modal.fade,
.toast.fade {
transition: opacity 120ms linear !important;
}
}In JavaScript:
js
// src/js/utils/motion.js
export const prefersReducedMotion = () =>
matchMedia('(prefers-reduced-motion: reduce)').matches;
export function animate(el, keyframes, options = {}) {
if (prefersReducedMotion()) {
// Jump to the final state rather than skipping the change entirely
Object.assign(el.style, keyframes.at(-1));
return { finished: Promise.resolve() };
}
return el.animate(keyframes, {
duration: 220,
easing: 'cubic-bezier(.2,0,0,1)',
fill: 'both',
...options
});
}There is also a user-level override in the Customizer, which sets data-av-motion="off|reduced|full" so users can opt out without changing their OS setting.
Motion One
The base animation primitive: a 2.6 KB wrapper over the Web Animations API. Hardware-accelerated by default, no JS running per frame.
js
import { animate, stagger, spring } from '@vendor/motion';
// Simple
animate('.av-card', { opacity: [0, 1], y: [12, 0] }, { duration: 0.22 });
// Staggered list entrance
animate(
'.av-list__item',
{ opacity: [0, 1], transform: ['translateY(8px)', 'none'] },
{ delay: stagger(0.04), duration: 0.24, easing: [.2, 0, 0, 1] }
);
// Spring
animate('.av-toggle__thumb', { x: 20 }, { easing: spring({ stiffness: 320, damping: 24 }) });Use GSAP only when Motion One cannot do it: complex timelines, scroll-driven sequences, SVG path morphing, or motion along a path. See Animation.
The motion patterns
1. Entrance — fade + small rise
scss
@keyframes av-enter {
from { opacity: 0; transform: translateY(8px); }
to { opacity: 1; transform: none; }
}
.av-enter {
animation: av-enter var(--av-duration-normal) var(--av-ease-decelerate) both;
}8px, not 40px. A large travel distance draws attention to the animation instead of the content.
2. Staggered lists
scss
.av-stagger > * {
animation: av-enter var(--av-duration-normal) var(--av-ease-decelerate) both;
animation-delay: calc(var(--av-stagger-index, 0) * 40ms);
}js
el.querySelectorAll('.av-stagger > *')
.forEach((child, i) => child.style.setProperty('--av-stagger-index', Math.min(i, 12)));Capped at 12 — beyond that the last items feel unresponsive.
3. Scroll reveal
AOS is not used. Add data-av-reveal (or data-av-reveal="left") to an element:
html
<section class="av-card" data-av-reveal>…</section>The runtime hides only elements that start below the fold — by setting data-av-reveal-state="hidden" — and an IntersectionObserver removes the attribute as each one scrolls into view, which plays a fade and a short slide. Anything already on screen at load is left alone, and under reduced motion no observer is created at all, so content is never stuck hidden.
Warning — never apply scroll reveal to content above the fold. It delays LCP and looks broken when the page loads already scrolled.
4. Skeleton loading
scss
.av-skeleton {
--av-skeleton-base: var(--av-surface-sunken);
--av-skeleton-shine: oklch(from var(--av-surface-raised) l c h / .6);
background: linear-gradient(90deg,
var(--av-skeleton-base) 25%,
var(--av-skeleton-shine) 50%,
var(--av-skeleton-base) 75%);
background-size: 200% 100%;
border-radius: var(--av-radius-sm);
animation: av-shimmer 1.6s var(--av-ease-linear) infinite;
}
@keyframes av-shimmer {
from { background-position: 200% 0; }
to { background-position: -200% 0; }
}
@media (prefers-reduced-motion: reduce) {
.av-skeleton { animation: none; background: var(--av-skeleton-base); }
}The skeleton must match the shape of the real content — same number of lines, same widths, same avatar size. A skeleton that does not match causes a jarring shift on load.
5. Number count-up
html
<span data-av-countup="48210" data-av-countup-currency="EUR">€48,210</span>
<span data-av-countup="98.6" data-av-countup-decimals="1">98.6</span>The server-rendered text is the real value, so the number is right with JavaScript off. The runtime counts from data-av-countup-from (default 0) to data-av-countup over data-av-countup-duration ms (default 900) when it scrolls into view, formatting through Intl.NumberFormat. Under reduced motion it writes the final value immediately.
6. Optimistic feedback
The interface responds to the click, not to the server.
js
async function toggleFavourite(btn, id) {
const wasActive = btn.classList.contains('is-active');
btn.classList.toggle('is-active'); // immediate — 0ms
btn.setAttribute('aria-pressed', String(!wasActive));
animate(btn.querySelector('.av-icon'),
{ scale: [1, 1.35, 1] },
{ duration: 0.32, easing: [.2, 0, 0, 1] });
try {
await fetch(`/api/favourites/${id}`, { method: wasActive ? 'DELETE' : 'POST' });
} catch {
btn.classList.toggle('is-active'); // revert
btn.setAttribute('aria-pressed', String(wasActive));
AdminVora.toast.error('Could not save. Please try again.');
}
}7. View transitions
Page-to-page navigation is animated out of the box. layout/_shell.scss opts every same-origin link into a cross-document view transition: the old content fades out, the new content fades in with a short rise, and the sidebar and topbar hold still. Browsers without cross-document view transitions load the next page as before.
scss
@view-transition { navigation: auto; }
.av-shell > .av-sidebar { view-transition-name: av-sidebar; }
.av-main > .av-topbar { view-transition-name: av-topbar; }
.av-main > .av-content { view-transition-name: av-content; }Put the opt-in inline in your page's <head> too, before the stylesheets:
html
<style>@view-transition { navigation: auto; }</style>Edge decides whether to animate before a large stylesheet has finished loading, so with only the copy in adminvora.css it skips some navigations. The demo pages carry the inline copy in their shared head.
The durations are --av-duration-fast and --av-duration-normal, so the motion axis and prefers-reduced-motion turn the transition off with everything else. A name may belong to one element per page; if your own markup reuses av-sidebar, av-topbar or av-content as a view-transition-name, the browser skips the transition.
Choreography
When multiple things animate together, they must feel like one event.
Rules
- One duration per event. Do not animate the backdrop over 300 ms and the modal over 200 ms.
- Stagger with intent. 30–50 ms between items. More reads as lag.
- Origin matters. A dropdown scales from the trigger's corner (
transform-origin: top left), a drawer slides from the edge it lives on. - Reverse the order on exit. Last in, first out.
scss
/* Modal: backdrop and dialog share the event, dialog leads slightly */
.modal-backdrop.fade { transition: opacity var(--av-duration-normal) var(--av-ease-standard); }
.modal.fade .modal-dialog {
transition: transform var(--av-duration-normal) var(--av-ease-decelerate),
opacity var(--av-duration-fast) var(--av-ease-standard);
transform: translateY(-12px) scale(.98);
}
.modal.show .modal-dialog { transform: none; }Performance rules
| Rule | Reason |
|---|---|
| Never animate more than ~12 elements at once | Each is a composited layer; memory and paint cost |
will-change only during the animation, removed after | Permanent hints waste GPU memory |
| Use CSS animations over JS where possible | They run off the main thread |
Throttle pointer-driven effects with requestAnimationFrame | pointermove fires far above 60 Hz |
Avoid animating inside a position: fixed blur | Forces a re-blur every frame |
| Never animate an element containing an iframe or canvas | Forces expensive re-rasterisation |
js
// The will-change pattern
el.style.willChange = 'transform';
const anim = animate(el, { x: 100 });
anim.finished.finally(() => { el.style.willChange = ''; });Testing motion
js
// tests/e2e/motion.spec.js
test('respects prefers-reduced-motion', async ({ page }) => {
await page.emulateMedia({ reducedMotion: 'reduce' });
await page.goto('/dashboard');
const durations = await page.$$eval('*', (els) =>
els.map((el) => getComputedStyle(el).transitionDuration)
.filter((d) => d !== '0s' && parseFloat(d) > 0.05));
expect(durations).toHaveLength(0);
});
test('no animation exceeds 500ms', async ({ page }) => {
await page.goto('/dashboard');
const slow = await page.$$eval('*', (els) => els
.map((el) => ({ sel: el.className, d: parseFloat(getComputedStyle(el).animationDuration) }))
.filter((x) => x.d > 0.5));
expect(slow).toHaveLength(0);
});Read next: Iconography.