Skip to content

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

TypeScript

feat(tokens): add duration-slow band and update spinner (#1322)

Cindy Zhang077acb66b655
diff --git a/packages/core/src/Spinner/XDSSpinner.tsx b/packages/core/src/Spinner/XDSSpinner.tsx
index 967d2ed570..fe244ff6a3 100644
--- a/packages/core/src/Spinner/XDSSpinner.tsx
+++ b/packages/core/src/Spinner/XDSSpinner.tsx
@@ -64,7 +64,7 @@ const styles = stylex.create({
canvas: {
backfaceVisibility: 'hidden',
display: 'block',
- animationDuration: durationVars['--duration-medium-max'],
+ animationDuration: durationVars['--duration-slow-min'],
animationIterationCount: 'infinite',
animationName: rotation,
animationTimingFunction: 'linear',
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index d4c32598e9..9b24f442fa 100644
--- a/packages/core/src/theme/defineTheme.ts
+++ b/packages/core/src/theme/defineTheme.ts
@@ -186,12 +186,12 @@ export interface XDSDefineThemeInput {
*
* @example
* ```
- * motion: { fast: 175, medium: 410, ratio: 0.75 }
+ * motion: { fast: 175, medium: 410, slow: 975, 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 }
+ * // Default: { fast: 175, medium: 410, slow: 975, ratio: 0.75 }
+ * // Cinematic: { fast: 200, medium: 500, slow: 1200, ratio: 0.7 }
* ```
*/
motion?: XDSMotionScaleConfig;
@@ -898,7 +898,9 @@ export function generateOnMediaCSS(theme: XDSDefinedTheme): string {
const declarations = pseudoEntries
.map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)
.join('\n');
- parts.push(` ${baseSelector}${pseudo} {\n${declarations}\n }`);
+ parts.push(
+ ` ${baseSelector}${pseudo} {\n${declarations}\n }`,
+ );
}
}
}
@@ -934,7 +936,9 @@ export function generateThemeCSS(theme: XDSDefinedTheme): ThemeCSSOutput {
const onMediaCss = generateOnMediaCSS(theme);
if (onMediaCss) {
- componentCss = componentCss ? `${componentCss}\n\n${onMediaCss}` : onMediaCss;
+ componentCss = componentCss
+ ? `${componentCss}\n\n${onMediaCss}`
+ : onMediaCss;
}
return {prose: proseCss, component: componentCss};
diff --git a/packages/core/src/theme/expandMotionScale.test.ts b/packages/core/src/theme/expandMotionScale.test.ts
index f0d6ebbb36..1d5a5350ed 100644
--- a/packages/core/src/theme/expandMotionScale.test.ts
+++ b/packages/core/src/theme/expandMotionScale.test.ts
@@ -52,7 +52,7 @@ describe('expandMotionScale', () => {
expect(tokens['--ease-standard']).toBe('cubic-bezier(0.0, 0.0, 0.2, 1)');
});
- it('produces exactly 6 duration tokens', () => {
+ it('produces exactly 6 duration tokens without slow', () => {
const tokens = expandMotionScale({fast: 175, medium: 410, ratio: 0.75});
const durationKeys = Object.keys(tokens).filter(k =>
k.startsWith('--duration-'),
@@ -61,20 +61,66 @@ describe('expandMotionScale', () => {
expect(durationKeys).toHaveLength(6);
});
- it('maintains ordering: min < base < max', () => {
+ it('produces 9 duration tokens with slow', () => {
+ const tokens = expandMotionScale({
+ fast: 175,
+ medium: 410,
+ slow: 975,
+ ratio: 0.75,
+ });
+ const durationKeys = Object.keys(tokens).filter(k =>
+ k.startsWith('--duration-'),
+ );
+
+ expect(durationKeys).toHaveLength(9);
+ });
+
+ it('computes default slow band', () => {
+ const tokens = expandMotionScale({
+ fast: 175,
+ medium: 410,
+ slow: 975,
+ ratio: 0.75,
+ });
+
+ expect(tokens['--duration-slow-min']).toBe('730ms'); // 975 × 0.75 = 731.25 → 730
+ expect(tokens['--duration-slow']).toBe('975ms');
+ expect(tokens['--duration-slow-max']).toBe('1300ms'); // 975 / 0.75 = 1300 → 1300
+ });
+
+ it('does not emit slow tokens when slow is omitted', () => {
const tokens = expandMotionScale({fast: 175, medium: 410, ratio: 0.75});
+ expect(tokens['--duration-slow-min']).toBeUndefined();
+ expect(tokens['--duration-slow']).toBeUndefined();
+ expect(tokens['--duration-slow-max']).toBeUndefined();
+ });
+
+ it('maintains ordering: min < base < max', () => {
+ const tokens = expandMotionScale({
+ fast: 175,
+ medium: 410,
+ slow: 975,
+ 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']);
+ const slowMin = parseInt(tokens['--duration-slow-min']);
+ const slow = parseInt(tokens['--duration-slow']);
+ const slowMax = parseInt(tokens['--duration-slow-max']);
expect(fastMin).toBeLessThan(fast);
expect(fast).toBeLessThan(fastMax);
expect(medMin).toBeLessThan(med);
expect(med).toBeLessThan(medMax);
expect(fastMax).toBeLessThan(medMin);
+ expect(medMax).toBeLessThan(slowMin);
+ expect(slowMin).toBeLessThan(slow);
+ expect(slow).toBeLessThan(slowMax);
});
});
diff --git a/packages/core/src/theme/expandMotionScale.ts b/packages/core/src/theme/expandMotionScale.ts
index ad9da42976..a430f37fad 100644
--- a/packages/core/src/theme/expandMotionScale.ts
+++ b/packages/core/src/theme/expandMotionScale.ts
@@ -28,13 +28,13 @@
* @example
* ```
* // Default XDS motion scale
- * { fast: 175, medium: 410, ratio: 0.75 }
+ * { fast: 175, medium: 410, slow: 975, 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 }
+ * { fast: 200, medium: 500, slow: 1200, ratio: 0.7 }
*
* // With custom easing
* { fast: 175, medium: 410, ratio: 0.75, easing: 'cubic-bezier(0.0, 0.0, 0.2, 1)' }
@@ -45,6 +45,8 @@ export interface XDSMotionScaleConfig {
fast: number;
/** Base duration for entrance/exit animations in ms (dialog, drawer, panel). */
medium: number;
+ /** Base duration for slow/continuous animations in ms (spinner, progress). */
+ slow?: number;
/**
* Scaling ratio for min/max variants.
* min = base × ratio, max = base / ratio.
@@ -79,6 +81,9 @@ function roundMs(ms: number): number {
* medium-min = medium × ratio (quick entrance/exit)
* medium = medium (standard entrance/exit)
* medium-max = medium / ratio (dramatic entrance)
+ * slow-min = slow × ratio (quick continuous animation) [optional]
+ * slow = slow (standard continuous animation) [optional]
+ * slow-max = slow / ratio (relaxed continuous animation) [optional]
*
* @param config — Motion scale configuration
* @returns Token overrides to merge into the theme token map
@@ -86,7 +91,7 @@ function roundMs(ms: number): number {
export function expandMotionScale(
config: XDSMotionScaleConfig,
): MotionScaleTokens {
- const {fast, medium, ratio, easing} = config;
+ const {fast, medium, slow, ratio, easing} = config;
const tokens: MotionScaleTokens = {
// Duration primitives
@@ -98,6 +103,13 @@ export function expandMotionScale(
'--duration-medium-max': `${roundMs(medium / ratio)}ms`,
};
+ // Slow band (optional — only emitted when slow base is provided)
+ if (slow != null) {
+ tokens['--duration-slow-min'] = `${roundMs(slow * ratio)}ms`;
+ tokens['--duration-slow'] = `${roundMs(slow)}ms`;
+ tokens['--duration-slow-max'] = `${roundMs(slow / ratio)}ms`;
+ }
+
// Easing override (optional — default comes from easeDefaults)
if (easing) {
tokens['--ease-standard'] = easing;
diff --git a/packages/core/src/theme/tokens.stylex.ts b/packages/core/src/theme/tokens.stylex.ts
index 57e26919da..8514a8888f 100644
--- a/packages/core/src/theme/tokens.stylex.ts
+++ b/packages/core/src/theme/tokens.stylex.ts
@@ -243,6 +243,7 @@ export const shadowVars = stylex.defineVars(shadowDefaults);
// Motion Tokens — Duration
// =============================================================================
// Duration primitives: pick a duration that matches the visual weight.
+// Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous).
// min/max variants derive from base × ratio (default ratio ≈ 0.75).
// See motion in defineTheme for computed generation.
@@ -253,6 +254,9 @@ export const durationDefaults = {
'--duration-medium-min': '310ms',
'--duration-medium': '410ms',
'--duration-medium-max': '550ms',
+ '--duration-slow-min': '730ms',
+ '--duration-slow': '975ms',
+ '--duration-slow-max': '1300ms',
} as const;
export const durationVars = stylex.defineVars(durationDefaults);
diff --git a/packages/themes/brutalist/src/brutalistTheme.ts b/packages/themes/brutalist/src/brutalistTheme.ts
index c9a6dc3a11..5e7878ad05 100644
--- a/packages/themes/brutalist/src/brutalistTheme.ts
+++ b/packages/themes/brutalist/src/brutalistTheme.ts
@@ -23,7 +23,7 @@ export const brutalistTheme = defineTheme({
// 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.
- motion: {fast: 65, medium: 150, ratio: 0.75, easing: 'linear'},
+ motion: {fast: 65, medium: 150, slow: 350, ratio: 0.75, easing: 'linear'},
tokens: {
// Colors — high contrast, no subtlety
diff --git a/packages/themes/default/src/defaultTheme.ts b/packages/themes/default/src/defaultTheme.ts
index ab97da3c5d..20dd9503ed 100644
--- a/packages/themes/default/src/defaultTheme.ts
+++ b/packages/themes/default/src/defaultTheme.ts
@@ -50,7 +50,7 @@ export const defaultTheme = defineTheme({
// Motion: 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.
- motion: {fast: 175, medium: 410, ratio: 0.75},
+ motion: {fast: 175, medium: 410, slow: 975, ratio: 0.75},
// Syntax highlighting — tuned to the default palette
syntax: defaultSyntax,
diff --git a/packages/themes/meta/src/metaTheme.ts b/packages/themes/meta/src/metaTheme.ts
index f9e75de18a..53e74d55e1 100644
--- a/packages/themes/meta/src/metaTheme.ts
+++ b/packages/themes/meta/src/metaTheme.ts
@@ -31,7 +31,7 @@ export const metaTheme = defineTheme({
},
// Motion — default Meta timing
- motion: {fast: 175, medium: 410, ratio: 0.75},
+ motion: {fast: 175, medium: 410, slow: 975, ratio: 0.75},
tokens: {
// Type workaround: these tokens exist in core but aren't in XDSTokenName yet
@@ -243,7 +243,7 @@ export const metaTheme = defineTheme({
// Supporting — CDS: 13px / 400
'--text-supporting-size': '0.8125rem',
- '--text-supporting-leading': '1.5385'
+ '--text-supporting-leading': '1.5385',
},
components: {
@@ -289,7 +289,10 @@ export const metaTheme = defineTheme({
borderColor: 'light-dark(var(--color-accent), #4BA9FE)',
color: 'light-dark(var(--color-accent), #4BA9FE)',
fontWeight: '500',
- ':hover': {backgroundColor: 'light-dark(rgba(0,100,224,0.06), rgba(75,169,254,0.1))'},
+ ':hover': {
+ backgroundColor:
+ 'light-dark(rgba(0,100,224,0.06), rgba(75,169,254,0.1))',
+ },
':active': {opacity: '0.7'},
},
'variant:secondary-outline': {
@@ -299,7 +302,10 @@ export const metaTheme = defineTheme({
borderColor: 'light-dark(var(--color-border), #525456)',
color: 'light-dark(var(--color-text-primary), #F3F4F5)',
fontWeight: '500',
- ':hover': {backgroundColor: 'light-dark(rgba(0,0,0,0.04), rgba(255,255,255,0.06))'},
+ ':hover': {
+ backgroundColor:
+ 'light-dark(rgba(0,0,0,0.04), rgba(255,255,255,0.06))',
+ },
':active': {opacity: '0.7'},
},
'variant:destructive-outline': {
@@ -309,7 +315,10 @@ export const metaTheme = defineTheme({
borderColor: 'light-dark(var(--color-error), #FB7D87)',
color: 'light-dark(var(--color-error), #FB7D87)',
fontWeight: '500',
- ':hover': {backgroundColor: 'light-dark(rgba(211,17,48,0.06), rgba(251,125,135,0.1))'},
+ ':hover': {
+ backgroundColor:
+ 'light-dark(rgba(211,17,48,0.06), rgba(251,125,135,0.1))',
+ },
':active': {opacity: '0.7'},
},
},
@@ -328,7 +337,6 @@ export const metaTheme = defineTheme({
// Section — 20px padding
// =========================================================================
-
// =========================================================================
// Text input — CDS: 16px radius, 16px horizontal padding
// =========================================================================
@@ -470,8 +478,6 @@ export const metaTheme = defineTheme({
},
},
-
-
// =========================================================================
// Divider — opaque gray instead of transparent blue-gray
// =========================================================================
diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.ts
index 46d652b17e..a3b6617ddf 100644
--- a/packages/themes/neutral/src/neutralTheme.ts
+++ b/packages/themes/neutral/src/neutralTheme.ts
@@ -59,7 +59,7 @@ export const neutralTheme = defineTheme({
// Motion: 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.
- motion: {fast: 125, medium: 300, ratio: 0.75},
+ motion: {fast: 125, medium: 300, slow: 700, ratio: 0.75},
// Syntax highlighting — desaturated to match grayscale palette
syntax: neutralSyntax,
diff --git a/packages/themes/whatsapp/src/whatsappTheme.ts b/packages/themes/whatsapp/src/whatsappTheme.ts
index c68ec1cf03..385a6964c5 100644
--- a/packages/themes/whatsapp/src/whatsappTheme.ts
+++ b/packages/themes/whatsapp/src/whatsappTheme.ts
@@ -58,7 +58,7 @@ export const whatsappTheme = defineTheme({
// Motion: WhatsApp feels snappy but not jarring.
// Slightly faster than XDS default, with ease-out for natural deceleration.
- motion: {fast: 150, medium: 350, ratio: 0.75},
+ motion: {fast: 150, medium: 350, slow: 825, ratio: 0.75},
tokens: {
// =========================================================================