Motion

Motion is CSS-first: plain transition-* classes + Base UI's built-in data-starting-style / data-ending-style transitions for overlays, plus a small set of mount-animation motion-* utilities for state feedback. The JS motion library appears in exactly one sanctioned place — the mirrored lucide-animated icons — and is a real dependency there, not an optional one.

Tokens

• Duration — --duration-fast (150ms), --duration-base (200ms), --duration-slow (300ms)
• Easing — --ease-standard, --ease-emphasized, --ease-exit, --ease-spring (a linear() spring with a tiny ~1.05 overshoot — the arrival/success curve) — bridged from --motion-ease-*

Motion at a glance

The whole vocabulary in plain language — what each animation looks like, where it lives, and how to see it. Everything is deliberately subtle (150–400ms, state-triggered, never on page load) and disappears entirely under OS "Reduce Motion".

Mechanism matrix

Base UI's data-starting-style / data-ending-style attributes can't express everything — four mechanisms cover the system, each with a defined home:

Field shakes once when it transitions into invalid, taking every control it wraps with it — the motion belongs to the field, not to the individual control, so Input, Textarea, Checkbox, RadioGroup, OTPInput and NumberField all behave identically inside one. Repeated failures replay via shakeSignal. FieldError itself stays still: Base UI only renders it while invalid, so it mounts fresh on every new error.

Sanctioned utilities

motion-pop-in, motion-enter-up, motion-shake, motion-flash (from @vegastack/design-tokens/utilities.css) are the only mount-animation classes, and motion-dock-in / motion-dock-out — from the same file — are the one sanctioned transition pair, for a docked control that stays mounted and flips data-active; everything else is a transition-* + token pair. Raw motion values — animate-[…], cubic-bezier(…), linear(…), duration-[…], ease-[…] — are lint-banned (raw-motion); every transition-* must carry duration-* and ease-* in the same class string (transition-pairing).

Toast motion is on the scale

Toasts used to be the one documented exception here, because sonner owned their motion. Since the Base UI Toast migration they are ours and they are tokenized: the enter, exit, stack and expand transitions all run duration-base ease-standard, the same pair as the modal family. A toast travels the same distance a Sheet does — in from beyond an edge — and 150ms reads clipped over that distance, which is the whole reason it is not duration-fast like the anchored surfaces.

Documented exceptions

• Indeterminate loaders — animate-spin (Spinner) and animate-pulse (Skeleton) are platform defaults, allowed as-is.
• Animated icons — the registry/ui/icons/* mirrors carry their own Motion-driven variants (including the check pathLength draw); their inline values are regenerated by the mirror script, not hand-tuned.

Exclusions (deliberate)

Adapted-from-reference effects we chose not to ship, per the dense dev-tool aesthetic: avatar hover lift, card 3D tilt, FAB morph. No button hover animations anywhere, and no press-motion either — the former active:translate-y-px nudge was removed; pressed feedback is colour-only (the active:* background states).

Duration utility bridge

The raw duration tokens live under --duration-*, but the @theme inline block in @vegastack/design-tokens/theme.css also re-exports them into Tailwind's transition-duration namespace:

@theme inline {
  --transition-duration-fast: var(--duration-fast);
  --transition-duration-base: var(--duration-base);
  --transition-duration-slow: var(--duration-slow);
}

That bridge is what lets you write the named duration-* utility instead of an arbitrary value — both compile to the same 150ms:

<div className="transition-opacity ease-standard duration-fast" />

Reduced motion

prefers-reduced-motion: reduce is enforced globally in @vegastack/design-tokens/base.css: every animation-duration / transition-duration collapses to 0.01ms with a single iteration, so no component opts out by accident. The specimen above also carries motion-reduce:animate-none defensively.