@carbon/motion 11.51.0-rc.0 → 11.52.0-rc.0

package/js/generated/tokens.d.ts

@@ -36,4 +36,4 @@ export declare const slow02: string;
 // Easing tokens
 export declare const easings: Record<'standard' | 'entrance' | 'exit', Record<'productive' | 'expressive', string>>;
 
-export declare const unstable_tokens: readonly string[];
+export declare const unstable_tokens: readonly string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carbon/motion",
   "description": "Motion helpers for digital and software products using the Carbon Design System",
-  "version": "11.51.0-rc.0",
+  "version": "11.52.0-rc.0",
   "license": "Apache-2.0",
   "sideEffects": [
     "index.scss",
@@ -38,13 +38,14 @@
     "postinstall": "ibmtelemetry --config=telemetry.yml"
   },
   "devDependencies": {
-    "@carbon/cli": "^11.49.0-rc.0",
+    "@carbon/cli": "^11.50.0-rc.0",
     "rimraf": "^6.0.1",
+    "style-dictionary": "^5.5.0",
     "typescript": "^6.0.3",
     "typescript-config-carbon": "^0.11.0"
   },
   "dependencies": {
     "@ibm/telemetry-js": "^1.5.0"
   },
-  "gitHead": "e848b98936051ac0026fb83551c91bfe603c589c"
+  "gitHead": "474482a993dff6b9085309aa4bc8484cf71b1612"
 }

package/style-dictionary/formats/js-surfaces.js

@@ -0,0 +1,154 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Emits `js/generated/surfaces.{js,d.ts}` from surfaces.json.
+ *
+ * Surface data lives in `$extensions["carbon.motion"]` on each leaf token —
+ * not in `$value` — so Style Dictionary cannot derive the output from the
+ * token value alone.  This format reads surfaces.json directly (the same
+ * pattern used by `carbon/scss-tokens` in @carbon/themes, which reads Carbon
+ * JS metadata directly instead of using SD token values).
+ *
+ * Two files are emitted by wiring this format into two SD `files` entries
+ * that differ only in `options.output` ('js' | 'dts').
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { toDtsTypeLiteral } = require('../utils/dts-type-literal');
+
+const FILE_BANNER = `// 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.
+`;
+
+// Path is resolved relative to this file (style-dictionary/formats/) → src/dtcg/
+const SURFACES_PATH = path.resolve(__dirname, '../../src/dtcg/surfaces.json');
+
+/**
+ * Collect surface entries from surfaces.json.
+ * Each surface node carries `$extensions["carbon.motion"]` with the recipe.
+ *
+ * @returns {Array<{ name: string, description: string, recipe: object }>}
+ */
+function collectSurfaces() {
+  const dtcg = JSON.parse(fs.readFileSync(SURFACES_PATH, 'utf8'));
+  const results = [];
+
+  function traverse(obj, pathSegments) {
+    for (const [key, value] of Object.entries(obj)) {
+      if (key.startsWith('$')) continue;
+      const segments = [...pathSegments, key];
+      if (
+        value &&
+        typeof value === 'object' &&
+        value.$extensions &&
+        value.$extensions['carbon.motion']
+      ) {
+        results.push({
+          name: segments.join('-'),
+          description: value.$description || '',
+          recipe: value.$extensions['carbon.motion'],
+        });
+      } else if (value && typeof value === 'object') {
+        traverse(value, segments);
+      }
+    }
+  }
+
+  traverse(dtcg, []);
+  return results;
+}
+
+/**
+ * @param {{ options: object }} args
+ * @returns {string}
+ */
+function carbonJsMotionSurfacesFormat({ options }) {
+  const outputMode = options?.output ?? 'js'; // 'js' | 'dts'
+
+  const surfaceList = collectSurfaces();
+  // Drop the leading "surface-" prefix from the export name.
+  const surfaceNames = surfaceList.map(({ name }) =>
+    name.startsWith('surface-') ? name.slice('surface-'.length) : name
+  );
+
+  const lines = [FILE_BANNER];
+
+  // ── Individual named surface exports ─────────────────────────────────────
+  for (let i = 0; i < surfaceList.length; i++) {
+    const { description, recipe } = surfaceList[i];
+    const exportName = surfaceNames[i];
+
+    if (description) {
+      lines.push(`/** ${description} */`);
+    }
+    if (outputMode === 'js') {
+      lines.push(
+        `export const ${exportName} = ${JSON.stringify(recipe, null, 2)};`
+      );
+    } else {
+      lines.push(
+        `export declare const ${exportName}: ${toDtsTypeLiteral(recipe)};`
+      );
+    }
+    lines.push('');
+  }
+
+  // ── surfaces map ─────────────────────────────────────────────────────────
+  if (outputMode === 'js') {
+    lines.push('export const surfaces = {');
+    for (const name of surfaceNames) {
+      lines.push(`  ${name},`);
+    }
+    lines.push('};');
+    lines.push('');
+  } else {
+    lines.push('export declare const surfaces: {');
+    for (const name of surfaceNames) {
+      lines.push(`  ${name}: typeof ${name};`);
+    }
+    lines.push('};');
+    lines.push('');
+  }
+
+  // ── getMotionSurface ──────────────────────────────────────────────────────
+  if (outputMode === 'js') {
+    lines.push(
+      `export function getMotionSurface(name) {`,
+      `  const surface = surfaces[name];`,
+      `  if (!surface) {`,
+      `    throw new Error(`,
+      `      \`Unable to find motion surface \\\`\${name}\\\`. Expected one of: \${Object.keys(surfaces).join(', ')}\``,
+      `    );`,
+      `  }`,
+      `  return surface;`,
+      `}`,
+      ``
+    );
+  } else {
+    lines.push(
+      `export declare function getMotionSurface(name: ${surfaceNames
+        .map((n) => `'${n}'`)
+        .join(' | ')}): (typeof surfaces)[typeof name];`,
+      ``
+    );
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  name: 'carbon/motion-js-surfaces',
+  format: carbonJsMotionSurfacesFormat,
+};

package/style-dictionary/formats/js-tokens.js

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Emits `js/generated/tokens.{js,d.ts}` from the motion DTCG tokens.
+ *
+ * The format receives all resolved tokens (duration + easing) and produces:
+ *   - V11 duration exports        (durationFast01, durationFast02, …)
+ *   - V10 deprecated aliases      (fast01, fast02, …)
+ *   - `easings` nested object     ({ standard: { productive, expressive }, … })
+ *   - `unstable_tokens` array
+ *
+ * Two files are emitted by wiring this format into two SD `files` entries
+ * that differ only in `options.output` ('js' | 'dts').
+ */
+
+const FILE_BANNER = `// 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.
+`;
+
+/**
+ * Convert kebab-case to camelCase.
+ * @param {string} str
+ * @returns {string}
+ */
+function kebabToCamel(str) {
+  return str.replace(/-([a-z0-9])/gi, (_, ch) => ch.toUpperCase());
+}
+
+/**
+ * Derive the V10 camelCase alias name from a V11 camelCase name.
+ * e.g. 'durationFast01' → 'fast01'
+ */
+function toV10CamelName(v11Camel) {
+  // Strip the leading 'duration' prefix and lowercase the first char.
+  const withoutPrefix = v11Camel.slice('duration'.length);
+  return withoutPrefix.charAt(0).toLowerCase() + withoutPrefix.slice(1);
+}
+
+/**
+ * @param {{ dictionary: import('style-dictionary').Dictionary, options: object }} args
+ * @returns {string}
+ */
+function carbonJsMotionTokensFormat({ dictionary, options }) {
+  const outputMode = options?.output ?? 'js'; // 'js' | 'dts'
+
+  // Build a lookup from kebab token name → resolved value
+  const tokenMap = new Map(
+    dictionary.allTokens.map((t) => [t.name, t.value ?? t.$value])
+  );
+
+  const lines = [FILE_BANNER];
+
+  // ── Duration tokens (V11 canonical) ──────────────────────────────────────
+  lines.push('// Duration tokens (V11)');
+  const durationTokens = dictionary.allTokens.filter((t) =>
+    t.name.startsWith('duration-')
+  );
+  const durationCamels = [];
+
+  for (const token of durationTokens) {
+    const camel = kebabToCamel(token.name);
+    durationCamels.push(camel);
+    const value = token.value ?? token.$value;
+    const description = token.$description ?? token.description ?? '';
+
+    if (description) {
+      lines.push(`/** ${description} */`);
+    }
+    if (outputMode === 'js') {
+      lines.push(`export const ${camel} = '${value}';`);
+    } else {
+      lines.push(`export declare const ${camel}: string;`);
+    }
+  }
+
+  // ── Duration tokens (V10 deprecated aliases) ──────────────────────────────
+  lines.push('');
+  lines.push('// Duration tokens (V10 — deprecated aliases)');
+  const v10Camels = [];
+
+  for (const v11Camel of durationCamels) {
+    const v10Camel = toV10CamelName(v11Camel);
+    v10Camels.push(v10Camel);
+
+    if (outputMode === 'js') {
+      lines.push(`/** @deprecated Use \`${v11Camel}\` instead */`);
+      lines.push(`export const ${v10Camel} = ${v11Camel};`);
+    } else {
+      lines.push(`/** @deprecated Use \`${v11Camel}\` instead */`);
+      lines.push(`export declare const ${v10Camel}: string;`);
+    }
+  }
+
+  // ── Easing map ────────────────────────────────────────────────────────────
+  lines.push('');
+  lines.push('// Easing tokens');
+
+  if (outputMode === 'dts') {
+    lines.push(
+      "export declare const easings: Record<'standard' | 'entrance' | 'exit', Record<'productive' | 'expressive', string>>;"
+    );
+  } else {
+    lines.push('export const easings = {');
+    for (const easingName of ['standard', 'entrance', 'exit']) {
+      lines.push(`  ${easingName}: {`);
+      for (const mode of ['productive', 'expressive']) {
+        const key = `easing-${easingName}-${mode}`;
+        const value = tokenMap.get(key);
+        if (value === undefined) {
+          throw new Error(`Missing SD token: ${key}`);
+        }
+        lines.push(`    ${mode}: '${value}',`);
+      }
+      lines.push(`  },`);
+    }
+    lines.push('};');
+  }
+
+  // ── unstable_tokens ───────────────────────────────────────────────────────
+  lines.push('');
+  if (outputMode === 'dts') {
+    lines.push('export declare const unstable_tokens: readonly string[];');
+  } else {
+    lines.push('export const unstable_tokens = [');
+    for (const camel of durationCamels) lines.push(`  '${camel}',`);
+    for (const v10 of v10Camels) lines.push(`  '${v10}',`);
+    lines.push('];');
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = {
+  name: 'carbon/motion-js-tokens',
+  format: carbonJsMotionTokensFormat,
+};

package/style-dictionary/formats/scss-surfaces.js

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Emits `scss/generated/_surfaces.scss` from surfaces.json.
+ *
+ * Surface data lives in `$extensions["carbon.motion"]` on each leaf token —
+ * not in `$value` — so Style Dictionary cannot derive the output from the
+ * token value alone.  This format reads surfaces.json directly (the same
+ * pattern used by `carbon/scss-tokens` in @carbon/themes, which reads Carbon
+ * JS metadata directly instead of using SD token values).
+ *
+ * Generates:
+ *   $surfaces: (
+ *     disclosure: ( kind: 'reveal', duration: 'moderate-01', … ),
+ *     …
+ *   );
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const FILE_BANNER = `// 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.
+//
+`;
+
+// Path is resolved relative to this file (style-dictionary/formats/) → src/dtcg/
+const SURFACES_PATH = path.resolve(__dirname, '../../src/dtcg/surfaces.json');
+
+/**
+ * Collect surface entries from surfaces.json.
+ *
+ * @returns {Array<{ name: string, description: string, recipe: object }>}
+ */
+function collectSurfaces() {
+  const dtcg = JSON.parse(fs.readFileSync(SURFACES_PATH, 'utf8'));
+  const results = [];
+
+  function traverse(obj, pathSegments) {
+    for (const [key, value] of Object.entries(obj)) {
+      if (key.startsWith('$')) continue;
+      const segments = [...pathSegments, key];
+      if (
+        value &&
+        typeof value === 'object' &&
+        value.$extensions &&
+        value.$extensions['carbon.motion']
+      ) {
+        results.push({
+          name: segments.join('-'),
+          description: value.$description || '',
+          recipe: value.$extensions['carbon.motion'],
+        });
+      } else if (value && typeof value === 'object') {
+        traverse(value, segments);
+      }
+    }
+  }
+
+  traverse(dtcg, []);
+  return results;
+}
+
+/**
+ * Convert a camelCase JS key to kebab-case for Sass.
+ * e.g. "enterEasing" → "enter-easing", "blockSize" → "block-size"
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function camelToKebab(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/**
+ * Serialise a JS recipe value to a Sass map / list / string literal.
+ * Arrays become Sass lists, plain objects become Sass maps, numbers stay
+ * numeric, strings get single-quoted.
+ *
+ * @param {*} value
+ * @param {number} [indent=0]
+ * @returns {string}
+ */
+function toSassLiteral(value, indent = 0) {
+  const pad = '  '.repeat(indent);
+  const innerPad = '  '.repeat(indent + 1);
+
+  if (Array.isArray(value)) {
+    const items = value.map((v) => toSassLiteral(v, 0)).join(', ');
+    return `(${items})`;
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value)
+      .map(
+        ([k, v]) =>
+          `${innerPad}${camelToKebab(k)}: ${toSassLiteral(v, indent + 1)}`
+      )
+      .join(',\n');
+    return `(\n${entries},\n${pad})`;
+  }
+
+  if (typeof value === 'number') return String(value);
+
+  // string — single-quote it
+  return `'${String(value)}'`;
+}
+
+/**
+ * @returns {string}
+ */
+function carbonScssMotionSurfacesFormat() {
+  const surfaceList = collectSurfaces();
+  const lines = [FILE_BANNER];
+
+  lines.push('$surfaces: (');
+
+  for (const { name, recipe } of surfaceList) {
+    // "surface-disclosure" → "disclosure"
+    const surfaceName = name.startsWith('surface-')
+      ? name.slice('surface-'.length)
+      : name;
+
+    lines.push(`  ${surfaceName}: (`);
+    for (const [key, value] of Object.entries(recipe)) {
+      const sassKey = camelToKebab(key);
+      lines.push(`    ${sassKey}: ${toSassLiteral(value, 2)},`);
+    }
+    lines.push(`  ),`);
+  }
+
+  lines.push(');');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  name: 'carbon/motion-scss-surfaces',
+  format: carbonScssMotionSurfacesFormat,
+};

package/style-dictionary/formats/scss-tokens.js

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Emits `scss/generated/_tokens.scss` from the motion DTCG tokens.
+ *
+ * Generates:
+ *   - `$easings` Sass map  (standard/entrance/exit × productive/expressive)
+ *   - V11 `$duration-*` variables
+ *   - V10 `$fast-*` / `$moderate-*` / `$slow-*` deprecated aliases
+ */
+
+const FILE_BANNER = `// 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.
+//
+`;
+
+/**
+ * @param {{ dictionary: import('style-dictionary').Dictionary }} args
+ * @returns {string}
+ */
+function carbonScssMotionTokensFormat({ dictionary }) {
+  // Build a lookup from kebab token name → resolved value
+  const tokenMap = new Map(
+    dictionary.allTokens.map((t) => [t.name, t.value ?? t.$value])
+  );
+
+  const lines = [FILE_BANNER];
+
+  // ── $easings map ──────────────────────────────────────────────────────────
+  lines.push('/// Common component easings');
+  lines.push('/// @type Map');
+  lines.push('/// @access public');
+  lines.push('/// @group @carbon/motion');
+  lines.push('$easings: (');
+  for (const easingName of ['standard', 'entrance', 'exit']) {
+    lines.push(`  ${easingName}: (`);
+    for (const mode of ['productive', 'expressive']) {
+      const key = `easing-${easingName}-${mode}`;
+      const value = tokenMap.get(key);
+      if (value === undefined) {
+        throw new Error(`Missing SD token: ${key}`);
+      }
+      lines.push(`    ${mode}: ${value},`);
+    }
+    lines.push(`  ),`);
+  }
+  lines.push(') !default;');
+  lines.push('');
+
+  // ── V11 duration variables ────────────────────────────────────────────────
+  const durationTokens = dictionary.allTokens.filter((t) =>
+    t.name.startsWith('duration-')
+  );
+
+  for (const token of durationTokens) {
+    const description = token.$description ?? token.description ?? '';
+    if (description) lines.push(`/// ${description}`);
+    lines.push('/// @access public');
+    lines.push('/// @type Duration');
+    lines.push('/// @group @carbon/motion');
+    lines.push(`$${token.name}: ${token.value ?? token.$value} !default;`);
+    lines.push('');
+  }
+
+  // ── V10 deprecated aliases ────────────────────────────────────────────────
+  lines.push('/// V10 backwards compatibility tokens');
+  const v10Map = {
+    'duration-fast-01': 'fast-01',
+    'duration-fast-02': 'fast-02',
+    'duration-moderate-01': 'moderate-01',
+    'duration-moderate-02': 'moderate-02',
+    'duration-slow-01': 'slow-01',
+    'duration-slow-02': 'slow-02',
+  };
+  for (const [v11, v10] of Object.entries(v10Map)) {
+    lines.push('/// @access public');
+    lines.push('/// @deprecated');
+    lines.push('/// @type Duration');
+    lines.push('/// @group @carbon/motion');
+    lines.push(`$${v10}: $${v11} !default;`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  name: 'carbon/motion-scss-tokens',
+  format: carbonScssMotionTokensFormat,
+};

package/style-dictionary/sd.config.js

@@ -0,0 +1,220 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Style Dictionary configuration for @carbon/motion.
+ *
+ * Wires together the custom plugins in this directory and drives two separate
+ * builds:
+ *
+ *   runJs()   → js/generated/tokens.{js,d.ts}
+ *               js/generated/surfaces.{js,d.ts}
+ *
+ *   runScss() → scss/generated/_tokens.scss
+ *               scss/generated/_surfaces.scss
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { default: StyleDictionary } = require('style-dictionary');
+
+// ── Custom plugins ─────────────────────────────────────────────────────────
+const carbonMotionDuration = require('./transforms/duration');
+const carbonMotionCubicBezier = require('./transforms/cubic-bezier');
+const carbonJsMotionTokens = require('./formats/js-tokens');
+const carbonJsMotionSurfaces = require('./formats/js-surfaces');
+const carbonScssMotionTokens = require('./formats/scss-tokens');
+const carbonScssMotionSurfaces = require('./formats/scss-surfaces');
+
+// ── Paths ──────────────────────────────────────────────────────────────────
+const ROOT = path.resolve(__dirname, '..');
+const DTCG_DIR = path.join(ROOT, 'src', 'dtcg');
+const SCSS_GENERATED = path.join(ROOT, 'scss', 'generated');
+const JS_GENERATED = path.join(ROOT, 'js', 'generated');
+
+// ── Custom name transform ──────────────────────────────────────────────────
+//
+// Builds a kebab-case name from the token path segments.
+// e.g. ['duration', 'fast', '01'] → 'duration-fast-01'
+//      ['easing', 'standard', 'productive'] → 'easing-standard-productive'
+const carbonMotionNameKebab = {
+  name: 'carbon/motion-name-kebab',
+  type: 'name',
+  transform(token) {
+    return token.path.join('-');
+  },
+};
+
+// ── Transform group ────────────────────────────────────────────────────────
+const CARBON_MOTION_TRANSFORMS = [
+  'attribute/cti',
+  'carbon/motion-name-kebab',
+  'carbon/motion-duration',
+  'carbon/motion-cubic-bezier',
+];
+
+// ── SD configs ────────────────────────────────────────────────────────────
+//
+// Separate configs are used for JS and SCSS so that `runJs()` and `runScss()`
+// only invoke their respective platforms, matching the themes pattern where
+// each build step is independently callable.
+
+// motion.json — JS output
+const jsTokensConfig = {
+  source: [path.join(DTCG_DIR, 'motion.json')],
+  platforms: {
+    'js/tokens': {
+      transformGroup: 'carbon/motion',
+      buildPath: JS_GENERATED + '/',
+      files: [
+        {
+          destination: 'tokens.js',
+          format: 'carbon/motion-js-tokens',
+          options: { output: 'js' },
+        },
+        {
+          destination: 'tokens.d.ts',
+          format: 'carbon/motion-js-tokens',
+          options: { output: 'dts' },
+        },
+      ],
+    },
+  },
+};
+
+// motion.json — SCSS output
+const scssTokensConfig = {
+  source: [path.join(DTCG_DIR, 'motion.json')],
+  platforms: {
+    'scss/tokens': {
+      transformGroup: 'carbon/motion',
+      buildPath: SCSS_GENERATED + '/',
+      files: [
+        {
+          destination: '_tokens.scss',
+          format: 'carbon/motion-scss-tokens',
+        },
+      ],
+    },
+  },
+};
+
+// surfaces.json — JS output
+//
+// Surfaces are processed by their formats reading surfaces.json directly;
+// SD still manages the build lifecycle and output directory creation.
+// motion.json is included so SD can resolve the alias references in
+// surfaces.json $value fields (even though the format reads $extensions
+// directly and does not consume the resolved values).
+const jsSurfacesConfig = {
+  source: [
+    path.join(DTCG_DIR, 'motion.json'),
+    path.join(DTCG_DIR, 'surfaces.json'),
+  ],
+  // The two source files both have a top-level $description; SD reports this
+  // as a collision even though it is DTCG metadata, not a real token conflict.
+  log: { warnings: 'disabled' },
+  platforms: {
+    'js/surfaces': {
+      transformGroup: 'carbon/motion',
+      buildPath: JS_GENERATED + '/',
+      files: [
+        {
+          destination: 'surfaces.js',
+          format: 'carbon/motion-js-surfaces',
+          options: { output: 'js' },
+        },
+        {
+          destination: 'surfaces.d.ts',
+          format: 'carbon/motion-js-surfaces',
+          options: { output: 'dts' },
+        },
+      ],
+    },
+  },
+};
+
+// surfaces.json — SCSS output
+const scssSurfacesConfig = {
+  source: [
+    path.join(DTCG_DIR, 'motion.json'),
+    path.join(DTCG_DIR, 'surfaces.json'),
+  ],
+  log: { warnings: 'disabled' },
+  platforms: {
+    'scss/surfaces': {
+      transformGroup: 'carbon/motion',
+      buildPath: SCSS_GENERATED + '/',
+      files: [
+        {
+          destination: '_surfaces.scss',
+          format: 'carbon/motion-scss-surfaces',
+        },
+      ],
+    },
+  },
+};
+
+// ── Build a registered SD instance ────────────────────────────────────────
+// In SD v5, register* methods live on the instance, not the class.
+// We create one base instance with all plugins registered, then extend it
+// per-config so each build inherits the registrations.
+function createBase() {
+  const base = new StyleDictionary({});
+  base.registerTransform(carbonMotionNameKebab);
+  base.registerTransform(carbonMotionDuration);
+  base.registerTransform(carbonMotionCubicBezier);
+  base.registerTransformGroup({
+    name: 'carbon/motion',
+    transforms: CARBON_MOTION_TRANSFORMS,
+  });
+  base.registerFormat(carbonJsMotionTokens);
+  base.registerFormat(carbonJsMotionSurfaces);
+  base.registerFormat(carbonScssMotionTokens);
+  base.registerFormat(carbonScssMotionSurfaces);
+  return base;
+}
+
+// ── JS build ──────────────────────────────────────────────────────────────
+// Generates:
+//   js/generated/tokens.{js,d.ts}
+//   js/generated/surfaces.{js,d.ts}
+async function runJs() {
+  fs.mkdirSync(JS_GENERATED, { recursive: true });
+  const base = createBase();
+  await (await base.extend(jsTokensConfig)).buildAllPlatforms();
+  await (await base.extend(jsSurfacesConfig)).buildAllPlatforms();
+}
+
+// ── SCSS build ────────────────────────────────────────────────────────────
+// Generates:
+//   scss/generated/_tokens.scss
+//   scss/generated/_surfaces.scss
+async function runScss() {
+  fs.mkdirSync(SCSS_GENERATED, { recursive: true });
+  const base = createBase();
+  await (await base.extend(scssTokensConfig)).buildAllPlatforms();
+  await (await base.extend(scssSurfacesConfig)).buildAllPlatforms();
+}
+
+// ── Full build (JS + SCSS) ─────────────────────────────────────────────────
+async function run() {
+  await runJs();
+  await runScss();
+}
+
+module.exports = {
+  run,
+  runJs,
+  runScss,
+  jsTokensConfig,
+  scssTokensConfig,
+  jsSurfacesConfig,
+  scssSurfacesConfig,
+};

package/style-dictionary/transforms/cubic-bezier.js

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Converts a DTCG cubicBezier $value array `[x1, y1, x2, y2]` into the CSS
+ * string `"cubic-bezier(x1, y1, x2, y2)"`.
+ *
+ * Style Dictionary v5 does not perform this conversion for cubicBezier tokens
+ * automatically, so we handle it here.
+ *
+ * Examples:
+ *   [0.2, 0, 0.38, 0.9] → 'cubic-bezier(0.2, 0, 0.38, 0.9)'
+ *   [0, 0, 0.3, 1]       → 'cubic-bezier(0, 0, 0.3, 1)'
+ */
+module.exports = {
+  name: 'carbon/motion-cubic-bezier',
+  type: 'value',
+  transitive: true,
+  filter(token) {
+    return token.$type === 'cubicBezier' || token.type === 'cubicBezier';
+  },
+  transform(token) {
+    const v = token.value !== undefined ? token.value : token.$value;
+
+    if (Array.isArray(v) && v.length === 4) {
+      return `cubic-bezier(${v.join(', ')})`;
+    }
+
+    // Already a resolved string — pass through.
+    return v;
+  },
+};

package/style-dictionary/transforms/duration.js

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Converts a DTCG duration $value object `{ value: N, unit: "ms" }` into the
+ * CSS string `"Nms"`.
+ *
+ * The DTCG spec stores duration as a composite object rather than a bare
+ * string; Style Dictionary does not know this shape natively, so we resolve
+ * it here before the value reaches any format.
+ *
+ * Examples:
+ *   { value: 70,  unit: 'ms' } → '70ms'
+ *   { value: 400, unit: 'ms' } → '400ms'
+ */
+module.exports = {
+  name: 'carbon/motion-duration',
+  type: 'value',
+  transitive: true,
+  filter(token) {
+    return token.$type === 'duration' || token.type === 'duration';
+  },
+  transform(token) {
+    const v = token.value !== undefined ? token.value : token.$value;
+
+    if (v && typeof v === 'object' && 'value' in v && 'unit' in v) {
+      return `${v.value}${v.unit}`;
+    }
+
+    // Already a resolved string (e.g. from a transitive pass) — pass through.
+    return v;
+  },
+};

package/style-dictionary/utils/dts-type-literal.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+/**
+ * Serialise a JS value as a TypeScript type literal.
+ * Preserves string/number literal types (and nested object/tuple structure)
+ * so generated `.d.ts` files discriminate on `kind` and keep token names
+ * assignable to hand-authored unions like `DurationName`.
+ *
+ * Examples:
+ *   'reveal'                          → '"reveal"'
+ *   0                                 → '0'
+ *   { kind: 'reveal' }                → '{\n  kind: "reveal"\n}'
+ *   ['entrance', 'productive']        → '[\n  "entrance",\n  "productive"\n]'
+ *
+ * @param {*} value
+ * @param {number} [indent=0]
+ * @returns {string}
+ */
+function toDtsTypeLiteral(value, indent = 0) {
+  const pad = '  '.repeat(indent);
+  const innerPad = '  '.repeat(indent + 1);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const items = value
+      .map((item) => `${innerPad}${toDtsTypeLiteral(item, indent + 1)}`)
+      .join(',\n');
+    return `[\n${items}\n${pad}]`;
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    const body = entries
+      .map(
+        ([key, nested]) =>
+          `${innerPad}${key}: ${toDtsTypeLiteral(nested, indent + 1)}`
+      )
+      .join(',\n');
+    return `{\n${body}\n${pad}}`;
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+
+  if (value === null) return 'null';
+
+  // string literal type
+  return JSON.stringify(String(value));
+}
+
+module.exports = { toDtsTypeLiteral };