@carbon/themes 11.78.0 → 11.79.0

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

@@ -0,0 +1,128 @@
+/**
+ * Copyright IBM Corp. 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';
+
+/**
+ * Receives tokens for ONE component (pre-processed by
+ * `component-tokens`) and emits two files:
+ *   - `<componentName>.js`   — named ES exports, one per token
+ *   - `<componentName>.d.ts` — companion TypeScript declarations
+ *
+ */
+
+const FILE_BANNER = `// Code generated by @carbon/themes. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2025
+//
+// 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])/g, (_, ch) => ch.toUpperCase());
+}
+
+/**
+ * Normalize theme key to the JS API convention.
+ * 'white' → 'whiteTheme', 'g10' → 'g10' (no dash, unlike SCSS convention)
+ * @param {string} theme
+ * @returns {string}
+ */
+function normalizeThemeKey(theme) {
+  if (theme === 'white') return 'whiteTheme';
+  return theme; // 'g10', 'g90', 'g100' — unchanged
+}
+
+/**
+ * Serialize a JS value to source-code string.
+ * @param {*} value
+ * @returns {string}
+ */
+function toSource(value) {
+  if (typeof value === 'string') {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Group SD tokens by component-token name and theme.
+ * Mirrors the logic in carbon-scss-component-tokens.js.
+ *
+ * @param {import('style-dictionary').Token[]} allTokens
+ * @returns {Map<string, Record<string, string>>}
+ */
+function groupByTokenAndTheme(allTokens) {
+  const result = new Map();
+  const BY_THEME_MARKER = '-by-theme-';
+
+  for (const token of allTokens) {
+    const idx = token.name.indexOf(BY_THEME_MARKER);
+    if (idx === -1) continue;
+
+    const tokenName = token.name.slice(0, idx);
+    const theme = token.name.slice(idx + BY_THEME_MARKER.length);
+
+    if (!result.has(tokenName)) {
+      result.set(tokenName, {});
+    }
+    result.get(tokenName)[theme] = token.value ?? token.$value;
+  }
+
+  return result;
+}
+
+/**
+ * @param {{ dictionary: import('style-dictionary').Dictionary, options: object }} args
+ * @returns {string}
+ */
+function carbonJsComponentTokensFormat({ dictionary, options }) {
+  const outputMode = options?.output ?? 'js'; // 'js' | 'dts'
+
+  const grouped = groupByTokenAndTheme(dictionary.allTokens);
+
+  // Preserve insertion order from the DTCG JSON walk.
+  const sortedNames = [...grouped.keys()];
+
+  const lines = [FILE_BANNER];
+
+  for (const tokenName of sortedNames) {
+    const themeValues = grouped.get(tokenName);
+    const camelName = kebabToCamel(tokenName);
+
+    // Preserve JSON source order exactly.
+    const themes = Object.keys(themeValues);
+
+    if (outputMode === 'js') {
+      const props = themes
+        .map((theme) => {
+          const key = normalizeThemeKey(theme);
+          return `  ${key}: ${toSource(themeValues[theme])}`;
+        })
+        .join(',\n');
+      lines.push(`export const ${camelName} = {\n${props},\n};`);
+    } else {
+      const props = themes
+        .map((theme) => `  ${normalizeThemeKey(theme)}: string`)
+        .join(';\n');
+      lines.push(`export declare const ${camelName}: {\n${props};\n};`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+module.exports = {
+  name: 'carbon/js-component-tokens',
+  format: carbonJsComponentTokensFormat,
+};

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

@@ -0,0 +1,84 @@
+/**
+ * Copyright IBM Corp. 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';
+
+/**
+ *
+ * Receives all tokens for ONE theme and emits two files (via SD's
+ * `files` array):
+ *   - `<themeName>.js`   — ES module with `export const camelName = value;`
+ *   - `<themeName>.d.ts` — companion TypeScript declarations
+ *
+ * Token names arrive as kebab-case from SD and are converted to camelCase.
+ *
+ */
+
+const FILE_BANNER = `// Code generated by @carbon/themes. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2025
+//
+// 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])/g, (_, ch) => ch.toUpperCase());
+}
+
+/**
+ * Serialize a JS value to a source-code string.
+ * Strings get single-quoted; everything else uses JSON.
+ * @param {*} value
+ * @returns {string}
+ */
+function toSource(value) {
+  if (typeof value === 'string') {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * @param {{ dictionary: import('style-dictionary').Dictionary, options: object }} args
+ * @returns {string}
+ */
+function carbonJsThemesFormat({ dictionary, options }) {
+  const outputMode = options?.output ?? 'js'; // 'js' | 'dts'
+
+  const lines = [FILE_BANNER];
+  const sorted = dictionary.allTokens;
+
+  for (const token of sorted) {
+    const camelName = kebabToCamel(token.name);
+    // SD v5 may store the resolved alias as a full token node object in
+    // token.value when the alias points to a sibling token. Unwrap it.
+    let value = token.value ?? token.$value;
+    if (value !== null && typeof value === 'object' && '$value' in value) {
+      value = value.$value;
+    }
+    const tsType = typeof value === 'string' ? 'string' : 'number';
+
+    if (outputMode === 'js') {
+      lines.push(`export const ${camelName} = ${toSource(value)};`);
+    } else {
+      lines.push(`export declare const ${camelName}: ${tsType};`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+module.exports = {
+  name: 'carbon/js-themes',
+  format: carbonJsThemesFormat,
+};

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

@@ -0,0 +1,149 @@
+/**
+ * Copyright IBM Corp. 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';
+
+/**
+ * Receives the tokens for ONE component (already expanded from the
+ * carbon.themes multi-theme shape by the `component-tokens`
+ * preprocessor).  Emits a Sass map variable per token, keyed by normalised
+ * theme name:
+ *
+ *   $button-danger-active: (
+ *     'white-theme': #a2191f,
+ *     'g-10':        #a2191f,
+ *     'g-90':        #a2191f,
+ *     'g-100':       #a2191f,
+ *   ) !default;
+ *
+ *
+ * The token tree must have been pre-processed by `carbon/component-tokens`
+ * so that each token has a `_by_theme` child group containing one resolved
+ * token per theme.
+ */
+
+const FILE_BANNER = `// Code generated by @carbon/themes. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2023
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+`;
+
+/**
+ * Normalize a raw theme key to the Carbon SCSS convention.
+ * @param {string} theme
+ * @returns {string}
+ */
+function normalizeThemeName(theme) {
+  if (theme === 'white') return 'white-theme';
+  if (/^g\d+$/.test(theme)) return theme.replace(/^g(\d+)$/, 'g-$1');
+  return theme;
+}
+
+/**
+ * Serialize a CSS value to a Sass literal (same logic as carbon-scss-themes).
+ * @param {string|number} value
+ * @returns {string}
+ */
+function toSassLiteral(value) {
+  if (typeof value === 'number') return String(value);
+  if (typeof value !== 'string') return JSON.stringify(value);
+  if (value.startsWith('#') || value.startsWith('rgb')) return value;
+  if (
+    value.endsWith('px') ||
+    value.endsWith('em') ||
+    value.endsWith('%') ||
+    value === '0'
+  )
+    return value;
+  return `string.unquote("${value}")`;
+}
+
+/**
+ * Group SD tokens by their component-token name and theme.
+ *
+ * After the carbon/component-tokens preprocessor runs, tokens in the
+ * dictionary look like:
+ *
+ *   button-danger-active-by-theme-white  (name after flattening)
+ *   button-danger-active-by-theme-g10
+ *   ...
+ *
+ * We strip the `_by_theme-` infix and reconstruct the map.
+ *
+ * @param {import('style-dictionary').Token[]} allTokens
+ * @returns {Map<string, Record<string, string>>}  tokenName → { theme: value }
+ */
+function groupByTokenAndTheme(allTokens) {
+  const result = new Map();
+
+  for (const token of allTokens) {
+    // Token names contain '_by_theme' as an injected path segment.
+    // e.g. 'button-danger-active-by-theme-white' — but SD uses whatever
+    // separator the platform config specifies (usually '-').
+    // Match the segment just before a known theme key.
+    const BY_THEME_MARKER = '-by-theme-';
+    const idx = token.name.indexOf(BY_THEME_MARKER);
+    if (idx === -1) continue;
+
+    const tokenName = token.name.slice(0, idx);
+    const theme = token.name.slice(idx + BY_THEME_MARKER.length);
+
+    if (!result.has(tokenName)) {
+      result.set(tokenName, {});
+    }
+    result.get(tokenName)[theme] = token.value ?? token.$value;
+  }
+
+  return result;
+}
+
+/**
+ * @param {{ dictionary: import('style-dictionary').Dictionary }} args
+ * @returns {string}
+ */
+function carbonScssComponentTokensFormat({ dictionary }) {
+  const grouped = groupByTokenAndTheme(dictionary.allTokens);
+
+  // Preserve insertion order from the DTCG JSON walk — do NOT sort here.
+  // The old builder also sorted alphabetically, but the compare script passes
+  // tokens in JSON order so we honour that to get a byte-for-byte match.
+  const sortedNames = [...grouped.keys()];
+
+  const variableBlocks = sortedNames.map((tokenName) => {
+    const themeValues = grouped.get(tokenName);
+
+    // Preserve JSON source order exactly.
+    const themes = Object.keys(themeValues);
+
+    const entries = themes
+      .map((theme) => {
+        const normalized = normalizeThemeName(theme);
+        const value = themeValues[theme];
+        // Unquoted key — matches t.SassMapProperty(t.Identifier(theme), ...) in old builder
+        return `  ${normalized}: ${toSassLiteral(value)},`;
+      })
+      .join('\n');
+
+    return `\n$${tokenName}: (\n${entries}\n) !default;`;
+  });
+
+  return (
+    FILE_BANNER +
+    `\n@use 'sass:map';\n` +
+    `@use 'sass:string';\n` +
+    variableBlocks.join('\n') +
+    '\n'
+  );
+}
+
+module.exports = {
+  name: 'carbon/scss-component-tokens',
+  format: carbonScssComponentTokensFormat,
+};

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

@@ -0,0 +1,127 @@
+/**
+ * Copyright IBM Corp. 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';
+
+/**
+ *
+ *
+ * Each theme (white, g10, g90, g100) is expected to be a separate SD
+ * *platform* build run.  This format receives all tokens for ONE theme and
+ * emits the Sass map variable for that theme plus the utilities.merge call
+ * that folds in layout spacing and type tokens.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * NOTE ON MULTI-THEME FILES
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  The recommended approach:  run all four platforms, collect their individual
+ * strings, and concatenate them in sd.config.js using a custom action.
+ * A simpler alternative (and the one wired up in sd.config.js) is to use SD's
+ * `buildAllPlatforms()` with four platforms that each write to a *separate*
+ * file, then a post-build step (`buildAllPlatforms` custom action) concatenates
+ * them.  Both patterns are documented in style-dictionary/README.md.
+ */
+
+const FILE_BANNER = `// Code generated by @carbon/themes. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2023
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+`;
+
+const SCSS_IMPORTS = `@use 'sass:map';
+@use 'sass:string';
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '../utilities';
+`;
+
+/**
+ * Serialize a CSS color value to a Sass literal.
+ *
+ * - Hex colors   → bare hex       (e.g.  #ffffff)
+ * - rgba()       → bare function  (e.g.  rgba(141, 141, 141, 0.5))
+ * - Strings      → string.unquote("…")
+ * - Numbers      → bare number
+ *
+ * @param {string|number} value
+ * @returns {string}  Sass source fragment
+ */
+function toSassLiteral(value) {
+  if (typeof value === 'number') {
+    return String(value);
+  }
+  if (typeof value !== 'string') {
+    return JSON.stringify(value);
+  }
+  if (value.startsWith('#')) {
+    return value;
+  }
+  if (
+    value.startsWith('rgb') ||
+    value.endsWith('px') ||
+    value.endsWith('em') ||
+    value.endsWith('%') ||
+    value.endsWith('vw') ||
+    value.endsWith('vh') ||
+    value === '0'
+  ) {
+    return value;
+  }
+  // Plain string (e.g. 'light', 'dark') → Sass unquote with single quotes,
+  // matching t.SassValue("string.unquote('...')") in the old builder.
+  return `string.unquote('${value}')`;
+}
+
+/**
+ * @param {{ dictionary: import('style-dictionary').Dictionary, options: object, file: object }} args
+ * @returns {string}
+ */
+function carbonScssThemesFormat({ dictionary, options, file }) {
+  const themeName = options?.themeName ?? file?.options?.themeName ?? 'unknown';
+
+  // Sort alphabetically — matches dtcg-themes.js which calls .sort(([a],[b])=>a.localeCompare(b))
+  // color-scheme lands at its natural alpha position ('c' section).
+  const sorted = [...dictionary.allTokens].sort((a, b) =>
+    a.name.localeCompare(b.name)
+  );
+
+  const entries = sorted
+    .map((token) => {
+      const name = token.name;
+      // SD v5 may store the post-alias value as a full token node object in
+      // token.value when an alias points to a sibling token. Unwrap it.
+      let value = token.value ?? token.$value;
+      if (value !== null && typeof value === 'object' && '$value' in value) {
+        value = value.$value;
+      }
+      // Unquoted key — matches t.SassMapProperty(t.Identifier(token), ...) in old builder
+      return `  ${name}: ${toSassLiteral(value)},`;
+    })
+    .join('\n');
+
+  return (
+    FILE_BANNER +
+    '\n' +
+    SCSS_IMPORTS +
+    '\n' +
+    `$${themeName}: (\n${entries}\n) !default;\n` +
+    `$${themeName}: utilities.merge(\n` +
+    `  $${themeName},\n` +
+    `  layout.$spacing,\n` +
+    `  layout.$fluid-spacing,\n` +
+    `  type.$tokens\n` +
+    `);\n`
+  );
+}
+
+module.exports = {
+  name: 'carbon/scss-themes',
+  format: carbonScssThemesFormat,
+};

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

@@ -0,0 +1,91 @@
+/**
+ * Copyright IBM Corp. 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';
+
+/**
+ * The format does not actually use the SD `dictionary` — it reads the token
+ * list from the Carbon JS metadata directly, matching the original builder.
+ * This is intentional: _tokens.scss is a mapping layer, not derived from the
+ * token values.
+ */
+
+const { types: t } = require('@carbon/scss-generator');
+const { generate } = require('@carbon/scss-generator');
+const { group } = require('../../src/tokens');
+
+const FILE_BANNER = `// Code generated by @carbon/themes. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2023
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+`;
+
+/**
+ * @returns {Promise<string>}
+ */
+async function carbonScssTokensFormat() {
+  const tokens = group.getTokens();
+
+  const variables = tokens.flatMap((token) => {
+    const id = token.name;
+    return [
+      t.Newline(),
+      t.Comment(`/ The CSS Custom Property for the \`${id}\` token`),
+      t.Assignment({
+        id: t.Identifier(id),
+        init: t.SassFunctionCall({
+          id: t.Identifier('_get'),
+          params: [t.SassString(id)],
+        }),
+        default: true,
+      }),
+    ];
+  });
+
+  const stylesheet = t.StyleSheet([
+    t.SassModule('sass:map'),
+    t.SassModule('../config'),
+    t.SassModule('../theme'),
+    t.Newline(),
+    t.Comment('/ Internal helper for generating CSS Custom Properties'),
+    t.SassFunction({
+      id: t.Identifier('_get'),
+      params: [t.Identifier('token')],
+      body: t.BlockStatement([
+        t.IfStatement({
+          test: t.LogicalExpression({
+            left: t.SassValue('config.$use-fallback-value'),
+            operator: '==',
+            right: t.SassBoolean(false),
+          }),
+          consequent: t.BlockStatement([
+            t.AtReturn(t.SassValue('var(--#{config.$prefix}-#{$token})')),
+          ]),
+          alternate: t.BlockStatement([
+            t.AtReturn(
+              t.SassValue(
+                'var(--#{config.$prefix}-#{$token}, #{theme.get($token)})'
+              )
+            ),
+          ]),
+        }),
+      ]),
+    }),
+    ...variables,
+  ]);
+
+  const { code } = generate(stylesheet);
+  return FILE_BANNER + '\n' + (await code);
+}
+
+module.exports = {
+  name: 'carbon/scss-tokens',
+  format: carbonScssTokensFormat,
+};

package/style-dictionary/preprocessors/component-tokens.js

@@ -0,0 +1,119 @@
+/**
+ * Copyright IBM Corp. 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';
+
+/**
+ * Preprocessor: carbon/component-tokens
+ *
+ * Expands the `$extensions["carbon.themes"]` multi-theme shape that component
+ * token files (button.json, tag.json, …) use into flat per-theme tokens that
+ * Style Dictionary can process natively.
+ *
+ * Input — one token node with no $value but a per-theme map in extensions:
+ *
+ *   "button": {
+ *     "danger-active": {
+ *       "$type": "color",
+ *       "$extensions": {
+ *         "carbon.themes": { "white": "{red.80}", "g10": "{red.80}", ... },
+ *         "org.carbon": { "alphaModifiers": { "g90": 0.3, "g100": 0.3 } }
+ *       }
+ *     }
+ *   }
+ *
+ * Output — one flat sibling token per theme, keyed as
+ * `<tokenPath>-_by_theme-<themeName>` so the format functions can reconstruct
+ * the original token name and theme:
+ *
+ *   "button": {
+ *     "danger-active": {
+ *       "_by_theme": {
+ *         "white":  { "$type": "color", "$value": "{red.80}" },
+ *         "g10":    { "$type": "color", "$value": "{red.80}" },
+ *         "g90":    { "$type": "color", "$value": "{red.80}",
+ *                     "$extensions": { "org.carbon": { "alphaModifier": 0.3 } } },
+ *         "g100":   { "$type": "color", "$value": "{red.80}",
+ *                     "$extensions": { "org.carbon": { "alphaModifier": 0.3 } } }
+ *       }
+ *     }
+ *   }
+ *
+ * SD v5 walks DTCG token trees and treats any node with a `$value` as a leaf
+ * token. The `_by_theme.<themeName>` nodes each have `$value`, so SD resolves
+ * aliases and applies transforms on them individually.
+ *
+ * The format functions identify these tokens by the `-_by_theme-` infix in
+ * their flattened name (using the `name/kebab` transform).
+ *
+ * Tokens that already carry a top-level $value are left untouched.
+ *
+ * @param {object} dictionary  Raw DTCG token tree passed by SD
+ * @returns {object}           Expanded token tree
+ */
+function carbonComponentTokensPreprocessor(dictionary) {
+  function walk(node) {
+    if (!node || typeof node !== 'object') return node;
+
+    const out = {};
+
+    for (const [key, value] of Object.entries(node)) {
+      if (key.startsWith('$')) {
+        out[key] = value;
+        continue;
+      }
+
+      if (!value || typeof value !== 'object') {
+        out[key] = value;
+        continue;
+      }
+
+      const carbonThemes = value.$extensions?.['carbon.themes'];
+      const alphaModifiers =
+        value.$extensions?.['org.carbon']?.alphaModifiers ?? {};
+
+      // Only expand nodes that have carbon.themes and NO existing $value.
+      if (carbonThemes && value.$value === undefined) {
+        const byTheme = {};
+
+        // Preserve original JSON key order (important for 'fallback' position)
+        for (const [theme, themeValue] of Object.entries(carbonThemes)) {
+          const alpha = alphaModifiers[theme];
+          const syntheticNode = {
+            $type: value.$type ?? 'color',
+            $value: themeValue,
+          };
+          if (alpha !== undefined) {
+            syntheticNode.$extensions = {
+              'org.carbon': { alphaModifier: alpha },
+            };
+          }
+          byTheme[theme] = syntheticNode;
+        }
+
+        out[key] = {
+          ...(value.$type ? { $type: value.$type } : {}),
+          ...(value.$description ? { $description: value.$description } : {}),
+          // _by_theme is a DTCG group — each child is a leaf token with $value
+          _by_theme: byTheme,
+        };
+      } else {
+        // Recurse into nested groups
+        out[key] = walk(value);
+      }
+    }
+
+    return out;
+  }
+
+  return walk(dictionary);
+}
+
+module.exports = {
+  name: 'carbon/component-tokens',
+  preprocessor: carbonComponentTokensPreprocessor,
+};