Skip to content

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:

NeedWhat runs it here
Enter, exit, hover, focus, pressedCSS transitions on a state class or data-av-state
Spinners, pulses, the animated icons@keyframes, named per partial
Reveal on scrollIntersectionObserver plus one attribute — see below
Dialog and drawer exitThe animation waited out with a duration read from getComputedStyle
Page-to-page transitionsView 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-motion on <html>, taking off or reduced, 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:

  1. Vendor it as Asset Vendoring describes — manifest entry, npm run vendor, commit the checksum.
  2. Add a key to the loader's VENDORS. check:integrations reads every fenced sample in this documentation and holds each loader key to that registry, so the key and its documentation have to arrive together.
  3. 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.
  4. 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-name must 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 ​

RuleReason
Animate transform, opacity, filter onlyAnything else triggers layout or paint
Never more than ~12 elements at onceEach becomes a composited layer
will-change set before, removed afterPermanent hints waste GPU memory
Throttle pointer-driven effects with rAFpointermove fires far above 60 Hz
Never animate inside a backdrop-filter elementForces a re-blur every frame
Never animate an element containing an iframe or canvasForces re-rasterisation
Prefer CSS animations for simple casesThey 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 byEffect
src/scss/utilities/_motion.scssThe 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-motionstillMotion() suppresses JavaScript-driven animation
src/scss/plugins/_glightbox.scssThe 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-motion respected everywhere
  • [ ] New @keyframes named after the partial that owns them, not borrowed
  • [ ] Any new @keyframes is reached by the reset in utilities/_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 still mixin, never a bare media query
  • [ ] will-change cleaned up after each animation
  • [ ] View transitions guarded with a feature check
  • [ ] view-transition-name values are unique
  • [ ] Any added library routes every call through one reduced-motion wrapper

Read next: Maps.

Documentation for @creativeigniter/adminvora