Motion

Hewn treats motion as a global contract, not a per-component prop. Tokens set timing, MotionProvider sets the mode, and sources may only animate transform, opacity, and filter.

Tokens

CSS custom properties live in @hewnui/themes/motion.css (imported by tokens.css). Theme packs still tune --kp-motion-duration for character; the scale below is shared.

TypeScript mirrors for Motion transitions ship from @hewnui/motion:

import { durations, easings, springs } from "@hewnui/motion";

durations.fast; // 0.12
easings.standard; // [0.2, 0, 0, 1]
springs.snappy; // { type: "spring", stiffness: 420, … }

Use CSS vars in class strings (duration-[var(--kp-motion-duration-fast)], ease-[var(--kp-motion-ease-standard)]) and the TS constants in transition={{ … }} props. Do not hard-code millisecond or bezier values in components.

Modes

MotionProvider exposes three modes:

Resolution rules:

1. Default preference is full.
2. prefers-reduced-motion: reduce caps effective mode at reduced — a user preference of full cannot win.
3. Users may only reduce motion further (full → reduced → off).
4. The effective mode is written to document.documentElement.dataset.motion so CSS-only surfaces can key off [data-motion="reduced"] / "off".

import { MotionProvider, useMotionMode } from "@hewnui/ui";

<MotionProvider defaultMotion="full">{children}</MotionProvider>

const { motion, effectiveMode, motionEnabled, reducedMotion, setMotion } =
  useMotionMode();

MotionConfig receives reducedMotion="never" in full mode and "always" otherwise.

Rules

• Animate transform, opacity, and filter only. Never animate layout properties (width, height, top, left, margin, …).
• Never use transition: all or Tailwind transition-all.
• Press feedback uses scale(0.96).
• Reduced motion always wins over product defaults and user “more motion” choices.
• Infinite motion must be isolated, memoized, and disabled when motionEnabled is false.
• pnpm check:motion fails the build if packages/ui sources violate the transition contract.

Appearance controls

Docs and Theme Lab appearance docks include the motion mode control next to theme, mode, material, and radius. Choices persist in localStorage (kp-motion). Legacy on values migrate to full.