Skip to content

Motion

How it is organised

Motion has two layers, like colour and radius. Foundation tokens are the easing curves, durations, distances and stagger interval. Animation utilities (.animate-*) combine a keyframe, a duration and a curve for a specific component. Use a utility when one fits; use the tokens (or the duration-* and ease-* Tailwind classes) for your own transitions.

6 easings5 durations4 distances1 stagger14 .animate-* utilities

Easing tokens

Six curves ship in global.css. The first three are also Tailwind classes. The other three are CSS variables only; use them as var(--ease-standard) or through the data-motion-entry-ease attribute.

TokenValueUse forTailwind class
--ease-outcubic-bezier(0.23, 1, 0.32, 1)Enter and exit of componentsease-out
--ease-in-outcubic-bezier(0.77, 0, 0.175, 1)Movement of something already on screenease-in-out
--ease-drawercubic-bezier(0.32, 0.72, 0, 1)Edge-mounted surfaces: Sidebar, drawers, sheetsease-drawer
--ease-standardcubic-bezier(0.2, 0, 0, 1)Most state changes in data-motionCSS variable only
--ease-incubic-bezier(0.4, 0, 1, 1)Exits in data-motionCSS variable only
--ease-overshootcubic-bezier(0.34, 1.56, 0.64, 1)A small pop in data-motionCSS variable only

The gallery below compares the three Tailwind curves with common alternatives. Click a thumbnail to replay it, change the duration and copy the CSS. Curves marked DS are Shavin tokens. linear is there as a baseline, not for UI motion.

ease-out
cubic-bezier(0.23, 1, 0.32, 1)
Preview
Duration
transition: transform 1200ms var(--ease-out);

Principles

Animate transform and opacity

Browsers can composite these without layout or paint. Animating width, height, top or margin forces layout on every frame and drops frames.

Ease-out to enter

Entering elements should start fast and settle. Ease-in delays the first frames, which is when the eye is watching, so it feels slow at the same duration. --ease-in is only offered for exits in data-motion; component exits use --ease-out.

Pick the curve before the duration

A good curve at 200ms beats a linear tween at any length. Start from --ease-out, --ease-in-out or --ease-drawer before changing the number.

Exit faster than enter

The user has already decided to dismiss. Most component exits run one step shorter than their entrance: a dialog opens in 240ms and closes in 160ms; a popover opens in 160ms and closes in 100ms.

Motion must be interruptible

A user can reopen what they just closed. Animations should start from the current state, not wait for the last one to finish.

Animate from the origin

Popovers rise from the side of their trigger; modals scale from the center. Motion that starts where the eye already is reads as cause and effect.

Give every animation a job

Feedback, guiding attention, or showing how two states relate. If an animation does none of these, remove it.

Respect reduced motion

Under prefers-reduced-motion the duration, distance and stagger tokens drop to zero, so token-driven motion becomes instant. Loading loops such as the spinner and skeleton keep running.

Buttons scale to 0.97 while pressed.

Animation utilities

Each class combines a keyframe, a duration and a curve. Shavin components already use them; reach for one before writing your own animation declaration.

UtilityPurposeDurationEasing
.animate-risePopover, tooltip, hover card enter; exits when data-state="closed"--dur-fast in, --dur-instant out--ease-out
.animate-rise-fastQuick tooltip reopen--dur-instant--ease-out
.animate-modal-inDialog enter (scale and fade)--dur-base--ease-out
.animate-modal-wrapDialog exit when data-state="closed"--dur-fast--ease-out
.animate-overlayDialog and Spotlight backdrop fade--dur-base in, --dur-fast outease
.animate-drawer-right-inDrawer enter from the right--dur-slow--ease-drawer
.animate-drawer-left-inDrawer enter from the left--dur-slow--ease-drawer
.animate-drawer-exitDrawer exit, by data-side--dur-slow--ease-drawer
.animate-accordion-downAccordion expand--dur-base--ease-out
.animate-accordion-upAccordion collapse--dur-base × 0.8--ease-out
.animate-progress-indeterminateIndeterminate progress bar loop1.4s loopease-in-out
.animate-pulse-dotPulsing dots for inline loading1.2s loopease-in-out
.animate-caret-blinkText caret blink1s loopsteps(2, start)
.animate-mesh-driftAnimated mesh backgrounds; stops under reduced motionloop—

Scroll and entrance motion

Importing from @shavin/ui starts the motion runtime. Add a data-motion-entry attribute and the element animates in when it scrolls into view. Hover a tile to replay its preset. Under reduced motion these animations are turned off.

fade-up
fade-down
scale-in
blur-in
mask-up
fade

Distance, duration and easing

dist="lg"
dur="slow"
ease="overshoot"

Parallax

A CSS-only drift as the element moves through the viewport. Scroll the page to see it. scrub and pin need the optional gsap peer dependency and do nothing without it.

I drift with page scroll
<Card data-motion-entry="fade-up" />                      {/* presets: fade · fade-up · fade-down · scale-in · blur-in · mask-up */}
<Grid data-motion-entry-stagger="1">…</Grid>              {/* tune with -dist (xs–lg) -dur (instant–enter) -ease (standard · out · in · overshoot) */}
<Image data-motion-scroll="parallax" src="…" />          {/* parallax (CSS); scrub/pin need gsap */}

Durations

The more often a surface is seen, the faster it should animate. Hovers, menus and tabs stay under 300ms. Large surfaces that travel a long way (sidebar, drawers) use 400ms, and one-off entrances use 560ms.

SurfaceDurationNotes
Press feedbackvar(--dur-instant)100ms. Also floating-panel exits.
Hover, tooltip, popover, menuvar(--dur-fast)160ms. .animate-rise and modal exits.
State changes and modalsvar(--dur-base)240ms. Tabs, accordions, dialog enter.
Large surfacesvar(--dur-slow)400ms. Sidebar collapse, drawers, sheets.
Entrances and revealsvar(--dur-enter)560ms. data-motion-entry default.

Duration, distance and stagger tokens

The animation utilities and data-motion presets read these tokens. Use them instead of hard-coded ms or px values. All of them are set to zero under reduced motion.

Duration tokens

--dur-instant100ms
--dur-fast160ms
--dur-base240ms
--dur-slow400ms
--dur-enter560ms

Distance tokens

--dist-xs4px
--dist-sm8px
--dist-md16px
--dist-lg24px

Stagger token

--stagger60ms

Interval between sequentially revealed elements. Multiply by index: calc(var(--stagger) * N)

Tailwind utilities: duration-instant, duration-fast, duration-base, duration-slow, duration-enter, paired with ease-out, ease-in-out or ease-drawer.

Reduced motion

When the user asks for reduced motion, Shavin removes movement and keeps feedback:

  • Duration and stagger tokens become 0ms and distance tokens become 0px, so anything built on them happens instantly.
  • Popover, tooltip, dialog and drawer animations switch to an opacity-only fade on --dur-instant, which is also 0ms, so they appear and disappear without moving.
  • All CSS transitions are cut to 0.01ms, and data-motion-entry and parallax animations are turned off.
  • Loading loops with fixed durations (spinner, skeleton, progress bar, pulsing dots, caret) keep running. The decorative mesh drift stops.

Components need no extra code for this. The two main rules in global.css:

@media (prefers-reduced-motion: reduce) {
  :root {
    --dur-instant: 0ms; --dur-fast: 0ms; --dur-base: 0ms;
    --dur-slow: 0ms; --dur-enter: 0ms; --stagger: 0ms;
    --dist-xs: 0px; --dist-sm: 0px; --dist-md: 0px; --dist-lg: 0px;
  }
}

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}
Configure Theme
Theme
Brand Color
Custom
Gray Family
Appearance
Radius
Scaling
Panel Style
Heading Font
Body Font