Appearance
Animation
No animation library is vendored. Motion is CSS transitions and keyframes, one small scroll- reveal module, and the animated-icon set — all of it this repository's own code and the platform's.
The design rules live in Motion. This page covers what runs them, and what you would add if you needed more.
Why there is no motion library
No animation library is vendored.
The reason nothing is vendored is that an admin interface's motion is short, interruptible and mostly state-driven, which CSS already does:
| Need | What runs it here |
|---|---|
| Enter, exit, hover, focus, pressed | CSS transitions on a state class or data-av-state |
| Spinners, pulses, the animated icons | @keyframes, named per partial |
| Reveal on scroll | IntersectionObserver plus one attribute — see below |
| Dialog and drawer exit | The animation waited out with a duration read from getComputedStyle |
| Page-to-page transitions | View Transitions, where the browser supports it |
A timeline library earns its place when you have overlapping, choreographed sequences. Nothing in this product does, and the cost of one is paid on every page whether it is used or not.
Reduced motion
One decision, two triggers, and every reader treats them as one condition:
@media (prefers-reduced-motion: reduce)is the operating-system preference.data-av-motionon<html>, takingofforreduced, is the product's own axis, so a visitor can turn motion down here even when the operating system has not been told to.
The reset in src/scss/utilities/_motion.scss is written once and selected by both, so nothing can answer one and not the other. See User motion preference below for what each reader covers.
There is no duration-scale preference. data-av-duration-scale was documented on this page and has no reader anywhere — an attribute that assigns successfully and changes nothing.
The rule motion code here follows: under reduced motion, jump to the end state, never skip the change. Something still has to move from A to B; it just arrives immediately.
Adding an animation library
If you need choreographed timelines, scroll-driven sequences, SVG path morphing or physics, adding a library is an ordinary integration:
- Vendor it as Asset Vendoring describes — manifest entry,
npm run vendor, commit the checksum. - Add a key to the loader's
VENDORS.check:integrationsreads every fenced sample in this documentation and holds each loader key to that registry, so the key and its documentation have to arrive together. - Put the reduced-motion decision in one wrapper and route every call through it, rather than asking each call site to remember. That is the shape the old page got right even though the file it described did not exist.
- Check the licence before you commit to it. GSAP in particular is not MIT, and its terms depend on what you are building — see Licences for how third-party terms are recorded here.
Scroll reveal
AOS is not vendored. initReveal does the same job in one attribute, and the design is worth reading because the obvious implementation is wrong.
html
<div data-av-reveal>Fades up when scrolled into view</div>
<div data-av-reveal="left">Enters from the inline start</div>
<div data-av-reveal="right">Enters from the inline end</div>Those three are the whole vocabulary: there is no delay, threshold or re-trigger option.
The hidden state is added by JavaScript, not declared in CSS. That is the whole trick. A [data-av-reveal] { opacity: 0 } start state hides the content permanently for anyone without JavaScript — and an admin template is exactly where that matters. Instead the stylesheet only describes the transition, initReveal writes data-av-reveal-state="hidden", and the observer removes it:
scss
[data-av-reveal] {
transition:
opacity var(--av-duration-slow) var(--av-ease-decelerate),
transform var(--av-duration-slow) var(--av-ease-decelerate);
}
[data-av-reveal][data-av-reveal-state='hidden'] {
opacity: 0;
transform: translateY(var(--av-space-4));
}Three further decisions are deliberate:
- An element already in view at load is never hidden first. Hiding it would play a reveal for something the reader is already looking at, and on a short page nothing scrolls afterwards to bring it back.
- Reduced motion skips the observer entirely rather than animating instantly — there is nothing to pay for, and the elements are simply left in their visible state.
- The reveal happens once. The observer unobserves the element on the first intersection, so scrolling back up does not replay it.
transform has no logical form, so the horizontal variants carry their direction in --av-reveal-shift, which the [dir='rtl'] rule flips — the same tactic the sidebar sweep and the auth panel use, and the one lint:css's directional-transform rule exists to enforce.
Lenis smooth scroll (not vendored)
MIT. Not in src/vendor/ and not in the loader.
There is no smooth-scroll module, deliberately.
Disabled by default because hijacking scroll:
- Breaks the OS scroll physics users expect
- Interferes with keyboard Page Down and Space paging
- Confuses screen readers' virtual cursor
- Makes precise scrolling in long tables painful
Appropriate for marketing pages and landing surfaces; wrong for a data-dense admin panel.
js
const lenis = new Lenis({ duration: 1.1, easing: (t) => 1 - Math.pow(1 - t, 3), smoothWheel: true });
if (reducedMotion()) lenis.destroy();
// Must be disabled inside scrollable panels
document.querySelectorAll('[data-lenis-prevent]').forEach((el) => el.setAttribute('data-lenis-prevent', ''));View Transitions
Progressive enhancement — no library required.
scss
@view-transition { navigation: auto; }
::view-transition-old(root) { animation: av-fade-out 90ms var(--av-ease-accelerate); }
::view-transition-new(root) { animation: av-fade-in 180ms var(--av-ease-decelerate); }
/* Persist the shell — only content cross-fades */
.av-sidebar { view-transition-name: av-sidebar; }
.av-topbar { view-transition-name: av-topbar; }
@media (prefers-reduced-motion: reduce) {
::view-transition-old(root), ::view-transition-new(root) { animation: none; }
}js
export function withViewTransition(update) {
if (!document.startViewTransition || reducedMotion()) return update();
return document.startViewTransition(update).finished;
}
// Usage
await withViewTransition(() => { list.innerHTML = newHtml; });Important —
view-transition-namemust be unique per element. Two elements sharing a name throw and abort the transition. When animating list items, generate names per id:style="view-transition-name: order-{{ id }}".
Keyframes, and how they are named
There are 42 @keyframes in src/scss/, and there is no shared animation library among them. An earlier version of this page listed ten generic ones — av-enter, av-exit, av-fade-out, av-scale-in, av-slide-up, av-bounce — of which six do not exist, together with an .av-animate-* utility layer that does not exist either.
@keyframes names are global, so they are named after the partial that owns them. That is a house rule with a reason: a component borrowing av-spin from an unrelated partial breaks silently the day that partial is deleted. So the button's spinner is av-btn-spin, the dialog's are av-dialog-in and av-dialog-out, the toast's are av-toast-in and av-toast-out, the drawer and sheet have their own, the OTP field's failure shake is av-otp-shake, and the sixteen animated-icon motions are all av-ai-*.
Four are deliberately generic, because they genuinely are shared: av-fade-in, av-spin, av-pulse and av-shimmer (the skeleton).
scss
// The shape to copy — in the partial that owns the component, inside its layer.
@layer components {
@keyframes av-otp-shake {
20%, 60% { translate: -4px 0; }
40%, 80% { translate: 4px 0; }
}
}The shake on a failed one-time code is the one place a "decorative" animation earns its keep: it communicates failure faster than the error text is read. It is still inside the global reduced-motion policy, which is the point of having one.
Performance rules
| Rule | Reason |
|---|---|
Animate transform, opacity, filter only | Anything else triggers layout or paint |
| Never more than ~12 elements at once | Each becomes a composited layer |
will-change set before, removed after | Permanent hints waste GPU memory |
| Throttle pointer-driven effects with rAF | pointermove fires far above 60 Hz |
Never animate inside a backdrop-filter element | Forces a re-blur every frame |
| Never animate an element containing an iframe or canvas | Forces re-rasterisation |
| Prefer CSS animations for simple cases | They run off the main thread |
js
el.style.willChange = 'transform';
const anim = animate(el, { x: 100 });
anim.finished.finally(() => { el.style.willChange = ''; });User motion preference
Beyond the operating-system setting, data-av-motion on <html> is the product's own axis:
html
<html data-av-motion="reduced">off and reduced mean the same thing to every reader. full is the default and is read by nothing — the real default is the attribute's absence. The Customizer's "Reduce motion" switch writes reduced when on and full when off, and the boot script restores it from storage before first paint.
Four readers, and they are deliberately one condition rather than four policies:
| Read by | Effect |
|---|---|
src/scss/utilities/_motion.scss | The global reset: transitions and animations collapse to 0.01ms, animation-iteration-count drops to 1, scroll-behavior falls back to auto |
The generated token layer (tokens.css) | --av-duration-* and --av-lift go to zero, so a component stops moving on hover without any rule mentioning motion |
The runtime, alongside prefers-reduced-motion | stillMotion() suppresses JavaScript-driven animation |
src/scss/plugins/_glightbox.scss | The lightbox overlay's transition is collapsed |
The token layer and the global reset overlap on purpose, and the overlap is the interesting part. Because every transition in the product interpolates a --av-duration-* token, zeroing those tokens already stopped every transition — which is why the missing global rule went unnoticed for so long. What it never touched was @keyframes: 34 animation declarations carry their own hard-coded duration and nearly all of them are infinite, so the switch left the skeleton shimmering, the spinners spinning and the auth background drifting. The most conspicuous motion in the product was the motion the control did not reach, and it is the motion a person reaching for that control is most likely reaching for.
0.01ms rather than 0 throughout: a zero-duration animation never fires animationend, and code waiting on that event would wait for ever.
When a component has more to say than "stop"
The global reset is enough for anything whose only motion is a duration. A few components need a resting state as well — the typing dots need an opacity, the drawn icon needs its stroke closed, the cart drawer needs its stagger zeroed — and those rules live with their component. Each one is a place the axis could be forgotten, so they go through one mixin rather than a hand-written media query:
scss
@use '../abstracts/motion' as *;
@layer components {
@include still {
.av-typing-dots i { animation: none; opacity: .6; }
}
}still emits the block twice — once under @media (prefers-reduced-motion: reduce) and once under :is([data-av-motion="reduced"], [data-av-motion="off"]) — so the two triggers cannot drift apart. npm run test:motion compares them element for element and fails if they do.
There is no duration-scale preference and no per-category opt-out. An earlier version of this page printed a reduced rule restricting transitions to opacity and colour, as though it shipped; it did not, and reduced is not a middle setting.
Checklist
- [ ] Every animation answers one of the three questions (origin / change / progress)
- [ ] Durations 80–480 ms; nothing over 500 ms
- [ ] Only compositor-friendly properties animated
- [ ]
prefers-reduced-motionrespected everywhere - [ ] New
@keyframesnamed after the partial that owns them, not borrowed - [ ] Any new
@keyframesis reached by the reset inutilities/_motion.scss— a rule outside the cascade layers, or an animation on a vendor's own element, is not - [ ] A per-component reduced-motion rule uses the
stillmixin, never a bare media query - [ ]
will-changecleaned up after each animation - [ ] View transitions guarded with a feature check
- [ ]
view-transition-namevalues are unique - [ ] Any added library routes every call through one reduced-motion wrapper
Read next: Maps.