@carbon/themes 12.0.0-alpha.1 → 12.0.0-alpha.3

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

@@ -1,127 +0,0 @@
-/**
- * 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

@@ -1,91 +0,0 @@
-/**
- * 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

@@ -1,172 +0,0 @@
-/**
- * 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.
- * Two equivalent forms are accepted:
- *
- *   Component-token form (legacy, bare strings + separate alphaModifiers):
- *   "button": {
- *     "danger-active": {
- *       "$type": "color",
- *       "$extensions": {
- *         "carbon.themes": { "white": "{red.80}", "g10": "{red.80}", ... },
- *         "org.carbon": { "alphaModifiers": { "g90": 0.3, "g100": 0.3 } }
- *       }
- *     }
- *   }
- *
- *   Unified theme-token form (value + alpha co-located per theme):
- *   "background": {
- *     "hover": {
- *       "$type": "color",
- *       "$extensions": {
- *         "carbon.themes": {
- *           "white": { "value": "{gray.50}", "alpha": 0.12 },
- *           "g10":   { "value": "{gray.50}", "alpha": 0.12 },
- *           "g90":   "{gray.50}",
- *           "g100":  "{gray.50}"
- *         }
- *       }
- *     }
- *   }
- *
- * 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).
-        // Each entry in carbon.themes is either:
-        //   - a bare string/alias  → { "white": "{red.80}" }   (legacy component form)
-        //   - an object { value, alpha? } → unified theme form where value and
-        //     alpha are co-located under the same theme key.
-        // The legacy separate "org.carbon.alphaModifiers" map is still supported
-        // for backwards-compat with existing component token files.
-        for (const [theme, themeEntry] of Object.entries(carbonThemes)) {
-          // An entry can be:
-          //   1. A bare string alias/hex           → treat as the value directly
-          //   2. A composite color object           → { colorSpace, components, hex }
-          //      Used for hardcoded non-palette colors. Treat as the value directly.
-          //   3. A { value, alpha? } wrapper object → unified theme format
-          const isComposite =
-            themeEntry !== null &&
-            typeof themeEntry === 'object' &&
-            !Array.isArray(themeEntry) &&
-            'hex' in themeEntry;
-          const isWrapper =
-            themeEntry !== null &&
-            typeof themeEntry === 'object' &&
-            !Array.isArray(themeEntry) &&
-            !isComposite;
-          const themeValue = isWrapper ? themeEntry.value : themeEntry;
-          // Per-theme alpha: only { value, alpha } wrappers carry alpha.
-          // Legacy org.carbon.alphaModifiers map is the fallback for component files.
-          const alpha = isWrapper ? themeEntry.alpha : alphaModifiers[theme];
-          const syntheticNode = {
-            $type: value.$type ?? 'color',
-            $value: themeValue,
-          };
-          if (alpha !== undefined) {
-            syntheticNode.$extensions = {
-              'org.carbon': { alphaModifier: alpha },
-            };
-          }
-          byTheme[theme] = syntheticNode;
-        }
-
-        // Build the expanded node: preserve DTCG metadata, add _by_theme, and
-        // recurse into any non-$ children (dual-role nodes in themes.json have
-        // both a carbon.themes value AND group children like `active`, `hover`).
-        const expandedNode = {
-          ...(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,
-        };
-        for (const [childKey, childValue] of Object.entries(value)) {
-          if (childKey.startsWith('$') || childKey === '_by_theme') continue;
-          if (!childValue || typeof childValue !== 'object') continue;
-          // Wrap in a single-key object so walk() sees the key and can apply
-          // the carbon.themes expansion logic to it (walk iterates the entries
-          // of the object passed in, so childValue alone would skip expansion).
-          expandedNode[childKey] = walk({ [childKey]: childValue })[childKey];
-        }
-        out[key] = expandedNode;
-      } else {
-        // Recurse into nested groups
-        out[key] = walk(value);
-      }
-    }
-
-    return out;
-  }
-
-  return walk(dictionary);
-}
-
-module.exports = {
-  name: 'carbon/component-tokens',
-  preprocessor: carbonComponentTokensPreprocessor,
-};

package/style-dictionary/preprocessors/dual-role.js

@@ -1,157 +0,0 @@
-/**
- * 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 unified themes.json (and previously the individual per-theme files) can
- * contain nodes that are simultaneously token leaves (they have a `$value`) AND
- * token groups (they have non-`$`-prefixed children).  Style Dictionary v5 does
- * not support this pattern — when a node has `$value`, SD treats it as a leaf
- * token and silently drops any non-`$` children.
- *
- * Example:
- *
- *   background: {
- *     $type:  "color",
- *     $value: "{gray.10}",            ← token leaf value
- *     active: { $type: "color", $value: "{gray.50}", ... },  ← child token
- *     brand:  { ... }
- *   }
- *
- * Without this preprocessor, SD emits `background` but loses `background-active`
- * and `background-brand`.  There are 27 such dual-role nodes in each of
- * g10 / g90 / g100, causing 48 tokens to go missing from the generated output.
- *
- * ── Solution ────────────────────────────────────────────────────────────────
- *
- * For any dual-role node (has `$value` AND non-`$` children), this preprocessor
- * splits the node:
- *
- *   1. The parent's token value (`$value`, `$type`, `$extensions`) is moved into
- *      a synthetic `_self` child at the same level.
- *   2. The parent node becomes a pure group (its `$value` is removed).
- *
- * After this transform, the tree becomes:
- *
- *   background: {
- *     _self:  { $type: "color", $value: "{gray.10}" },   ← parent value
- *     active: { $type: "color", $value: "{gray.50}", ... },
- *     brand:  { ... }
- *   }
- *
- * SD sees `background._self` as path `['background', '_self']` and
- * `background.active` as path `['background', 'active']`.
- *
- * A companion custom name transform (`carbon/name-kebab`, registered in
- * sd.config.js) strips `_self` from the path when building the token name:
- *
- *   ['background', '_self'] → 'background'       (parent token)
- *   ['background', 'active'] → 'background-active'
- *   ['layer', '_self'] → 'layer'
- *   ['layer', '01'] → 'layer-01'
- *
- * This reproduces the flat token names that the old dtcg-converter produced,
- * while preserving correct hierarchy for SD's alias resolution and path-based
- * name computation.
- *
- * ── Alias resolution ────────────────────────────────────────────────────────
- *
- * The color-palette.json file is loaded as `source:` (not pre-processed) by
- * sd.config.js, so its tokens stay in their original nested form and SD alias
- * resolution ({blue.60} etc.) continues to work.
- *
- * This preprocessor is called with only the theme JSON as input (passed as
- * `tokens:` in themeConfig()), never seeing the merged palette+theme tree.
- * Therefore palette tokens are unaffected.
- *
- * @param {object} dictionary  Raw DTCG token tree (theme file only)
- * @returns {object}           Normalised tree with dual-role nodes split
- */
-
-/**
- * Process a single DTCG token node.
- *
- * The node may be:
- *   - A pure leaf token (has `$value`, no non-`$` children) → returned as-is.
- *   - A pure group (no `$value`, has non-`$` children) → children are recursed.
- *   - A dual-role node (has BOTH `$value` AND non-`$` children) → split: the
- *     `$value`/`$type`/`$extensions` are moved to a `_self` synthetic leaf, and
- *     the node becomes a pure group whose children include `_self` plus the
- *     original children (each recursively processed).
- *
- * @param {object} node  A single DTCG node object.
- * @returns {object}     The normalised node.
- */
-function processNode(node) {
-  if (!node || typeof node !== 'object') return node;
-
-  const hasValue = '$value' in node;
-  const nonDollarChildren = Object.keys(node).filter((k) => !k.startsWith('$'));
-  const hasChildren = nonDollarChildren.length > 0;
-
-  if (hasValue && hasChildren) {
-    // ── Dual-role node ────────────────────────────────────────────────────────
-    // Collect the DTCG metadata into a `_self` leaf.
-    const selfLeaf = {};
-    for (const [k, v] of Object.entries(node)) {
-      if (k.startsWith('$')) selfLeaf[k] = v;
-    }
-    // Build the pure-group: _self first, then recursively-processed children.
-    const group = { _self: selfLeaf };
-    for (const childKey of nonDollarChildren) {
-      group[childKey] = processNode(node[childKey]);
-    }
-    return group;
-  } else if (hasChildren) {
-    // ── Pure group ────────────────────────────────────────────────────────────
-    const out = {};
-    for (const [k, v] of Object.entries(node)) {
-      if (k.startsWith('$')) {
-        out[k] = v;
-      } else {
-        out[k] = processNode(v);
-      }
-    }
-    return out;
-  } else {
-    // ── Pure leaf token ───────────────────────────────────────────────────────
-    return node;
-  }
-}
-
-/**
- * Top-level preprocessor function.
- *
- * The top-level dictionary itself is always a group (never a token), so we
- * iterate its entries and call processNode() on each non-`$` child.
- *
- * @param {object} dictionary  Raw DTCG token tree from the theme JSON file
- * @returns {object}           Normalised tree with all dual-role nodes split
- */
-function carbonDualRolePreprocessor(dictionary) {
-  if (!dictionary || typeof dictionary !== 'object') return dictionary;
-
-  const out = {};
-  for (const [key, value] of Object.entries(dictionary)) {
-    if (key.startsWith('$')) {
-      // Top-level DTCG metadata — preserve as-is.
-      out[key] = value;
-    } else if (value && typeof value === 'object') {
-      out[key] = processNode(value);
-    } else {
-      out[key] = value;
-    }
-  }
-  return out;
-}
-
-module.exports = {
-  name: 'carbon/dual-role',
-  preprocessor: carbonDualRolePreprocessor,
-};

package/style-dictionary/preprocessors/theme-metadata.js

@@ -1,46 +0,0 @@
-/**
- * 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';
-
-/**
- *
- * Extracts the `$extensions["org.carbon"]["color-scheme"]` value that lives
- * at the top level of the unified themes.json and
- * injects it as a synthetic `color-scheme` token, so the SCSS format can
- * include it in the theme Sass map alongside the regular color tokens.
- *
- *
- * @param {object} dictionary  Style Dictionary raw token tree
- * @returns {object}
- */
-function carbonThemeMetadataPreprocessor(dictionary) {
-  const colorScheme = dictionary.$extensions?.['org.carbon']?.['color-scheme'];
-
-  if (!colorScheme) {
-    return dictionary;
-  }
-
-  // Inject as color.scheme so the flattened token name becomes 'color-scheme',
-  // matching what dtcg-converter.js produces today.
-  return {
-    ...dictionary,
-    color: {
-      ...(dictionary.color ?? {}),
-      scheme: {
-        $type: 'other',
-        $value: colorScheme,
-        $description: 'Color scheme of this theme (light or dark)',
-      },
-    },
-  };
-}
-
-module.exports = {
-  name: 'carbon/theme-metadata',
-  preprocessor: carbonThemeMetadataPreprocessor,
-};