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.
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.
| Token | Value | Use for | Tailwind class |
|---|---|---|---|
| --ease-out | cubic-bezier(0.23, 1, 0.32, 1) | Enter and exit of components | ease-out |
| --ease-in-out | cubic-bezier(0.77, 0, 0.175, 1) | Movement of something already on screen | ease-in-out |
| --ease-drawer | cubic-bezier(0.32, 0.72, 0, 1) | Edge-mounted surfaces: Sidebar, drawers, sheets | ease-drawer |
| --ease-standard | cubic-bezier(0.2, 0, 0, 1) | Most state changes in data-motion | CSS variable only |
| --ease-in | cubic-bezier(0.4, 0, 1, 1) | Exits in data-motion | CSS variable only |
| --ease-overshoot | cubic-bezier(0.34, 1.56, 0.64, 1) | A small pop in data-motion | CSS 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.
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.
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.
| Utility | Purpose | Duration | Easing |
|---|---|---|---|
| .animate-rise | Popover, tooltip, hover card enter; exits when data-state="closed" | --dur-fast in, --dur-instant out | --ease-out |
| .animate-rise-fast | Quick tooltip reopen | --dur-instant | --ease-out |
| .animate-modal-in | Dialog enter (scale and fade) | --dur-base | --ease-out |
| .animate-modal-wrap | Dialog exit when data-state="closed" | --dur-fast | --ease-out |
| .animate-overlay | Dialog and Spotlight backdrop fade | --dur-base in, --dur-fast out | ease |
| .animate-drawer-right-in | Drawer enter from the right | --dur-slow | --ease-drawer |
| .animate-drawer-left-in | Drawer enter from the left | --dur-slow | --ease-drawer |
| .animate-drawer-exit | Drawer exit, by data-side | --dur-slow | --ease-drawer |
| .animate-accordion-down | Accordion expand | --dur-base | --ease-out |
| .animate-accordion-up | Accordion collapse | --dur-base × 0.8 | --ease-out |
| .animate-progress-indeterminate | Indeterminate progress bar loop | 1.4s loop | ease-in-out |
| .animate-pulse-dot | Pulsing dots for inline loading | 1.2s loop | ease-in-out |
| .animate-caret-blink | Text caret blink | 1s loop | steps(2, start) |
| .animate-mesh-drift | Animated mesh backgrounds; stops under reduced motion | loop | — |
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-upfade-downscale-inblur-inmask-upfadeDistance, 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.
<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.
| Surface | Duration | Notes |
|---|---|---|
| Press feedback | var(--dur-instant) | 100ms. Also floating-panel exits. |
| Hover, tooltip, popover, menu | var(--dur-fast) | 160ms. .animate-rise and modal exits. |
| State changes and modals | var(--dur-base) | 240ms. Tabs, accordions, dialog enter. |
| Large surfaces | var(--dur-slow) | 400ms. Sidebar collapse, drawers, sheets. |
| Entrances and reveals | var(--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
Distance tokens
Stagger token
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-entryand 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;
}
}