@carbon/motion 11.49.0 → 11.50.0

package/scss/generated/_tokens.scss

@@ -0,0 +1,99 @@
+// Code generated by @carbon/motion. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2026
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+/// Common component easings
+/// @type Map
+/// @access public
+/// @group @carbon/motion
+$easings: (
+  standard: (
+    productive: cubic-bezier(0.2, 0, 0.38, 0.9),
+    expressive: cubic-bezier(0.4, 0.14, 0.3, 1),
+  ),
+  entrance: (
+    productive: cubic-bezier(0, 0, 0.38, 0.9),
+    expressive: cubic-bezier(0, 0, 0.3, 1),
+  ),
+  exit: (
+    productive: cubic-bezier(0.2, 0, 1, 0.9),
+    expressive: cubic-bezier(0.4, 0.14, 1, 1),
+  ),
+) !default;
+
+/// Micro-interactions such as button and toggle. Instant response to user action.
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-fast-01: 70ms !default;
+
+/// Micro-interactions such as fade in. Subtle entrance or exit of small UI elements.
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-fast-02: 110ms !default;
+
+/// Micro-interactions, small expansion, short distance movements. Default transition speed.
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-moderate-01: 150ms !default;
+
+/// Expansion, system communication, toast. Slightly longer interactions with more visual weight.
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-moderate-02: 240ms !default;
+
+/// Large expansion, important system notifications. Deliberate, prominent transitions.
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-slow-01: 400ms !default;
+
+/// Background dimming, large hero transitions. Slow, immersive motion for maximum emphasis.
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-slow-02: 700ms !default;
+
+/// V10 backwards compatibility tokens
+/// @access public
+/// @deprecated
+/// @type Duration
+/// @group @carbon/motion
+$fast-01: $duration-fast-01 !default;
+
+/// @access public
+/// @deprecated
+/// @type Duration
+/// @group @carbon/motion
+$fast-02: $duration-fast-02 !default;
+
+/// @access public
+/// @deprecated
+/// @type Duration
+/// @group @carbon/motion
+$moderate-01: $duration-moderate-01 !default;
+
+/// @access public
+/// @deprecated
+/// @type Duration
+/// @group @carbon/motion
+$moderate-02: $duration-moderate-02 !default;
+
+/// @access public
+/// @deprecated
+/// @type Duration
+/// @group @carbon/motion
+$slow-01: $duration-slow-01 !default;
+
+/// @access public
+/// @deprecated
+/// @type Duration
+/// @group @carbon/motion
+$slow-02: $duration-slow-02 !default;

package/src/dtcg/motion.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://tr.designtokens.org/format/",
+  "$description": "Motion tokens for the Carbon Design System — durations and easing curves",
+  "duration": {
+    "fast": {
+      "01": {
+        "$type": "duration",
+        "$value": { "value": 70, "unit": "ms" },
+        "$description": "Micro-interactions such as button and toggle. Instant response to user action."
+      },
+      "02": {
+        "$type": "duration",
+        "$value": { "value": 110, "unit": "ms" },
+        "$description": "Micro-interactions such as fade in. Subtle entrance or exit of small UI elements."
+      }
+    },
+    "moderate": {
+      "01": {
+        "$type": "duration",
+        "$value": { "value": 150, "unit": "ms" },
+        "$description": "Micro-interactions, small expansion, short distance movements. Default transition speed."
+      },
+      "02": {
+        "$type": "duration",
+        "$value": { "value": 240, "unit": "ms" },
+        "$description": "Expansion, system communication, toast. Slightly longer interactions with more visual weight."
+      }
+    },
+    "slow": {
+      "01": {
+        "$type": "duration",
+        "$value": { "value": 400, "unit": "ms" },
+        "$description": "Large expansion, important system notifications. Deliberate, prominent transitions."
+      },
+      "02": {
+        "$type": "duration",
+        "$value": { "value": 700, "unit": "ms" },
+        "$description": "Background dimming, large hero transitions. Slow, immersive motion for maximum emphasis."
+      }
+    }
+  },
+  "easing": {
+    "standard": {
+      "productive": {
+        "$type": "cubicBezier",
+        "$value": [0.2, 0, 0.38, 0.9],
+        "$description": "Standard easing for productive motion. Used for UI elements that move within the viewport."
+      },
+      "expressive": {
+        "$type": "cubicBezier",
+        "$value": [0.4, 0.14, 0.3, 1],
+        "$description": "Standard easing for expressive motion. Used for elements with more prominent, fluid movement."
+      }
+    },
+    "entrance": {
+      "productive": {
+        "$type": "cubicBezier",
+        "$value": [0, 0, 0.38, 0.9],
+        "$description": "Entrance easing for productive motion. Used when elements enter the screen."
+      },
+      "expressive": {
+        "$type": "cubicBezier",
+        "$value": [0, 0, 0.3, 1],
+        "$description": "Entrance easing for expressive motion. Used for prominent element entrances."
+      }
+    },
+    "exit": {
+      "productive": {
+        "$type": "cubicBezier",
+        "$value": [0.2, 0, 1, 0.9],
+        "$description": "Exit easing for productive motion. Used when elements leave the screen."
+      },
+      "expressive": {
+        "$type": "cubicBezier",
+        "$value": [0.4, 0.14, 1, 1],
+        "$description": "Exit easing for expressive motion. Used for prominent element exits."
+      }
+    }
+  }
+}

package/src/dtcg/surfaces.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://tr.designtokens.org/format/",
+  "$description": "Motion surface recipes for Carbon — composite transition intents built from primitive duration and easing tokens.",
+  "surface": {
+    "disclosure": {
+      "$type": "transition",
+      "$value": {
+        "duration": "{duration.moderate.01}",
+        "delay": { "value": 0, "unit": "ms" },
+        "timingFunction": "{easing.entrance.productive}"
+      },
+      "$description": "Accordion, table-row expand — reveal in place.",
+      "$extensions": {
+        "carbon.motion": {
+          "kind": "reveal",
+          "duration": "moderate-01",
+          "enter": { "blockSize": "auto", "opacity": 1 },
+          "exit": { "blockSize": 0, "opacity": 0 },
+          "enterEasing": ["entrance", "productive"],
+          "exitEasing": ["exit", "productive"]
+        }
+      }
+    },
+    "contextual": {
+      "$type": "transition",
+      "$value": {
+        "duration": "{duration.fast.02}",
+        "delay": { "value": 0, "unit": "ms" },
+        "timingFunction": "{easing.entrance.expressive}"
+      },
+      "$description": "Icon → tooltip/popover — fade and scale reveal.",
+      "$extensions": {
+        "carbon.motion": {
+          "kind": "reveal",
+          "duration": "fast-02",
+          "enter": { "opacity": 1, "transform": "scale(1)" },
+          "exit": { "opacity": 0, "transform": "scale(0.96)" },
+          "enterEasing": ["entrance", "expressive"],
+          "exitEasing": ["exit", "expressive"]
+        }
+      }
+    },
+    "stretch": {
+      "$type": "transition",
+      "$value": {
+        "duration": "{duration.slow.01}",
+        "delay": { "value": 0, "unit": "ms" },
+        "timingFunction": "{easing.entrance.expressive}"
+      },
+      "$description": "Component reveal stretching from the vertical axis.",
+      "$extensions": {
+        "carbon.motion": {
+          "kind": "reveal",
+          "duration": "slow-01",
+          "enter": { "opacity": 1, "clipPath": "inset(0 0 0 0)" },
+          "exit": { "opacity": 0, "clipPath": "inset(50% 0 50% 0)" },
+          "enterEasing": ["entrance", "expressive"],
+          "exitEasing": ["exit", "expressive"]
+        }
+      }
+    },
+    "expand": {
+      "$type": "transition",
+      "$value": {
+        "duration": "{duration.moderate.02}",
+        "delay": { "value": 0, "unit": "ms" },
+        "timingFunction": "{easing.standard.productive}"
+      },
+      "$description": "Card/tile → side-panel/tearsheet — shared-element morph.",
+      "$extensions": {
+        "carbon.motion": {
+          "kind": "shared-element",
+          "duration": "moderate-02",
+          "enter": { "opacity": 1, "transform": "scale(1)" },
+          "exit": { "opacity": 0, "transform": "scale(0.96)" },
+          "enterEasing": ["standard", "productive"],
+          "exitEasing": ["standard", "productive"]
+        }
+      }
+    },
+    "invoke": {
+      "$type": "transition",
+      "$value": {
+        "duration": "{duration.moderate.02}",
+        "delay": { "value": 0, "unit": "ms" },
+        "timingFunction": "{easing.standard.expressive}"
+      },
+      "$description": "Button → modal/menu/popover — shared-element morph from the trigger.",
+      "$extensions": {
+        "carbon.motion": {
+          "kind": "shared-element",
+          "origin": "trigger",
+          "duration": "moderate-02",
+          "enterEasing": ["standard", "expressive"],
+          "exitEasing": ["standard", "expressive"]
+        }
+      }
+    }
+  }
+}

package/src/surfaces.ts

@@ -5,15 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type { DurationName, EasingMode, EasingName } from './tokens';
+// Surface definitions are generated from src/dtcg/surfaces.json by
+// `yarn build:tokens` (tasks/build.js) and written to
+// js/generated/surfaces.js before this file is bundled.
+// Run `yarn build` to regenerate them.
+export { surfaces, getMotionSurface } from '../js/generated/surfaces.js';
+
+// ── TypeScript types ─────────────────────────────────────────────────────────
+// These are hand-authored here rather than generated because they describe the
+// Carbon-specific structure of a surface recipe and are referenced by consumers
+// who need to type-check against the surface API.
+
+import type { DurationName, EasingName, EasingMode } from './tokens';
 
 type MotionEasing = readonly [EasingName, EasingMode];
 
-/**
- * from/to styles for reveal surface - plain CSS property/value pairs
- * keep values engine-neutral so CSS, WAAPI, and Motion can all consume
- * them
- */
+// from/to styles for reveal surface - plain CSS property/value pairs
+// keep values engine-neutral so CSS, WAAPI, and Motion can all consume them
 type RevealKeyframe = Record<string, string | number>;
 
 interface MotionSurfaceBase {
@@ -43,74 +51,9 @@ interface SharedElementSurface extends MotionSurfaceBase {
 }
 
 export type MotionSurfaceDefinition = SharedElementSurface | RevealSurface;
-
-/**
- * Named motion intents. These definitions are engine and framework agnostic.
- *
- * `prefers-reduced-motion` is intentionally not represented here: surfaces
- * never animate when the users request reduced motion. Framework adapters
- * bail before running, and the Sass output is wrapped in a
- * `prefers-reduced-motion: no-preference` media query
- */
-export const surfaces = {
-  // Accordion, table-row expand - reveal in place
-  disclosure: {
-    kind: 'reveal',
-    duration: 'moderate-01',
-    enter: { blockSize: 'auto', opacity: 1 },
-    exit: { blockSize: 0, opacity: 0 },
-    enterEasing: ['entrance', 'productive'],
-    exitEasing: ['exit', 'productive'],
-  },
-  // Icon > tooltip/popover
-  contextual: {
-    kind: 'reveal',
-    duration: 'fast-02',
-    enter: { opacity: 1, transform: 'scale(1)' },
-    exit: { opacity: 0, transform: 'scale(0.96)' },
-    enterEasing: ['entrance', 'expressive'],
-    exitEasing: ['exit', 'expressive'],
-  },
-  // Component reveal, "stretching" from vertical axis
-  stretch: {
-    kind: 'reveal',
-    duration: 'slow-01',
-    enter: { opacity: 1, clipPath: 'inset(0 0 0 0)' },
-    exit: { opacity: 0, clipPath: 'inset(50% 0 50% 0)' },
-    enterEasing: ['entrance', 'expressive'],
-    exitEasing: ['exit', 'expressive'],
-  },
-  // Card/tile > side-panel/tearsheet
-  expand: {
-    kind: 'shared-element',
-    duration: 'moderate-02',
-    enter: { opacity: 1, transform: 'scale(1)' },
-    exit: { opacity: 0, transform: 'scale(0.96)' },
-    enterEasing: ['standard', 'productive'],
-    exitEasing: ['standard', 'productive'],
-  },
-  // Button > modal/menu/popover - morphs from the trigger
-  invoke: {
-    kind: 'shared-element',
-    origin: 'trigger',
-    duration: 'moderate-02',
-    enterEasing: ['standard', 'expressive'],
-    exitEasing: ['standard', 'expressive'],
-  },
-} as const satisfies Record<string, MotionSurfaceDefinition>;
-
-export type MotionSurfaceName = keyof typeof surfaces;
-
-// Give JavaScript consumers a clear error for an unknown surface name.
-export const getMotionSurface = (name: MotionSurfaceName) => {
-  const surface = surfaces[name];
-
-  if (!surface) {
-    throw new Error(
-      `Unable to find motion surface \`${name}\`. Expected one of: ` +
-        Object.keys(surfaces).join(', ')
-    );
-  }
-
-  return surface;
-};
+export type MotionSurfaceName =
+  | 'disclosure'
+  | 'contextual'
+  | 'stretch'
+  | 'expand'
+  | 'invoke';

package/src/tokens.ts

@@ -5,35 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export const fast01 = '70ms';
-export const fast02 = '110ms';
-export const moderate01 = '150ms';
-export const moderate02 = '240ms';
-export const slow01 = '400ms';
-export const slow02 = '700ms';
-
-// V11 Tokens
-export const durationFast01 = fast01;
-export const durationFast02 = fast02;
-export const durationModerate01 = moderate01;
-export const durationModerate02 = moderate02;
-export const durationSlow01 = slow01;
-export const durationSlow02 = slow02;
-
-export const unstable_tokens = [
-  'fast01',
-  'fast02',
-  'moderate01',
-  'moderate02',
-  'slow01',
-  'slow02',
-  'durationFast01',
-  'durationFast02',
-  'durationModerate01',
-  'durationModerate02',
-  'durationSlow01',
-  'durationSlow02',
-] as const;
+// Token values are generated from src/dtcg/motion.json by `yarn build:tokens`
+// (tasks/build.js) and written to js/generated/tokens.js before this file is
+// bundled. Run `yarn build` to regenerate them.
+import {
+  durationFast01,
+  durationFast02,
+  durationModerate01,
+  durationModerate02,
+  durationSlow01,
+  durationSlow02,
+  easings,
+} from '../js/generated/tokens.js';
+
+export {
+  durationFast01,
+  durationFast02,
+  durationModerate01,
+  durationModerate02,
+  durationSlow01,
+  durationSlow02,
+  fast01,
+  fast02,
+  moderate01,
+  moderate02,
+  slow01,
+  slow02,
+  easings,
+  unstable_tokens,
+} from '../js/generated/tokens.js';
 
 export type DurationName =
   | 'fast-01'
@@ -43,6 +43,11 @@ export type DurationName =
   | 'slow-01'
   | 'slow-02';
 
+export type EasingName = 'standard' | 'entrance' | 'exit';
+export type EasingMode = 'productive' | 'expressive';
+export type CubicBezier = readonly [number, number, number, number];
+export type EasingMap = Record<EasingName, Record<EasingMode, string>>;
+
 // Map the surface names to the existing Carbon duration tokens.
 const durations: Record<DurationName, string> = {
   'fast-01': durationFast01,
@@ -53,13 +58,10 @@ const durations: Record<DurationName, string> = {
   'slow-02': durationSlow02,
 };
 
-export type EasingName = 'standard' | 'entrance' | 'exit';
-export type EasingMode = 'productive' | 'expressive';
-export type CubicBezier = readonly [number, number, number, number];
-export type EasingMap = Record<EasingName, Record<EasingMode, string>>;
 type EasingCurveMap = Record<EasingName, Record<EasingMode, CubicBezier>>;
 
 // Keep one numeric source for every Carbon easing curve.
+// Used by resolveEasing() — surfaces need raw numeric arrays, not CSS strings.
 const easingCurves: EasingCurveMap = {
   standard: {
     productive: [0.2, 0, 0.38, 0.9],
@@ -75,40 +77,20 @@ const easingCurves: EasingCurveMap = {
   },
 };
 
-const formatEasing = (curve: CubicBezier) =>
-  `cubic-bezier(${curve.join(', ')})`;
-
-export const easings: EasingMap = {
-  standard: {
-    productive: formatEasing(easingCurves.standard.productive),
-    expressive: formatEasing(easingCurves.standard.expressive),
-  },
-  entrance: {
-    productive: formatEasing(easingCurves.entrance.productive),
-    expressive: formatEasing(easingCurves.entrance.expressive),
-  },
-  exit: {
-    productive: formatEasing(easingCurves.exit.productive),
-    expressive: formatEasing(easingCurves.exit.expressive),
-  },
-};
-
 export const motion = (name: EasingName, mode: EasingMode) => {
-  if (!easings[name]) {
+  const easing = easings[name];
+  if (!easing) {
     throw new Error(
       `Unable to find easing \`${name}\` in our supported easings. Expected ` +
         `one of: ${Object.keys(easings).join(', ')}`
     );
   }
-
-  const easing = easings[name];
   if (!easing[mode]) {
     throw new Error(
       `Unable to find a mode for the easing \`${name}\` called: \`${mode}\`. ` +
         `Expected one of: ${Object.keys(easing).join(', ')}`
     );
   }
-
   return easing[mode];
 };