@carbon/themes 11.81.0 → 11.82.0-rc.0

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

@@ -14,8 +14,10 @@
  * 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:
+ * 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",
@@ -26,6 +28,21 @@
  *     }
  *   }
  *
+ *   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:
@@ -80,9 +97,33 @@ function carbonComponentTokensPreprocessor(dictionary) {
       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];
+        // 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,
@@ -95,12 +136,24 @@ function carbonComponentTokensPreprocessor(dictionary) {
           byTheme[theme] = syntheticNode;
         }
 
-        out[key] = {
+        // 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);

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

@@ -9,13 +9,13 @@
 
 /**
  *
- * DTCG source files (g10.json, g90.json, g100.json) 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.
+ * 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 (g10.json):
+ * Example:
  *
  *   background: {
  *     $type:  "color",

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

@@ -10,7 +10,7 @@
 /**
  *
  * Extracts the `$extensions["org.carbon"]["color-scheme"]` value that lives
- * at the top level of each theme JSON file (white.json, g10.json, etc.) and
+ * 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.
  *

package/style-dictionary/sd.config.js

@@ -21,7 +21,9 @@ const { default: StyleDictionary } = require('style-dictionary');
 // ── Custom plugins ────────────────────────────────────────────────────────────
 const carbonColorFlatten = require('./transforms/color-flatten');
 const carbonAlphaModifier = require('./transforms/alpha-modifier');
-const carbonComponentTokensPreprocessor = require('./preprocessors/component-tokens');
+const carbonComponentTokensPreprocessorModule = require('./preprocessors/component-tokens');
+const { preprocessor: carbonComponentTokensPreprocessor } =
+  carbonComponentTokensPreprocessorModule;
 const carbonThemeMetadataPreprocessor = require('./preprocessors/theme-metadata');
 const { preprocessor: flattenDualRole } = require('./preprocessors/dual-role');
 const carbonScssThemes = require('./formats/scss-themes');
@@ -43,6 +45,15 @@ const JS_GENERATED_COMPONENTS = path.join(
 );
 
 const THEME_NAMES = ['white', 'g10', 'g90', 'g100'];
+
+// Light/dark scheme per theme — used to re-inject color-scheme metadata after
+// extractThemeSlice strips the root $extensions from the unified file.
+const THEME_COLOR_SCHEME = {
+  white: 'light',
+  g10: 'light',
+  g90: 'dark',
+  g100: 'dark',
+};
 const COMPONENT_NAMES = [
   'button',
   'tag',
@@ -51,6 +62,72 @@ const COMPONENT_NAMES = [
   'content-switcher',
 ];
 
+// ── extractThemeSlice ─────────────────────────────────────────────────────────
+//
+// After the component-tokens preprocessor runs on themes.json, every leaf token
+// node becomes a group with a `_by_theme` child containing one synthetic leaf
+// per theme.  This function walks the expanded tree and replaces each
+// `_by_theme` group with the single synthetic leaf for `themeName`, collapsing
+// the tree back into a normal per-theme token structure that the rest of the
+// pipeline (flattenDualRole, SD transforms, formatters) understands.
+//
+// Tokens that do NOT have a _by_theme group (palette reference tokens injected
+// via `source:`) are passed through unchanged.
+function extractThemeSlice(node, themeName) {
+  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;
+    }
+    if (key === '_by_theme') {
+      // Skip — handled by the parent via the `value._by_theme` branch below.
+      continue;
+    }
+
+    // Check if this child node has a _by_theme group (i.e. it was a leaf or
+    // dual-role node in themes.json that the preprocessor expanded).
+    if (value._by_theme) {
+      const leaf = value._by_theme[themeName];
+      if (leaf) {
+        // Start with the leaf's DTCG fields ($type, $value, $extensions).
+        const merged = { ...leaf };
+        // Preserve $description from the group wrapper (leaf synthetic nodes
+        // don't carry it, but the original themes.json node does).
+        if (!merged.$description && value.$description)
+          merged.$description = value.$description;
+        if (!merged.$type && value.$type) merged.$type = value.$type;
+
+        // Recurse into any group children of this node (dual-role case):
+        // e.g. `background` is both a token and the parent of `background-active`.
+        for (const [childKey, childValue] of Object.entries(value)) {
+          if (childKey.startsWith('$') || childKey === '_by_theme') continue;
+          if (!childValue || typeof childValue !== 'object') continue;
+          const sliced = extractThemeSlice(
+            { [childKey]: childValue },
+            themeName
+          );
+          if (sliced[childKey] !== undefined)
+            merged[childKey] = sliced[childKey];
+        }
+
+        out[key] = merged;
+      }
+      // If the theme had no entry, skip the token.
+    } else {
+      const sliced = extractThemeSlice(value, themeName);
+      if (sliced !== null) out[key] = sliced;
+    }
+  }
+  return out;
+}
+
 // ── Custom name transform ─────────────────────────────────────────────────────
 //
 // Builds a kebab-case name from the SD token path, with one special rule:
@@ -89,16 +166,46 @@ const CARBON_TRANSFORMS = [
 ];
 
 // ── Helper: build config for one theme ───────────────────────────────────────
+//
+// themes.json is the unified source — all four themes in one file, with each
+// token carrying per-theme values under $extensions["carbon.themes"].
+// The component-tokens preprocessor expands those into per-theme leaf tokens
+// (identical to what it does for component files), and dual-role splitting
+// then runs on the resulting tree so SD sees clean leaf+group pairs.
 function themeConfig(themeName) {
-  // Pre-process the theme JSON to handle "dual-role" nodes (nodes that have
-  // both a $value AND non-$ children).  SD v5 treats a node with $value as a
-  // leaf and silently drops children; flattenDualRole collects ALL leaf tokens
-  // (including children of dual-role parents) into a flat camelCase structure.
-  // The palette is kept in `source:` (nested) so SD alias resolution works.
-  const rawTheme = JSON.parse(
-    fs.readFileSync(path.join(DTCG_DIR, `${themeName}.json`), 'utf8')
+  // Read the unified themes.json. The component-tokens preprocessor first
+  // expands carbon.themes entries into _by_theme.<theme> leaf nodes, then
+  // flattenDualRole splits any dual-role nodes (value + children) so SD can
+  // process them without losing children.
+  const rawThemes = JSON.parse(
+    fs.readFileSync(path.join(DTCG_DIR, 'themes.json'), 'utf8')
   );
-  const flatTokens = flattenDualRole(rawTheme);
+  // The component-tokens preprocessor understands the { value, alpha } entry
+  // shape from the unified file as well as the legacy bare-string shape from
+  // component files. Run it first so carbon.themes entries become $value leaves.
+  const expanded = carbonComponentTokensPreprocessor(rawThemes);
+  // Now extract only this theme's _by_theme.<themeName> leaf nodes, rewriting
+  // them back to plain $value tokens so the rest of the pipeline sees a normal
+  // single-theme token tree.
+  const rawSlice = extractThemeSlice(expanded, themeName);
+
+  // Re-attach the per-theme color-scheme to the root $extensions so that
+  // carbonThemeMetadataPreprocessor (which reads
+  // dictionary.$extensions["org.carbon"]["color-scheme"]) can inject the
+  // color-scheme synthetic token.  extractThemeSlice does not carry the root
+  // $extensions through because they are global, not per-token.
+  const themeSlice = {
+    ...rawSlice,
+    $extensions: {
+      ...(rawSlice.$extensions ?? {}),
+      'org.carbon': {
+        ...(rawSlice.$extensions?.['org.carbon'] ?? {}),
+        'color-scheme': THEME_COLOR_SCHEME[themeName],
+      },
+    },
+  };
+
+  const flatTokens = flattenDualRole(themeSlice);
 
   return {
     source: [path.join(DTCG_DIR, 'color-palette.json')],
@@ -246,7 +353,7 @@ function createBase() {
     name: 'carbon',
     transforms: CARBON_TRANSFORMS,
   });
-  base.registerPreprocessor(carbonComponentTokensPreprocessor);
+  base.registerPreprocessor(carbonComponentTokensPreprocessorModule);
   base.registerPreprocessor(carbonThemeMetadataPreprocessor);
   base.registerFormat(carbonScssThemes);
   base.registerFormat(carbonScssTokens);

package/style-dictionary/transforms/alpha-modifier.js

@@ -19,7 +19,7 @@
  * If no alphaModifier extension is present the token is passed through
  * unchanged (carbon/color-flatten will handle it next).
  *
- * Example in white.json:
+ * Example in themes.json:
  *   "background-active": {
  *     "$type": "color",
  *     "$value": "{gray.50}",         ← resolved by SD to '#8d8d8d'