`motion` — chassis motion-token resolver

(no submodules)

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

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

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

Usage: Advanced example

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.

2.7 KiB Raw Blame History

motion — chassis motion-token resolver