Motion settings

Use the defaults

The base stylesheet includes the motion tokens and the shared motion rules. Components that use animated icons, layout transitions, overlays, or loading indicators depend on them; preserve the base import and component CSS.

The examples use each component’s built-in motion; you do not need extra animation code to reproduce them.

Motion tokens

Every duration and easing in the kit comes from a --motion-* custom property that the base stylesheet sets on :root. Component CSS reads these tokens directly. The Motion parts and the charts read them from their own element when an animation starts; a mark that follows the pointer moves on a spring timed by its duration token.

Durations

The duration scale has six steps, micro, fast, base, moderate, slow and linger, and most motion takes one of them.

The other durations belong to one kind of motion each.

A few motions are multiples of a step, so they follow it when you change it. The global search opens in 80 percent of --motion-duration-micro and closes in half of it. A scrollbar waits three micro steps before it fades, and the copy check draws in over two. A toast’s error shake takes seven eighths of --motion-duration-slow. The Spinner and Skeleton loops are multiples of --motion-duration-loop.

Easings

Distances and scales

Override a token

Set a token on :root in your global stylesheet, after the base import. The kit defines its tokens inside a cascade layer, so a rule that your application writes outside a layer wins over them, except under reduced motion, where the kit keeps its durations at 1ms (see Respect user preferences). This example makes floating panels and dialogs a little quicker:

:root {
  --motion-duration-moderate: 200ms;
  --motion-duration-modal: 180ms;
}

A step of the scale times many components, so changing --motion-duration-moderate also changes the content of a toast and the fill of an Animated Button. Set a token that belongs to one kind of motion, such as --motion-duration-modal, when only that motion should change. --motion-duration-value follows --motion-duration-linger until you set it.

A token set on a wrapper reaches what renders inside it, as any custom property does. Popovers, menus, dialogs and toasts render in a portal at the end of the document, outside your wrappers, so set their tokens on :root. A wrapper can give one group of charts a slower glide, for example:

.report-charts {
  --motion-duration-value: 600ms;
}

Scoped configuration

SiteplaneMotionProvider is installed with the shared base source:

import { SiteplaneMotionProvider } from "@/siteplane/system/motion/siteplane-motion-provider";
import { Button } from "@/siteplane/components/button";

<SiteplaneMotionProvider preset="reduced">
  <Button>Continue</Button>
</SiteplaneMotionProvider>;

The preset is standard or reduced and is required. The provider creates a real div scope, unlike the display-contents UI provider. useSiteplaneMotionPreset returns the current scoped preset or undefined outside a provider. Kit portals inside the provider carry its preset.

Respect user preferences

Motion is reduced when the system asks for reduced motion, when html carries data-motion-reduce="true", or inside SiteplaneMotionProvider preset="reduced". Under each of them the base stylesheet sets every duration token except the three loops to 1ms, on every element in its scope. Transitions and animations then finish at once and still fire their end events. These values are marked important, so a token that you override does not bring motion back for people who asked for less.

The loop, ring pulse and Badge light durations keep their values; the Spinner, the Skeleton, indeterminate Progress, the Badge light and a featured icon’s rings stop under reduced motion instead. Motion that a component drives from JavaScript, such as the Motion parts and the charts, also reads the preference and jumps to its end.

Retain the component’s reduced-motion handling and test the actual interaction with the operating system preference enabled. Different components combine CSS and JavaScript motion; a scoped preset is not a promise that arbitrary application animations are disabled. For custom animation, handle reduced motion explicitly and keep the final state immediately understandable.

Animated Buttons, Icon Morphs, Theme Toggles, Pagination, and Tag Group document their specific motion-related APIs and limits.