# Motion settings

Tune the shared motion tokens and keep reduced-motion behavior.

## 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](/docs/components/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.

| Token                        | Default | Used for                                                                                                                                     |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--motion-duration-micro`    | `100ms` | The shortest step, for quick fades, the fade-through of swapped content, the beats of a stagger and a scrollbar that appears.                |
| `--motion-duration-fast`     | `150ms` | State changes on hover, press, focus and selection, floating labels, dimmed chart bars, a scrollbar that fades out and a picker that closes. |
| `--motion-duration-base`     | `180ms` | Small moves and fades, such as icon pops, the Sidebar’s width and labels, steppers and pagination.                                           |
| `--motion-duration-moderate` | `240ms` | Floating panels such as Popover, Menu, Select and Tooltip that open, close or flip sides, and the content of a toast.                        |
| `--motion-duration-slow`     | `320ms` | Draws and slides, such as checks, calendar months, sliders, the copy icon and a toast’s success pulse.                                       |
| `--motion-duration-linger`   | `380ms` | Long settles, such as Progress, the toast stack, theme toggles, a dimmed chart series and a check on its way out.                            |

The other durations belong to one kind of motion each.

| Token                             | Default                         | Used for                                                                                                                                         |
| --------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--motion-duration-overlay`       | `160ms`                         | A dialog’s backdrop, the cross-fade between the panes of a popover or tooltip, and a date or color picker that opens.                            |
| `--motion-duration-expand`        | `200ms`                         | Panels that expand or collapse, such as Accordion and Collapsible, list items that enter or leave, and the height of Tabs panels after a switch. |
| `--motion-duration-modal`         | `210ms`                         | A Dialog or AlertDialog that opens or closes.                                                                                                    |
| `--motion-duration-follow`        | `280ms`                         | Marks that follow the pointer, such as a chart’s crosshair and dots.                                                                             |
| `--motion-duration-navigation`    | `300ms`                         | A NavigationMenu popup and the switch between its groups.                                                                                        |
| `--motion-duration-value`         | `var(--motion-duration-linger)` | Values that change in place, such as chart data, rolling numbers, Meter and Sparkline.                                                           |
| `--motion-duration-panel-release` | `400ms`                         | A Drawer that is let go after a swipe, scaled by the strength of the swipe.                                                                      |
| `--motion-duration-panel`         | `450ms`                         | A Sheet or Drawer that slides in or out, with its backdrop.                                                                                      |
| `--motion-duration-follow-trail`  | `520ms`                         | A card that trails the pointer, such as the tooltip of a chart.                                                                                  |
| `--motion-duration-carousel`      | `800ms`                         | A carousel page that settles.                                                                                                                    |
| `--motion-duration-loop`          | `1000ms`                        | One cycle of a loading loop in Spinner, Skeleton and indeterminate Progress.                                                                     |
| `--motion-duration-ring-pulse`    | `4000ms`                        | One loop of a featured icon’s ring pulse.                                                                                                        |
| `--motion-duration-badge-light`   | `5000ms`                        | One turn of the Badge light.                                                                                                                     |

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

| Token                        | Default                            | Used for                                                                                                                                       |
| ---------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--motion-ease-standard`     | `cubic-bezier(0.16, 1, 0.3, 1)`    | The default curve, a quick start that settles softly, for presence, overlays, checks, slides, values and toasts.                               |
| `--motion-ease-state`        | `cubic-bezier(0.4, 0, 0.2, 1)`     | State changes of fields, choice controls, tabs and accordions, and a scrollbar that fades.                                                     |
| `--motion-ease-soft-in-out`  | `cubic-bezier(0.65, 0, 0.35, 1)`   | An even start and finish, for icons that morph, fills that sweep, dimmed chart series and content that leaves a swap.                          |
| `--motion-ease-expand`       | `cubic-bezier(0.7, 0.1, 0.5, 0.9)` | A Collapsible’s panel and chevron.                                                                                                             |
| `--motion-ease-panel`        | `cubic-bezier(0.32, 0.72, 0, 1)`   | A Sheet or Drawer and its backdrop.                                                                                                            |
| `--motion-ease-navigation`   | `cubic-bezier(0.25, 0.1, 0.25, 1)` | The browser’s default curve, for a NavigationMenu, the Icon Morphs, calendar days, the toast stack’s fades and the Switch thumb in a menu row. |
| `--motion-ease-carousel`     | `cubic-bezier(0.25, 1, 0.5, 1)`    | A carousel page that settles.                                                                                                                  |
| `--motion-ease-switch`       | `cubic-bezier(0, 0.55, 0.45, 1)`   | A Switch thumb on its way to the other end.                                                                                                    |
| `--motion-ease-toast-replay` | `cubic-bezier(0.5, 1, 0.89, 1)`    | A toast that replays its type when it is updated.                                                                                              |
| `--motion-ease-loop`         | `ease-in-out`                      | The Spinner’s comet, dots and bars.                                                                                                            |
| `--motion-ease-ping`         | `cubic-bezier(0, 0, 0.2, 1)`       | The Spinner’s pulse.                                                                                                                           |
| `--motion-ease-linear`       | `linear`                           | An even pace for progress, loops, strokes that draw, the Sidebar’s width and a featured icon’s rings.                                          |

### Distances and scales

| Token                            | Default    | Used for                                                                                  |
| -------------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
| `--motion-overlay-y`             | `4px`      | How far a NavigationMenu popup, or a popover that flips sides, travels as it settles.     |
| `--motion-overlay-scale`         | `0.985`    | The scale a popover starts from when it flips sides.                                      |
| `--motion-navigation-distance`   | `0.75rem`  | How far a NavigationMenu’s content travels when the group changes.                        |
| `--motion-floating-panel-offset` | `7px`      | How far a floating panel travels as it opens and closes.                                  |
| `--motion-floating-panel-scale`  | `0.955`    | The scale a floating panel opens from.                                                    |
| `--motion-presence-scale`        | `0.96`     | The scale of a list item that enters or leaves.                                           |
| `--motion-check-pop-scale`       | `0.82`     | The scale a check pops in from, and shrinks back to.                                      |
| `--motion-ring-pulse-scale`      | `1.55`     | How far a featured icon’s ring travels, as a scale of its circle.                         |
| `--motion-ring-pulse-opacity`    | `0.24`     | The strongest opacity of a featured icon’s ring.                                          |
| `--motion-ring-pulse-count`      | `infinite` | How many waves a featured icon’s rings travel. A number stops them after that many waves. |

## 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](#respect-user-preferences)). This example makes floating panels and dialogs a little quicker:

```css
: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:

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

## Scoped configuration

SiteplaneMotionProvider is installed with the shared base source:

```tsx
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](/docs/components/animated-buttons/), [Icon Morphs](/docs/components/icon-morphs/), [Theme Toggles](/docs/components/theme-toggles/), [Pagination](/docs/components/pagination/), and [Tag Group](/docs/components/tag-group/) document their specific motion-related APIs and limits.