first commit

docs/ui/react/react-ui/src/utils/motion/motion.md

@@ -0,0 +1,82 @@
+# `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.