Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(theme): motionScale config for defineTheme — computed duration scale (#685)

Cindy Zhang7d760c065013
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index 7df8faeb69..3f1747a6b7 100644
--- a/packages/core/src/theme/defineTheme.ts
+++ b/packages/core/src/theme/defineTheme.ts
@@ -50,6 +50,10 @@ import {
generateTypeScaleComponents,
type XDSTypeScaleConfig,
} from './expandTypeScale';
+import {
+ expandMotionScale,
+ type XDSMotionScaleConfig,
+} from './expandMotionScale';
import {
expandRadiusScale,
type XDSRadiusScaleConfig,
@@ -142,6 +146,23 @@ export interface XDSDefineThemeInput {
* ```
*/
typeScale?: XDSTypeScaleConfig;
+ /**
+ * Motion scale configuration. Computes duration min/max variants from
+ * base values and a scaling ratio: min = base × ratio, max = base / ratio.
+ *
+ * Explicit `tokens` overrides take precedence over motionScale-generated values.
+ *
+ * @example
+ * ```
+ * motionScale: { fast: 175, medium: 410, ratio: 0.75 }
+ *
+ * // Suggested starting points:
+ * // Snappy: { fast: 100, medium: 250, ratio: 0.75 }
+ * // Default: { fast: 175, medium: 410, ratio: 0.75 }
+ * // Cinematic: { fast: 200, medium: 500, ratio: 0.7 }
+ * ```
+ */
+ motionScale?: XDSMotionScaleConfig;
/**
* Optional radius scale configuration. Generates radius token overrides
* from a base unit and multiplier.
@@ -307,7 +328,15 @@ export function defineTheme(input: XDSDefineThemeInput): XDSDefinedTheme {
}
}
- // 2. Apply explicit token overrides (highest precedence — overwrites typeScale/radiusScale)
+ // 1c. Apply motionScale-generated tokens (same precedence as typeScale)
+ if (input.motionScale) {
+ const motionTokens = expandMotionScale(input.motionScale);
+ for (const [key, value] of Object.entries(motionTokens)) {
+ tokens[key] = value;
+ }
+ }
+
+ // 2. Apply explicit token overrides (highest precedence — overwrites typeScale/radiusScale/motionScale)
if (input.tokens) {
for (const [key, value] of Object.entries(input.tokens)) {
if (value !== undefined) {
diff --git a/packages/core/src/theme/expandMotionScale.test.ts b/packages/core/src/theme/expandMotionScale.test.ts
new file mode 100644
index 0000000000..d4d9499882
--- /dev/null
+++ b/packages/core/src/theme/expandMotionScale.test.ts
@@ -0,0 +1,80 @@
+import {describe, it, expect} from 'vitest';
+import {expandMotionScale} from './expandMotionScale';
+
+describe('expandMotionScale', () => {
+ it('computes default XDS motion scale', () => {
+ const tokens = expandMotionScale({fast: 175, medium: 410, ratio: 0.75});
+
+ expect(tokens['--duration-fast-min']).toBe('130ms'); // 175 × 0.75 = 131.25 → 130
+ expect(tokens['--duration-fast']).toBe('175ms');
+ expect(tokens['--duration-fast-max']).toBe('235ms'); // 175 / 0.75 = 233.3 → 235
+ expect(tokens['--duration-medium-min']).toBe('310ms'); // 410 × 0.75 = 307.5 → 310
+ expect(tokens['--duration-medium']).toBe('410ms');
+ expect(tokens['--duration-medium-max']).toBe('545ms'); // 410 / 0.75 = 546.6 → 545
+ });
+
+ it('computes snappy motion scale', () => {
+ const tokens = expandMotionScale({fast: 100, medium: 250, ratio: 0.75});
+
+ expect(tokens['--duration-fast-min']).toBe('75ms');
+ expect(tokens['--duration-fast']).toBe('100ms');
+ expect(tokens['--duration-fast-max']).toBe('135ms');
+ expect(tokens['--duration-medium-min']).toBe('190ms');
+ expect(tokens['--duration-medium']).toBe('250ms');
+ expect(tokens['--duration-medium-max']).toBe('335ms');
+ });
+
+ it('computes cinematic motion scale', () => {
+ const tokens = expandMotionScale({fast: 200, medium: 500, ratio: 0.7});
+
+ expect(tokens['--duration-fast-min']).toBe('140ms');
+ expect(tokens['--duration-fast']).toBe('200ms');
+ expect(tokens['--duration-fast-max']).toBe('285ms');
+ expect(tokens['--duration-medium-min']).toBe('350ms');
+ expect(tokens['--duration-medium']).toBe('500ms');
+ expect(tokens['--duration-medium-max']).toBe('715ms');
+ });
+
+ it('does not include easing token when not specified', () => {
+ const tokens = expandMotionScale({fast: 175, medium: 410, ratio: 0.75});
+
+ expect(tokens['--easing-standard']).toBeUndefined();
+ });
+
+ it('includes easing override when specified', () => {
+ const tokens = expandMotionScale({
+ fast: 175,
+ medium: 410,
+ ratio: 0.75,
+ easing: 'cubic-bezier(0.0, 0.0, 0.2, 1)',
+ });
+
+ expect(tokens['--easing-standard']).toBe('cubic-bezier(0.0, 0.0, 0.2, 1)');
+ });
+
+ it('produces exactly 6 duration tokens', () => {
+ const tokens = expandMotionScale({fast: 175, medium: 410, ratio: 0.75});
+ const durationKeys = Object.keys(tokens).filter(k =>
+ k.startsWith('--duration-'),
+ );
+
+ expect(durationKeys).toHaveLength(6);
+ });
+
+ it('maintains ordering: min < base < max', () => {
+ const tokens = expandMotionScale({fast: 175, medium: 410, ratio: 0.75});
+
+ const fastMin = parseInt(tokens['--duration-fast-min']);
+ const fast = parseInt(tokens['--duration-fast']);
+ const fastMax = parseInt(tokens['--duration-fast-max']);
+ const medMin = parseInt(tokens['--duration-medium-min']);
+ const med = parseInt(tokens['--duration-medium']);
+ const medMax = parseInt(tokens['--duration-medium-max']);
+
+ expect(fastMin).toBeLessThan(fast);
+ expect(fast).toBeLessThan(fastMax);
+ expect(medMin).toBeLessThan(med);
+ expect(med).toBeLessThan(medMax);
+ expect(fastMax).toBeLessThan(medMin);
+ });
+});
diff --git a/packages/core/src/theme/expandMotionScale.ts b/packages/core/src/theme/expandMotionScale.ts
new file mode 100644
index 0000000000..5ca960ea07
--- /dev/null
+++ b/packages/core/src/theme/expandMotionScale.ts
@@ -0,0 +1,107 @@
+/**
+ * @file expandMotionScale.ts
+ * @input Motion scale configuration { fast, medium, ratio, easing? }
+ * @output Token overrides for duration and easing primitives
+ * @position Theme utility; consumed by defineTheme.ts
+ *
+ * Computes duration min/max variants from base values and a scaling ratio:
+ * min = base × ratio
+ * max = base / ratio
+ *
+ * This gives theme authors a simple 3-value interface (fast, medium, ratio)
+ * that expands into a coherent 6-token duration scale. A "snappy" theme
+ * lowers the base; a "cinematic" theme raises it — and the proportional
+ * relationships between variants are preserved automatically.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/expandMotionScale.test.ts
+ * - /packages/core/src/theme/defineTheme.ts
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Motion scale configuration.
+ *
+ * @example
+ * ```
+ * // Default XDS motion scale
+ * { fast: 175, medium: 410, ratio: 0.75 }
+ *
+ * // Snappy theme (reduced motion budget)
+ * { fast: 100, medium: 250, ratio: 0.75 }
+ *
+ * // Cinematic theme (dramatic animations)
+ * { fast: 200, medium: 500, ratio: 0.7 }
+ *
+ * // With custom easing
+ * { fast: 175, medium: 410, ratio: 0.75, easing: 'cubic-bezier(0.0, 0.0, 0.2, 1)' }
+ * ```
+ */
+export interface XDSMotionScaleConfig {
+ /** Base duration for micro-interactions in ms (hover, toggle, checkbox). */
+ fast: number;
+ /** Base duration for entrance/exit animations in ms (dialog, drawer, panel). */
+ medium: number;
+ /**
+ * Scaling ratio for min/max variants.
+ * min = base × ratio, max = base / ratio.
+ * Typical range: 0.65–0.85. Default: 0.75.
+ */
+ ratio: number;
+ /** Optional easing curve override for --easing-standard. */
+ easing?: string;
+}
+
+/** Token overrides produced by expandMotionScale. */
+export type MotionScaleTokens = Record<string, string>;
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+/**
+ * Round a duration in ms to the nearest 5ms for clean token values.
+ */
+function roundMs(ms: number): number {
+ return Math.round(ms / 5) * 5;
+}
+
+/**
+ * Expand a motion scale configuration into duration and easing token overrides.
+ *
+ * Duration computation:
+ * fast-min = fast × ratio (smallest micro-interaction)
+ * fast = fast (standard micro-interaction)
+ * fast-max = fast / ratio (slightly longer micro-interaction)
+ * medium-min = medium × ratio (quick entrance/exit)
+ * medium = medium (standard entrance/exit)
+ * medium-max = medium / ratio (dramatic entrance)
+ *
+ * @param config — Motion scale configuration
+ * @returns Token overrides to merge into the theme token map
+ */
+export function expandMotionScale(
+ config: XDSMotionScaleConfig,
+): MotionScaleTokens {
+ const {fast, medium, ratio, easing} = config;
+
+ const tokens: MotionScaleTokens = {
+ // Duration primitives
+ '--duration-fast-min': `${roundMs(fast * ratio)}ms`,
+ '--duration-fast': `${roundMs(fast)}ms`,
+ '--duration-fast-max': `${roundMs(fast / ratio)}ms`,
+ '--duration-medium-min': `${roundMs(medium * ratio)}ms`,
+ '--duration-medium': `${roundMs(medium)}ms`,
+ '--duration-medium-max': `${roundMs(medium / ratio)}ms`,
+ };
+
+ // Easing override (optional — default comes from easingDefaults)
+ if (easing) {
+ tokens['--easing-standard'] = easing;
+ }
+
+ return tokens;
+}
diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index 8b33e50ef7..50a5940da1 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -37,6 +37,12 @@ export type {
RadiusScaleTokens,
} from './expandRadiusScale';
+export {expandMotionScale} from './expandMotionScale';
+export type {
+ XDSMotionScaleConfig,
+ MotionScaleTokens,
+} from './expandMotionScale';
+
// Export token defaults and vars for use in custom components and themes
export {
colorDefaults,
diff --git a/packages/themes/brutalist/src/index.ts b/packages/themes/brutalist/src/index.ts
index 09e02752a7..5bc7e82dc4 100644
--- a/packages/themes/brutalist/src/index.ts
+++ b/packages/themes/brutalist/src/index.ts
@@ -14,6 +14,12 @@ export const brutalistTheme = defineTheme({
// Zero radius everywhere — multiplier 0 makes all scalable radii 0px
radiusScale: {base: 4, multiplier: 0},
+ // Motion scale: near-instant — brutalism doesn't wait.
+ // Produces: fast-min=50ms, fast=65ms, fast-max=85ms,
+ // medium-min=115ms, medium=150ms, medium-max=200ms.
+ // Linear easing — no curves, no polish, just movement.
+ motionScale: {fast: 65, medium: 150, ratio: 0.75, easing: 'linear'},
+
tokens: {
// Colors — high contrast, no subtlety
'--color-accent': ['#FF1493', '#FF69B4'],
diff --git a/packages/themes/default/src/defaultTheme.ts b/packages/themes/default/src/defaultTheme.ts
index 6ed6b5f8a1..0ebfd9efeb 100644
--- a/packages/themes/default/src/defaultTheme.ts
+++ b/packages/themes/default/src/defaultTheme.ts
@@ -21,6 +21,11 @@ export const defaultTheme = defineTheme({
// Generates all heading + text tokens AND component overrides automatically.
typeScale: {base: 14, ratio: 1.2},
+ // Motion scale: base durations from Ted's proposal (#674), ratio=0.75.
+ // Generates: fast-min=130ms, fast=175ms, fast-max=235ms,
+ // medium-min=310ms, medium=410ms, medium-max=545ms.
+ motionScale: {fast: 175, medium: 410, ratio: 0.75},
+
// The default theme uses the built-in token defaults from tokens.stylex.ts.
// No additional token overrides needed.
tokens: {},
diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.ts
index b710750e3a..6352e2ba6c 100644
--- a/packages/themes/neutral/src/neutralTheme.ts
+++ b/packages/themes/neutral/src/neutralTheme.ts
@@ -29,6 +29,11 @@ export const neutralTheme = defineTheme({
},
},
+ // Motion scale: snappier than default to match shadcn/Tailwind conventions.
+ // Produces: fast-min=95ms, fast=125ms, fast-max=165ms,
+ // medium-min=225ms, medium=300ms, medium-max=400ms.
+ motionScale: {fast: 125, medium: 300, ratio: 0.75},
+
tokens: {
// =========================================================================
// Colors — neutral grayscale palette using oklch