# `motion` — chassis motion-token resolver

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Tiny set of helpers for components that need to read the chassis motion
tokens. The Provider applies the active theme's tokens as
`--motion-duration-*` and `--motion-easing-*` CSS variables on
`<html>`; this module exposes a typed `motionToken` builder so
component source uses a single canonical reference style. The
`prefersReducedMotion()` helper is a runtime read for components that
need to branch on the user preference in JS rather than via CSS
variables.

## Features

- Typed `MotionTokenName` union covering every chassis motion token
  (`duration-fast` / `duration-base` / `duration-slow` /
  `easing-standard` / `easing-enter` / `easing-exit`)
- `motionToken(name)` returns the `var(--motion-<name>)` string
- `prefersReducedMotion()` is SSR-safe — returns `false` when no
  `window` / `matchMedia` is available
- Honours the chassis convention that the `<ThemeProvider>` is the
  single mutator of the underlying CSS variables; this module only
  reads

## Usage: Basic example

```tsx
import { motionToken } from "@suaveplan/react-ui/utils/motion";

<div
    style={{
        transitionProperty: "opacity",
        transitionDuration: motionToken("duration-base"),
        transitionTimingFunction: motionToken("easing-standard"),
    }}
/>;
```

## Usage: Advanced example

```tsx
import { motionToken, prefersReducedMotion } from "@suaveplan/react-ui/utils/motion";

function Animated({ children }: { children: React.ReactNode }) {
    const reduced = prefersReducedMotion();
    return (
        <div
            style={{
                transitionProperty: "opacity, transform",
                transitionDuration: reduced
                    ? "0ms"
                    : motionToken("duration-slow"),
                transitionTimingFunction: motionToken("easing-enter"),
            }}
        >
            {children}
        </div>
    );
}
```

## API Reference

- `motionToken(name: MotionTokenName): string` — builds the
  `var(--motion-<name>)` reference
- `prefersReducedMotion(): boolean` — runtime media-query read; SSR-safe
- `type MotionTokenName` — union of every chassis motion token name

## Implementation notes

The chassis intentionally exposes both a CSS-variable read path
(`motionToken`) and a JS read path (`prefersReducedMotion`) because
some component patterns (e.g. canvas-rendered visuals, `requestAnimation
Frame`-driven scrubs) cannot consume CSS variables directly. Most
components that DO consume CSS — every Radix primitive wrapper, every
shadcn-derived component — should prefer the variable path so the
chassis can flip motion globally via the `<ThemeProvider>` without
re-rendering each component.