@zyncat/ui 0.8.0

package/src/motion/flip.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { useLayoutEffect, useRef, type RefObject } from 'react';
+import {
+  dropShared,
+  flip,
+  keepShared,
+  measure,
+  readShared,
+  type Box,
+  type FlipOptions,
+  type Playback,
+} from '../engine';
+import { UIMotion } from '../tokens/motion-tokens';
+
+export type FlipTuning = FlipOptions;
+
+export function useSelfFlip<T extends HTMLElement>(tuning: FlipTuning = {}, enabled = true): RefObject<T | null> {
+  const ref = useRef<T | null>(null);
+  const previous = useRef<Box | null>(null);
+  const playing = useRef<Playback | null>(null);
+  const { scale, timing } = tuning;
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || !enabled) return;
+    const from = playing.current ? measure(el) : previous.current;
+    playing.current?.stop();
+    previous.current = measure(el);
+    const next = from && !UIMotion.reduced ? flip(el, from, { scale, timing }) : null;
+    playing.current = next;
+    next?.finished.then(() => {
+      if (playing.current === next) playing.current = null;
+    });
+  });
+
+  useLayoutEffect(
+    () => () => {
+      playing.current?.stop();
+    },
+    [],
+  );
+
+  return ref;
+}
+
+export function useSharedFlip<T extends HTMLElement>(
+  id: string,
+  tuning: FlipTuning = {},
+  enabled = true,
+): RefObject<T | null> {
+  const ref = useRef<T | null>(null);
+  const playing = useRef<{ play: Playback; el: T } | null>(null);
+  const { scale, timing } = tuning;
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || !enabled) return;
+    const live = playing.current;
+    const from = live && live.el === el ? measure(el) : readShared(id);
+    live?.play.stop();
+    keepShared(id, measure(el));
+    const next = from && !UIMotion.reduced ? flip(el, from, { scale, timing }) : null;
+    playing.current = next ? { play: next, el } : null;
+    next?.finished.then(() => {
+      if (playing.current?.play === next) playing.current = null;
+    });
+  });
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    return () => {
+      const live = playing.current;
+      if (live) {
+        const box = measure(live.el);
+        if (box.width && box.height) keepShared(id, box);
+        live.play.stop();
+      }
+      const mine = readShared(id);
+      queueMicrotask(() => {
+        if (readShared(id) === mine) dropShared(id);
+      });
+    };
+  }, [id, enabled]);
+
+  return ref;
+}

package/src/motion/glide.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import { useRef, type RefObject } from 'react';
+import { animate } from '../engine';
+import { UIMotion as SM } from '../tokens/motion-tokens';
+
+export type GlideApi = ReturnType<typeof useGlide>;
+
+export function useGlide<T extends HTMLElement>(containerRef: RefObject<T | null>) {
+  const ref = useRef<HTMLSpanElement | null>(null);
+  const visible = useRef(false);
+
+  function enter(target: HTMLElement | null) {
+    const box = containerRef.current,
+      pill = ref.current;
+    if (!box || !pill || !target) return;
+    const was = pill.getBoundingClientRect();
+    const b = box.getBoundingClientRect();
+    const t = target.getBoundingClientRect();
+    const s = box.offsetWidth ? b.width / box.offsetWidth : 1;
+    pill.style.translate = `${(t.left - b.left) / s + box.scrollLeft}px ${(t.top - b.top) / s + box.scrollTop}px`;
+    pill.style.width = `${t.width / s}px`;
+    pill.style.height = `${t.height / s}px`;
+    const now = pill.getBoundingClientRect();
+    animate(pill, { opacity: [1], timing: { duration: SM.dur.fast, ease: SM.ease.standard } });
+    const glided = visible.current && !SM.reduced;
+    visible.current = true;
+    if (!glided) return;
+    const timing = { ...SM.t.settle, fill: 'none' as const };
+    animate(
+      pill,
+      { x: [was.left - now.left, 0], y: [was.top - now.top, 0], timing, composite: 'add' },
+      { width: [was.width, now.width], height: [was.height, now.height], timing },
+    );
+  }
+
+  function leave() {
+    visible.current = false;
+    if (ref.current) animate(ref.current, { opacity: [0], timing: { duration: SM.dur.fast, ease: SM.ease.exit } });
+  }
+
+  return { ref, enter, leave };
+}
+
+export function GlidePill({ className, glide }: { className?: string; glide: GlideApi }) {
+  return <span ref={glide.ref} className={className} aria-hidden="true" />;
+}

package/src/motion/motion-timing.ts

@@ -0,0 +1,33 @@
+import { UIMotion, type MotionTransition } from '../tokens/motion-tokens';
+import type { DurationToken, EaseToken } from '../tokens/motion-scale';
+import { resolveDirection, type DisableableAnimation } from './timing';
+
+export interface DirectionDefault {
+  duration: DurationToken;
+  ease: EaseToken;
+}
+
+export interface MotionTimingDefaults {
+  open: DirectionDefault;
+  close: DirectionDefault;
+}
+
+export interface MotionTimings {
+  open: MotionTransition;
+  close: MotionTransition;
+}
+
+export function resolveMotionTiming(
+  animation: DisableableAnimation | undefined,
+  defaults: MotionTimingDefaults,
+): MotionTimings {
+  if (animation === null) return { open: { duration: 0 }, close: { duration: 0 } };
+
+  const build = (dir: 'open' | 'close'): MotionTransition => {
+    const durToken = (animation && resolveDirection(animation.duration, dir)) || defaults[dir].duration;
+    const easeToken = (animation && resolveDirection(animation.ease, dir)) || defaults[dir].ease;
+    return { duration: UIMotion.dur[durToken], ease: UIMotion.ease[easeToken] };
+  };
+
+  return { open: build('open'), close: build('close') };
+}

package/src/motion/presence-context.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+export interface PresenceState {
+  /** False once the child has been removed from `children` but is still mounted for its exit. */
+  isPresent: boolean;
+  /** False for children present at the Presence's own first paint when `initial={false}`. */
+  initial: boolean;
+  /** Called by the child when its exit has finished; lets Presence drop it from the tree. */
+  safeToRemove: () => void;
+}
+
+const DETACHED: PresenceState = { isPresent: true, initial: true, safeToRemove: () => {} };
+
+export const PresenceContext = createContext<PresenceState>(DETACHED);
+
+export const usePresence = (): PresenceState => useContext(PresenceContext);

package/src/motion/presence.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import {
+  Children,
+  Fragment,
+  createElement,
+  isValidElement,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { PresenceContext } from './presence-context';
+
+interface Entry {
+  key: string;
+  node: ReactElement;
+  exiting: boolean;
+}
+
+function toEntries(children: ReactNode): Entry[] {
+  const out: Entry[] = [];
+  Children.forEach(children, (child, index) => {
+    if (isValidElement(child)) out.push({ key: String(child.key ?? index), node: child, exiting: false });
+  });
+  return out;
+}
+
+export interface PresenceProps {
+  /** Keyed children. A child animates out only if it renders a `<Motion>` carrying `exit`. */
+  children?: ReactNode;
+  /** Let children present on the first paint play their `animate`. @default true */
+  initial?: boolean;
+  /** `wait` holds entering children back until the outgoing ones have left. @default 'sync' */
+  mode?: 'sync' | 'wait';
+  /** Fires once the last exiting child has been removed. */
+  onExitComplete?: () => void;
+}
+
+export function Presence({ children, initial = true, mode = 'sync', onExitComplete }: PresenceProps) {
+  const incoming = toEntries(children);
+  const signature = incoming.map((entry) => entry.key).join('|');
+  const [shown, setShown] = useState<Entry[]>(incoming);
+  const bornAtMount = useRef(new Set(incoming.map((entry) => entry.key)));
+  const wasExiting = useRef(false);
+  const complete = useRef(onExitComplete);
+  complete.current = onExitComplete;
+
+  useLayoutEffect(() => {
+    setShown((previous) => {
+      const live = new Set(incoming.map((entry) => entry.key));
+      const merged: Entry[] = incoming.map((entry) => ({ ...entry }));
+      previous.forEach((entry, index) => {
+        if (live.has(entry.key)) return;
+        merged.splice(index, 0, entry.exiting ? entry : { ...entry, exiting: true });
+      });
+      return merged;
+    });
+  }, [signature]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const leaving = shown.some((entry) => entry.exiting);
+
+  useEffect(() => {
+    if (wasExiting.current && !leaving) complete.current?.();
+    wasExiting.current = leaving;
+  }, [leaving]);
+
+  const fresh = new Map(incoming.map((entry) => [entry.key, entry.node]));
+  const visible = mode === 'wait' && leaving ? shown.filter((entry) => entry.exiting) : shown;
+
+  return createElement(
+    Fragment,
+    null,
+    visible.map((entry) =>
+      createElement(
+        PresenceContext.Provider,
+        {
+          key: entry.key,
+          value: {
+            isPresent: !entry.exiting,
+            initial: initial || !bornAtMount.current.has(entry.key),
+            safeToRemove: () => setShown((previous) => previous.filter((e) => e.key !== entry.key || !e.exiting)),
+          },
+        },
+        fresh.get(entry.key) ?? entry.node,
+      ),
+    ),
+  );
+}

package/src/motion/timing.ts

@@ -0,0 +1,49 @@
+import type { CSSProperties } from 'react';
+import type { DurationToken, EaseToken } from '../tokens/motion-scale';
+
+export type TimingDirection = 'open' | 'close';
+/** One token for both directions, or split per direction; an omitted direction keeps its default. */
+export type DirectionalToken<Token extends string> = Token | { [D in TimingDirection]?: Token };
+
+/** Timing of an open/close transition, constrained to the motion token vocabulary -
+ *  see DurationToken / EaseToken for what each token means. */
+export interface AnimationTiming {
+  /** Duration token(s); an omitted field or direction keeps the component's default. */
+  duration?: DirectionalToken<DurationToken>;
+  /** Ease token(s); an omitted field or direction keeps the component's default. */
+  ease?: DirectionalToken<EaseToken>;
+}
+
+/** The `animation` prop shape: tokens to retime, omit for the component's defaults, or
+ *  `null` to disable the transition entirely (it plays instantly). */
+export type DisableableAnimation = AnimationTiming | null;
+
+/** Extend this to expose the timing API on a component; redeclare `animation`
+ *  to document the component's own default tokens. */
+export interface TimingProps {
+  /** Transition timing - motion tokens only, each field a single token or { open, close };
+   *  `null` disables the transition (it plays instantly). */
+  animation?: DisableableAnimation;
+}
+
+export function resolveDirection<Token extends string>(
+  timing: DirectionalToken<Token> | undefined,
+  dir: TimingDirection,
+): Token | undefined {
+  return typeof timing === 'object' ? timing[dir] : timing;
+}
+
+export function timingVars(prefix: string, animation: DisableableAnimation | undefined): CSSProperties | undefined {
+  if (animation === undefined) return undefined;
+  if (animation === null) {
+    return { [`--${prefix}-dur-open`]: '0ms', [`--${prefix}-dur-close`]: '0ms' } as CSSProperties;
+  }
+  const vars: Record<string, string> = {};
+  for (const dir of ['open', 'close'] as const) {
+    const d = resolveDirection(animation.duration, dir);
+    const e = resolveDirection(animation.ease, dir);
+    if (d) vars[`--${prefix}-dur-${dir}`] = `var(--duration-${d})`;
+    if (e) vars[`--${prefix}-ease-${dir}`] = `var(--ease-${e})`;
+  }
+  return Object.keys(vars).length ? (vars as CSSProperties) : undefined;
+}

package/src/motion/use-motion.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import { useLayoutEffect, useRef, type RefObject } from 'react';
+import { animate, type Layer, type Playback } from '../engine';
+import { usePresence } from './presence-context';
+
+export type Plays = Playback | Playback[] | null | undefined | void;
+export type MotionSpec = Layer | Layer[] | ((el: HTMLElement) => Plays);
+
+const toList = (plays: Plays): Playback[] => (!plays ? [] : Array.isArray(plays) ? plays : [plays]);
+
+export function run(spec: MotionSpec | undefined, el: HTMLElement): Playback[] {
+  if (!spec) return [];
+  if (typeof spec === 'function') return toList(spec(el));
+  return [Array.isArray(spec) ? animate(el, ...spec) : animate(el, spec)];
+}
+
+const allSettled = (plays: Playback[]): Promise<void> =>
+  plays.length ? Promise.all(plays.map((play) => play.finished)).then((): void => {}) : Promise.resolve();
+
+export interface MotionSpecs {
+  /** Plays on mount, and again whenever `deps` change. */
+  animate?: MotionSpec;
+  /** Plays when a parent `<Presence>` drops this child; it stays mounted until this finishes. */
+  exit?: MotionSpec;
+  /** Play `animate` on mount. Falls back to the parent Presence's own `initial`. @default true */
+  initial?: boolean;
+  /** Replay `animate` when these change. Must keep a stable length. @default [] */
+  deps?: unknown[];
+}
+
+/** Drives `<Motion>`; use it directly on elements you hold a ref to but do not render. */
+export function useMotion(ref: RefObject<HTMLElement | null>, { animate, exit, initial, deps }: MotionSpecs): void {
+  const presence = usePresence();
+  const playing = useRef<Playback[]>([]);
+  const mounted = useRef(false);
+  const spec = useRef({ animate, exit, initial });
+  spec.current = { animate, exit, initial };
+
+  const stop = () => {
+    for (const play of playing.current) play.stop();
+    playing.current = [];
+  };
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    const atMount = !mounted.current;
+    mounted.current = true;
+    if (!el) return;
+    if (atMount && (spec.current.initial ?? presence.initial) === false) return;
+    stop();
+    playing.current = run(spec.current.animate, el);
+  }, deps ?? []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useLayoutEffect(() => {
+    if (presence.isPresent) return;
+    const el = ref.current;
+    stop();
+    playing.current = el ? run(spec.current.exit, el) : [];
+    allSettled(playing.current).then(presence.safeToRemove);
+  }, [presence.isPresent]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useLayoutEffect(() => stop, []);
+}

package/src/styles.css

@@ -0,0 +1,26 @@
+/* Zyncat UI base layer - import ONCE at your app root:  import '@zyncat/ui/styles.css';
+   Fonts, design tokens (:root variables) and the shared `glass` utility.
+
+   Per-component CSS is NOT here on purpose: every component imports its own
+   stylesheet, so the consumer's bundler code-splits and lazy-loads it with the
+   component. This file is only the always-needed global layer.
+   Order matters: fonts - primitives - semantics - shared utilities. */
+
+@import './tokens/fonts.css';
+
+@import './tokens/color.css';
+@import './tokens/typography.css';
+@import './tokens/spacing.css';
+@import './tokens/radius.css';
+@import './tokens/elevation.css';
+@import './tokens/motion.css';
+@import './tokens/glass.css';
+@import './tokens/icons.css';
+@import './tokens/layers.css';
+@import './tokens/avatar.css';
+
+@import './tokens/semantic.css';
+
+/* Cross-cutting frosted-surface utility shared by several unrelated components
+   (badge, toast, select, icon); kept global instead of duplicated per component. */
+@import './components/internal/glass/glass.css';

package/src/tokens/avatar.css

@@ -0,0 +1,20 @@
+/* Avatar tokens - reserved identity palette + lit-from-above face finish. */
+
+:root {
+  --avatar-1-bg: oklch(0.945 0.04 250);
+  --avatar-1-fg: oklch(0.45 0.08 250);
+  --avatar-2-bg: oklch(0.945 0.04 292);
+  --avatar-2-fg: oklch(0.45 0.08 292);
+  --avatar-3-bg: oklch(0.945 0.04 334);
+  --avatar-3-fg: oklch(0.45 0.08 334);
+  --avatar-4-bg: oklch(0.945 0.04 5);
+  --avatar-4-fg: oklch(0.45 0.08 5);
+  --avatar-5-bg: oklch(0.945 0.04 55);
+  --avatar-5-fg: oklch(0.45 0.08 55);
+  --avatar-6-bg: oklch(0.945 0.04 125);
+  --avatar-6-fg: oklch(0.45 0.08 125);
+
+  /* Surface finish - white sheen from top, cool near-black shade from bottom (never pure black). */
+  --avatar-sheen: oklch(1 0 0 / 0.35);
+  --avatar-shade: oklch(0.225 0.012 264 / 0.05);
+}

package/src/tokens/color.css

@@ -0,0 +1,58 @@
+/* Color primitives - the closed neutral + status ramps. */
+
+:root {
+  --gray-0: oklch(1 0 0);
+  --gray-25: oklch(0.992 0.0015 264);
+  --gray-50: oklch(0.984 0.003 264);
+  --gray-100: oklch(0.968 0.004 264);
+  --gray-150: oklch(0.948 0.005 264);
+  --gray-200: oklch(0.922 0.006 264);
+  --gray-300: oklch(0.872 0.008 264);
+  --gray-400: oklch(0.765 0.01 264);
+  --gray-500: oklch(0.642 0.012 264);
+  --gray-600: oklch(0.532 0.013 264);
+  --gray-700: oklch(0.422 0.013 264);
+  --gray-800: oklch(0.305 0.012 264);
+  --gray-900: oklch(0.225 0.01 264);
+  --gray-950: oklch(0.165 0.008 264);
+
+  --teal-50: oklch(0.972 0.02 198);
+  --teal-100: oklch(0.935 0.04 198);
+  --teal-200: oklch(0.88 0.066 198);
+  --teal-300: oklch(0.795 0.092 198);
+  --teal-400: oklch(0.705 0.112 198);
+  --teal-500: oklch(0.63 0.118 198);
+  --teal-600: oklch(0.56 0.114 198);
+  --teal-700: oklch(0.478 0.1 198);
+  --teal-800: oklch(0.4 0.082 198);
+  --teal-900: oklch(0.32 0.062 198);
+
+  --green-50: oklch(0.965 0.028 152);
+  --green-500: oklch(0.62 0.13 152);
+  --green-600: oklch(0.548 0.122 152);
+  --green-700: oklch(0.462 0.1 152);
+
+  --amber-50: oklch(0.972 0.034 75);
+  --amber-500: oklch(0.76 0.14 75);
+  --amber-600: oklch(0.7 0.142 75);
+  --amber-700: oklch(0.56 0.118 75);
+
+  --red-50: oklch(0.968 0.02 27);
+  --red-300: oklch(0.8 0.09 27);
+  --red-400: oklch(0.64 0.2 27);
+  --red-500: oklch(0.602 0.196 27);
+  --red-600: oklch(0.545 0.196 27);
+  --red-700: oklch(0.478 0.172 27);
+
+  /* Wash tints - glassy active/selected fills that let the surface show through; low alpha per hue.
+     -strong is the press step of the gray wash (hover 6% < press 10%). */
+  --gray-wash: oklch(0.42 0.012 264 / 0.06);
+  --gray-wash-strong: oklch(0.42 0.012 264 / 0.1);
+  --teal-wash: oklch(0.63 0.118 198 / 0.05);
+  --green-wash: oklch(0.62 0.13 152 / 0.1);
+  --amber-wash: oklch(0.76 0.14 75 / 0.12);
+  --red-wash: oklch(0.602 0.196 27 / 0.1);
+
+  /* Cool near-black shadow ink - pure black looks muddy on a cool canvas. */
+  --shadow-rgb: 13 18 30;
+}

package/src/tokens/elevation.css

@@ -0,0 +1,22 @@
+/* Elevation - two-layer shadows, focus/selection rings, border widths. */
+
+:root {
+  --shadow-xs: 0 1px 1px rgb(var(--shadow-rgb) / 0.04);
+  --shadow-sm: 0 1px 2px rgb(var(--shadow-rgb) / 0.05), 0 1px 1px rgb(var(--shadow-rgb) / 0.04);
+  --shadow-md: 0 2px 4px rgb(var(--shadow-rgb) / 0.04), 0 6px 12px rgb(var(--shadow-rgb) / 0.07);
+  --shadow-lg: 0 4px 8px rgb(var(--shadow-rgb) / 0.04), 0 12px 28px rgb(var(--shadow-rgb) / 0.1);
+  --shadow-xl: 0 8px 16px rgb(var(--shadow-rgb) / 0.06), 0 24px 48px rgb(var(--shadow-rgb) / 0.14);
+
+  /* Borders - one hairline (1px); weight comes from the border color, not thickness; 2px for focus/selected. */
+  --border-hairline: 1px;
+  --border-emphasis: 1.5px;
+
+  /* Focus & selection rings - box-shadows (not outlines) so they follow border-radius. */
+
+  /* Derive from --accent so the ring tracks the active accent and theme, never a fixed hue. */
+  --ring-accent: 0 0 0 3px color-mix(in oklab, var(--accent) 32%, transparent);
+  --ring-danger: 0 0 0 3px oklch(0.602 0.196 27 / 0.3);
+  --ring-warning: 0 0 0 3px color-mix(in oklab, var(--warning) 30%, transparent);
+  --ring-success: 0 0 0 3px color-mix(in oklab, var(--success) 30%, transparent);
+  --ring-offset: 0 0 0 2px var(--bg-surface), 0 0 0 4px color-mix(in oklab, var(--accent) 40%, transparent);
+}

package/src/tokens/fonts.css

@@ -0,0 +1,3 @@
+/* Webfonts - Geist (UI) + Geist Mono (numerals, data, code) from Google Fonts; self-host woff2 for prod. */
+
+@import url('https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=Geist+Mono:wght@400;500;600&display=swap');

package/src/tokens/glass.css

@@ -0,0 +1,20 @@
+/* Glass tokens - structural frosted-surface pieces; per-tone tints live in semantic.css. */
+
+:root {
+  --glass-blur: 9px;
+  --glass-blur-strong: 16px;
+  --glass-saturate: 1.5;
+
+  --glass-sheen: linear-gradient(
+    145deg,
+    rgb(255 255 255 / 0.55) 0%,
+    rgb(255 255 255 / 0.1) 24%,
+    rgb(255 255 255 / 0) 46%
+  );
+  --glass-sheen-rest: 0.8;
+  --glass-sheen-hover: 1;
+
+  --glass-highlight: inset 0 1px 0 0 rgb(255 255 255 / 0.55);
+  --glass-shadow: 0 1px 2px rgb(var(--shadow-rgb) / 0.05), 0 2px 5px rgb(var(--shadow-rgb) / 0.05);
+  --glass-shadow-hover: 0 2px 4px rgb(var(--shadow-rgb) / 0.06), 0 8px 18px rgb(var(--shadow-rgb) / 0.1);
+}

package/src/tokens/icons.css

@@ -0,0 +1,7 @@
+/* Icon sizing - sm 16 (inline) - md 20 (default) - lg 24 (emphasis). */
+
+:root {
+  --icon-sm: 17px;
+  --icon-md: 20px;
+  --icon-lg: 26px;
+}

package/src/tokens/layers.css

@@ -0,0 +1,6 @@
+/* Z-index bands - one stacking contract; --layer-overlay is a BAND (base + stack depth) so a later overlay paints above an earlier one. */
+:root {
+  --layer-overlay: 1000;
+  --layer-toast: 1050;
+  --layer-tooltip: 1100;
+}

package/src/tokens/motion-scale.ts

@@ -0,0 +1,17 @@
+/** Names of the UI-transition duration scale (`--duration-*`):
+ *  - `fast` 140ms - micro feedback: hover washes, presses, control tint/border/shadow.
+ *  - `base` 200ms - standard element transitions: fades, toggles, badge morphs.
+ *  - `slow` 300ms - layout-scale movement: Collapse, panel resizes, reordering.
+ *  - `slower` 450ms - large-surface movement: dialogs, sheets, page-scale reveals.
+ *  - `slowest` 900ms - hero-scale movement: card expansion, container transforms. The scale's
+ *    ceiling: anything longer is choreography and belongs to Motion, not a transition token. */
+export type DurationToken = 'fast' | 'base' | 'slow' | 'slower' | 'slowest';
+
+/** Names of the brand easing curves (`--ease-*`):
+ *  - `standard` cubic-bezier(0.2, 0, 0, 1) - brisk start, soft landing; the default for state changes.
+ *  - `entrance` cubic-bezier(0.16, 1, 0.3, 1) - hard deceleration; content arriving on screen.
+ *  - `exit` cubic-bezier(0.4, 0, 1, 1) - accelerates away; content leaving (pair with a faster duration).
+ *  - `spring` cubic-bezier(0.34, 1.4, 0.5, 1) - overshoots then settles; playful confirmations.
+ *  - `glide` cubic-bezier(0.55, 0, 0.15, 1) - symmetric in-out travel; a persistent element moving
+ *    between positions, never enter/exit. */
+export type EaseToken = 'standard' | 'entrance' | 'exit' | 'spring' | 'glide';

package/src/tokens/motion-tokens.ts

@@ -0,0 +1,92 @@
+export interface MotionTransition {
+  type?: 'spring' | 'tween' | 'inertia' | 'keyframes';
+  duration?: number;
+  ease?:
+    | Bezier
+    | 'linear'
+    | 'easeIn'
+    | 'easeOut'
+    | 'easeInOut'
+    | 'circIn'
+    | 'circOut'
+    | 'circInOut'
+    | 'backIn'
+    | 'backOut'
+    | 'backInOut'
+    | 'anticipate';
+  bounce?: number;
+  visualDuration?: number;
+  delay?: number;
+}
+
+export type Bezier = [number, number, number, number];
+
+import type { DurationToken, EaseToken } from './motion-scale';
+export type { DurationToken, EaseToken } from './motion-scale';
+
+export interface MotionTokens {
+  /** seconds - fast 0.14 - base 0.2 - slow 0.3 - slower 0.45 - slowest 0.9 */
+  dur: Record<DurationToken, number>;
+  ease: Record<EaseToken, Bezier>;
+  /** ready-made Motion transitions */
+  t: { enter: MotionTransition; exit: MotionTransition; layout: MotionTransition; settle: MotionTransition };
+  reduced: boolean;
+}
+
+const DEFAULT_DUR: MotionTokens['dur'] = { fast: 0.14, base: 0.2, slow: 0.3, slower: 0.45, slowest: 0.9 };
+const DEFAULT_EASE: MotionTokens['ease'] = {
+  standard: [0.2, 0, 0, 1],
+  entrance: [0.16, 1, 0.3, 1],
+  exit: [0.4, 0, 1, 1],
+  spring: [0.34, 1.4, 0.5, 1],
+  glide: [0.55, 0, 0.15, 1],
+};
+
+function build(dur: MotionTokens['dur'], ease: MotionTokens['ease']): MotionTokens {
+  const reduced = dur.base <= 0.005;
+  return {
+    dur,
+    ease,
+    reduced,
+    t: {
+      enter: { duration: dur.base, ease: ease.entrance },
+      exit: { duration: dur.fast, ease: ease.exit },
+      layout: { duration: dur.slow, ease: ease.entrance },
+      settle: reduced ? { duration: 0 } : { type: 'spring', visualDuration: dur.fast, bounce: 0.25 },
+    },
+  };
+}
+
+function readFromDom(): MotionTokens {
+  const cs = getComputedStyle(document.documentElement);
+  const seconds = (name: string, fallback: number): number => {
+    const v = cs.getPropertyValue(name).trim();
+    const n = v.slice(-2) === 'ms' ? parseFloat(v) / 1000 : parseFloat(v);
+    return isNaN(n) ? fallback : n;
+  };
+  const bezier = (name: string, fallback: Bezier): Bezier => {
+    const m = cs.getPropertyValue(name).match(/-?[\d.]+/g);
+    return m && m.length === 4 ? (m.map(Number) as Bezier) : fallback;
+  };
+  return build(
+    {
+      fast: seconds('--duration-fast', DEFAULT_DUR.fast),
+      base: seconds('--duration-base', DEFAULT_DUR.base),
+      slow: seconds('--duration-slow', DEFAULT_DUR.slow),
+      slower: seconds('--duration-slower', DEFAULT_DUR.slower),
+      slowest: seconds('--duration-slowest', DEFAULT_DUR.slowest),
+    },
+    {
+      standard: bezier('--ease-standard', DEFAULT_EASE.standard),
+      entrance: bezier('--ease-entrance', DEFAULT_EASE.entrance),
+      exit: bezier('--ease-exit', DEFAULT_EASE.exit),
+      spring: bezier('--ease-spring', DEFAULT_EASE.spring),
+      glide: bezier('--ease-glide', DEFAULT_EASE.glide),
+    },
+  );
+}
+
+export const UIMotion: MotionTokens =
+  typeof document !== 'undefined' ? readFromDom() : build(DEFAULT_DUR, DEFAULT_EASE);
+
+export default UIMotion;