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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 themesexport {colorDefaults,diff --git a/packages/themes/brutalist/src/index.ts b/packages/themes/brutalist/src/index.tsindex 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 0pxradiusScale: {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.tsindex 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.tsindex 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