@massimo-cassandro/minimo 1.33.6 → 1.34.0

package/design-tokens/README.md

@@ -6,201 +6,6 @@
 
 <!-- TODO modalità d'uso (da tokens penpots o figma, con o snza merge css ecc...) -->
 
-## Design Token Utilities
+## Design Tokens Builder
 
-<!-- TODO rivedere e semplificare -->
-
-A set of Node.js scripts for managing CSS design tokens in a project. Built on top of [Style Dictionary v5](https://styledictionary.com/).
-
-### Scripts
-
-| Script | Purpose |
-|---|---|
-| `build-tokens.mjs` | Generates a CSS custom properties file from design token source files |
-| `check-unresolved-custom-props.mjs` | Scans CSS files and reports any `var(--...)` references not found in the generated token file |
-
-Both scripts share the same config file, passed via `--config`.
-
-### Setup
-
-The scripts are intended to be used as npm scripts. Add them to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "build tokens": "npx buildTokens --config ./path/to/tokens-config.mjs",
-    "check unresolved props": "npx checkUnresolvedProps --config ./path/to/tokens-config.mjs"
-  }
-}
-```
-
-### Dependencies
-
-The following packages must be present in your project:
-
-```json
-{
-  "style-dictionary": "^5",
-  "stylelint": "^16"
-}
-```
-
-### Configuration file
-
-Both scripts read a shared config file passed with `--config`. Use `tokens-config-sample.mjs` as a starting point.
-
-Read comments inside the sample file for more info.
-
-
-### `build-tokens.mjs`
-
-Reads design token source files and generates:
-- A **CSS file** containing all tokens as custom properties inside `:root { ... }`
-- Optionally, one or more **W3C DTCG JSON/JSONC** files, independent of any specific consuming tool (usable in Penpot, Figma via plugin, Token Studio, ...).
-
-#### Usage
-
-```sh
-npx buildTokens --config ./path/to/tokens-config.mjs
-```
-
-#### Source files
-
-The `source` array accepts any combination of:
-- Concrete file paths: `'./tokens/colors.jsonc'`
-- Glob patterns: `'./tokens/**/*.{json,jsonc,mjs}'`
-
-**Supported formats:**
-- `.json` / `.jsonc` — parsed directly as token data
-- `.mjs` / `.js` — imported as ES modules; must export a W3C DTCG-compliant object as `default`
-
-
-#### Token file format (JS example)
-
-When using `.mjs` source files, export a default object following the [W3C Design Token Community Group format](https://design-tokens.github.io/community-group/format/):
-
-```js
-// colors.tokens.mjs
-export default {
-  color: {
-    brand: {
-      primary: { $type: 'color', $value: '#0057FF' },
-      secondary: { $type: 'color', $value: '#FF6B00' },
-    },
-    neutral: {
-      '100': { $type: 'color', $value: '#F5F5F5' },
-      '900': { $type: 'color', $value: '#1A1A1A' },
-    },
-  },
-  semantic: {
-    color: {
-      text: {
-        primary: { $type: 'color', $value: '{color.neutral.900}' }, // alias
-      },
-    },
-  },
-};
-```
-
-The main advantage of `.mjs` over `.json` is the ability to use JavaScript variables, comments, and computed values within the token definition.
-
-Values can be expressions like `"{size.base} * .25"`, see `tokens-config-sample.mjs` for more info.
-
-#### Custom transforms
-
-The following transforms are registered on top of Style Dictionary's built-ins:
-
-| Name | Type | Description |
-|---|---|---|
-| `shadow/css` | value | Converts shadow objects (single or array) to a `box-shadow` CSS string. px values are converted to rem. |
-| `size/pxToRem-smart` | value | Converts `dimension` token values from px to rem. Skips values already in rem. |
-| `color/css-modern` | value | Color passthrough with transitive alias support. |
-| `gradient/css` | value | Converts gradient objects to CSS `linear-gradient`, `radial-gradient` or `conic-gradient`. |
-| `composite/css` | value | Converts `border`, `outline`, `transition` and `animation` objects to their CSS shorthand. |
-| `typography/css` | value | Typography passthrough — the format handles exploding the value into individual properties. |
-
-#### CSS output
-
-All tokens are output as CSS custom properties inside `:root`, sorted alphabetically.
-
-Typography tokens are expanded into multiple properties:
-- `--token-name-font` — a `font` shorthand (when both `fontSize` and `fontFamily` are present)
-- `--token-name-letter-spacing`, `--token-name-text-transform`, `--token-name-text-decoration` — individual properties
-
-The generated file is linted and auto-fixed with stylelint using the config specified in `stylelintConfigPath`.
-
-#### JSON output
-
-When `jsonBuildPath` is set, the script also generates W3C DTCG token files, independent of any specific consuming tool (e.g. importable into Penpot via the [Design Tokens plugin](https://penpot.app/penpot-files/design-tokens), into Figma via a compatible plugin, or into Token Studio).
-
-**Single file** (`jsonDestFile` is a string):
-```
-jsonBuildPath/tokens.jsonc   ← all tokens in one file
-```
-
-**One file per source** (`jsonDestFile` is `null` or omitted):
-```
-jsonBuildPath/colors.tokens.jsonc
-jsonBuildPath/spacing.tokens.jsonc
-jsonBuildPath/typography.tokens.jsonc
-```
-All files are written flat in `jsonBuildPath`, regardless of the subdirectory structure of the source files — no subdirectories are created. If two source files with different paths would produce the same output filename, the build fails with an error listing the colliding files instead of silently overwriting one with the other.
-
-The `jsonFormat` option controls the output:
-
-| Value | Extension | Disclaimer header |
-|---|---|---|
-| `'jsonc'` | `.jsonc` | Yes |
-| `'json'` | `.json` | No |
-
-Alias references (`{color.brand.primary}`) are preserved in the output so consuming tools maintain token links between primitive and semantic tokens.
-
-> JSON token files intentionally use a minimal set of transforms (no px→rem conversion, no shorthand expansion) because consuming tools generally expect original values and structured objects, not resolved CSS strings.
-
----
-
-### `check-unresolved-custom-props.mjs`
-
-Scans all `.css` files in `dirToCheck` (recursively) and reports:
-
-- **unresolved properties** — `var(--...)` references that are not defined in the generated token CSS file or in any `extraCustomPropsFiles`
-- **unused properties** — custom properties defined in the generated token CSS file (or an `extraCustomPropsFiles` entry) but never referenced via `var()` in any scanned CSS file. Only reported if `checkUnused: true` is set in the config, since it re-runs the Style Dictionary transform pipeline over the token sources to resolve, when possible, the `.mjs` source file for each unused property. When `ignoreUnusedInNodeModules` is true (default), properties sourced from a token file under `node_modules` (e.g. a third-party token package) are never reported as unused.
-
-Results are written to `unresolved-unused-props.md` in the same directory as the config file.
-
-#### Usage
-
-```sh
-npx checkUnresolvedProps --config ./path/to/tokens-config.mjs
-```
-
-#### Output
-
-The script creates a `unresolved-unused-props.md` file next to the config file (only if there is at least one unresolved or unused property). Each unresolved entry links to the file and line number where the property is used; each unused entry links to its `.mjs` token source file when it can be resolved, otherwise just the property name is reported:
-
-```markdown
-## Unresolved custom properties
-
-* [components.css](../src/components.css#L42) -> `--color-action-hover`
-* [layout.css](../src/layout.css#L17) -> `--spacing-missing`
-
-## Unused custom properties
-
-* [colors.minimo.tokens.mjs](../_src/colors.minimo.tokens.mjs) -> `--color-legacy-accent`
-* `--manually-added-prop`
-```
-
-In VS Code, Option/Alt-clicking on the URL opens the file at the required line.
-
-
-#### Excluding properties
-
-Use `excludePattern` to suppress false positives — for example, internal/private custom properties that are defined dynamically or inline:
-
-```js
-// skips all custom props starting with `--_` or `--js-`
-excludePattern: [
-  /^--_/,          
-  /^--js-/,        
-]
-```
+The Node.js scripts that generate the CSS custom properties / JSON token files from the sources in this directory (`build-tokens.mjs`, `check-unresolved-custom-props.mjs`, exposed as the `buildTokens` / `checkUnresolvedProps` bins) live in [dev-tools/design-tokens-builder](../dev-tools/design-tokens-builder/README.md), alongside the other standalone dev-tools CLI utilities.

package/dev-tools/README.md

@@ -6,6 +6,7 @@ A collection of standalone Node.js CLI utilities to help manage a web project's
 * [Svg Icons Tools](./svg-icons-tools/README.md) — optimizes SVG icons and combines/converts them into symbols, JSX, or SCSS variables
 * [Create favicons](./create-favicons/README.md) — generates the full favicon set (SVG, PNG, ICO, webmanifest, HTML snippet) from a source image
 * [upd@m](./upd@m/README.md) — updates all `@massimo-cassandro/*` packages installed in `node_modules`
+* [Design Tokens Builder](./design-tokens-builder/README.md) — generates a CSS custom properties file (and optional JSON token files) from design token sources
 * [starter-kit](#starter-kit) — script for installing minimo environment
 
 ## starter-kit

package/dev-tools/design-tokens-builder/README.md

@@ -0,0 +1,208 @@
+# Design Tokens Builder
+
+<!-- TODO rivedere e semplificare -->
+
+A set of Node.js scripts for managing CSS design tokens in a project. Built on top of [Style Dictionary v5](https://styledictionary.com/).
+
+### Scripts
+
+| Script | Purpose |
+|---|---|
+| `build-tokens.mjs` | Generates a CSS custom properties file from design token source files |
+| `check-unresolved-custom-props.mjs` | Scans CSS files and reports any `var(--...)` references not found in the generated token file |
+
+Both scripts share the same config file, passed via `--config`.
+
+### Setup
+
+The scripts are intended to be used as npm scripts. Add them to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build tokens": "npx buildTokens --config ./path/to/tokens-config.mjs",
+    "check unresolved props": "npx checkUnresolvedProps --config ./path/to/tokens-config.mjs"
+  }
+}
+```
+
+### Dependencies
+
+The following packages must be present in your project:
+
+```json
+{
+  "style-dictionary": "^5",
+  "stylelint": "^16"
+}
+```
+
+### Configuration file
+
+Both scripts read a shared config file passed with `--config`. Use `tokens-config-sample.mjs` as a starting point.
+
+Read comments inside the sample file for more info.
+
+
+### `build-tokens.mjs`
+
+Reads design token source files and generates:
+- A **CSS file** containing all tokens as custom properties inside `:root { ... }`
+- Optionally, one or more **W3C DTCG JSON/JSONC** files, independent of any specific consuming tool (usable in Penpot, Figma via plugin, Token Studio, ...).
+
+#### Usage
+
+```sh
+npx buildTokens --config ./path/to/tokens-config.mjs
+```
+
+#### Source files
+
+The `source` array accepts any combination of:
+- Concrete file paths: `'./tokens/colors.jsonc'`
+- Glob patterns: `'./tokens/**/*.{json,jsonc,mjs}'`
+
+**Supported formats:**
+- `.json` / `.jsonc` — parsed directly as token data
+- `.mjs` / `.js` — imported as ES modules; must export a W3C DTCG-compliant object as `default`
+
+
+#### Token file format (JS example)
+
+When using `.mjs` source files, export a default object following the [W3C Design Token Community Group format](https://design-tokens.github.io/community-group/format/):
+
+```js
+// colors.tokens.mjs
+export default {
+  color: {
+    brand: {
+      primary: { $type: 'color', $value: '#0057FF' },
+      secondary: { $type: 'color', $value: '#FF6B00' },
+    },
+    neutral: {
+      '100': { $type: 'color', $value: '#F5F5F5' },
+      '900': { $type: 'color', $value: '#1A1A1A' },
+    },
+  },
+  semantic: {
+    color: {
+      text: {
+        primary: { $type: 'color', $value: '{color.neutral.900}' }, // alias
+      },
+    },
+  },
+};
+```
+
+The main advantage of `.mjs` over `.json` is the ability to use JavaScript variables, comments, and computed values within the token definition.
+
+Values can be expressions like `"{size.base} * .25"`, see `tokens-config-sample.mjs` for more info.
+
+#### Custom transforms
+
+The following transforms are registered on top of Style Dictionary's built-ins:
+
+| Name | Type | Description |
+|---|---|---|
+| `shadow/css` | value | Converts shadow objects (single or array) to a `box-shadow` CSS string. px values are converted to rem. |
+| `size/pxToRem-smart` | value | Converts `dimension` token values from px to rem. Skips values already in rem. |
+| `color/css-modern` | value | Color passthrough with transitive alias support. |
+| `gradient/css` | value | Converts gradient objects to CSS `linear-gradient`, `radial-gradient` or `conic-gradient`. |
+| `composite/css` | value | Converts `border`, `outline`, `transition` and `animation` objects to their CSS shorthand. |
+| `typography/css` | value | Typography passthrough — the format handles exploding the value into individual properties. |
+
+#### CSS output
+
+All tokens are output as CSS custom properties inside `:root`, sorted alphabetically.
+
+Typography tokens are expanded into multiple properties:
+- `--token-name-font` — a `font` shorthand (when both `fontSize` and `fontFamily` are present)
+- `--token-name-letter-spacing`, `--token-name-text-transform`, `--token-name-text-decoration` — individual properties
+
+The generated file is linted and auto-fixed with stylelint using the config specified in `stylelintConfigPath`.
+
+#### JSON output
+
+When `jsonBuildPath` is set, the script also generates W3C DTCG token files, independent of any specific consuming tool (e.g. importable into Penpot via the [Design Tokens plugin](https://penpot.app/penpot-files/design-tokens), into Figma via a compatible plugin, or into Token Studio).
+
+**Single file** (`jsonDestFile` is a string):
+```
+jsonBuildPath/tokens.jsonc   ← all tokens in one file
+```
+
+**One file per source** (`jsonDestFile` is `null` or omitted):
+```
+jsonBuildPath/colors.tokens.jsonc
+jsonBuildPath/spacing.tokens.jsonc
+jsonBuildPath/typography.tokens.jsonc
+```
+All files are written flat in `jsonBuildPath`, regardless of the subdirectory structure of the source files — no subdirectories are created. If two source files with different paths would produce the same output filename, the build fails with an error listing the colliding files instead of silently overwriting one with the other.
+
+The `jsonFormat` option controls the output:
+
+| Value | Extension | Disclaimer header |
+|---|---|---|
+| `'jsonc'` | `.jsonc` | Yes |
+| `'json'` | `.json` | No |
+
+Alias references (`{color.brand.primary}`) are preserved in the output so consuming tools maintain token links between primitive and semantic tokens.
+
+> JSON token files intentionally use a minimal set of transforms (no px→rem conversion, no shorthand expansion) because consuming tools generally expect original values and structured objects, not resolved CSS strings.
+
+#### sourceModes (light/dark split)
+
+`sourceModes` is an alternative to `source`, for projects that need a light/dark (or other) custom properties split. See the comments in `tokens-config-sample.mjs` for the full option reference (`sourceModes`, `sourceModesBase`).
+
+When set, each mode has its own `source` array, and the generated CSS composes all modes into a single `destFile`:
+- the base mode's props go in a top-level `:root { ... }` block, with `color-scheme: <all modes>;` prepended
+- every other mode's props go in `@media (prefers-color-scheme: <mode>) { :root { ... } }`, with `color-scheme: <mode>;` prepended
+
+`customPropsGroups`, `mergeCustomProps`, `addLayer`, `pxToRem` etc. all apply the same way as with a single `source`. The JSON output (when `jsonBuildPath` is set) is produced once per mode, with the mode name appended to each filename (e.g. `tokens-light.jsonc` / `tokens-dark.jsonc`).
+
+---
+
+### `check-unresolved-custom-props.mjs`
+
+Scans all `.css` files in `dirToCheck` (recursively) and reports:
+
+- **unresolved properties** — `var(--...)` references that are not defined in the generated token CSS file or in any `extraCustomPropsFiles`
+- **unused properties** — custom properties defined in the generated token CSS file (or an `extraCustomPropsFiles` entry) but never referenced via `var()` in any scanned CSS file. Only reported if `checkUnused: true` is set in the config, since it re-runs the Style Dictionary transform pipeline over the token sources to resolve, when possible, the `.mjs` source file for each unused property. When `ignoreUnusedInNodeModules` is true (default), properties sourced from a token file under `node_modules` (e.g. a third-party token package) are never reported as unused.
+
+Results are written to `unresolved-unused-props.md` in the same directory as the config file.
+
+#### Usage
+
+```sh
+npx checkUnresolvedProps --config ./path/to/tokens-config.mjs
+```
+
+#### Output
+
+The script creates a `unresolved-unused-props.md` file next to the config file (only if there is at least one unresolved or unused property). Each unresolved entry links to the file and line number where the property is used; each unused entry links to its `.mjs` token source file when it can be resolved, otherwise just the property name is reported:
+
+```markdown
+## Unresolved custom properties
+
+* [components.css](../src/components.css#L42) -> `--color-action-hover`
+* [layout.css](../src/layout.css#L17) -> `--spacing-missing`
+
+## Unused custom properties
+
+* [colors.minimo.tokens.mjs](../_src/colors.minimo.tokens.mjs) -> `--color-legacy-accent`
+* `--manually-added-prop`
+```
+
+In VS Code, Option/Alt-clicking on the URL opens the file at the required line.
+
+
+#### Excluding properties
+
+Use `excludePattern` to suppress false positives — for example, internal/private custom properties that are defined dynamically or inline:
+
+```js
+// skips all custom props starting with `--_` or `--js-`
+excludePattern: [
+  /^--_/,          
+  /^--js-/,        
+]
+```

package/dev-tools/design-tokens-builder/build-tokens-src/build-source-modes.mjs

@@ -0,0 +1,152 @@
+// build-tokens-src/build-source-modes.mjs
+// Alternative build path used when the project config sets `sourceModes`
+// (see config.mjs) instead of a single `source` array — typically for a
+// light/dark custom-properties split.
+//
+// For each mode, a separate StyleDictionary instance is built from that
+// mode's own `source` array. The generated `:root { ... }` CSS blocks are
+// then composed into a single destFile:
+//   - the base mode's block stays as a plain `:root { ... }` rule, with a
+//     `color-scheme: <all modes joined>;` declaration prepended
+//     (e.g. "light dark")
+//   - every other mode's block is wrapped in
+//     `@media (prefers-color-scheme: <mode>) { :root { ... } }`, with a
+//     `color-scheme: <mode>;` declaration prepended
+// customPropsGroups, mergeCustomProps and pxToRem apply per mode, exactly as
+// in the single-source build. addLayer (if set) wraps the whole composed
+// result in a single `@layer`, rather than one per mode.
+//
+// JSON tokens (if jsonBuildPath is set) are produced per mode: one set of
+// files per mode, with `-<mode>` appended to each filename (see
+// buildJsonFiles() in formats/json.mjs), e.g. "tokens-light.jsonc" /
+// "tokens-dark.jsonc", or "size-light.jsonc" / "size-dark.jsonc" in
+// multi-file mode (jsonDestFile: null).
+
+import StyleDictionary from 'style-dictionary';
+import * as path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { CSS_TRANSFORMS, JSON_TRANSFORMS } from './platforms.mjs';
+import { customPropsCount } from './formats/css.mjs';
+import { buildJsonFiles, collectConcreteFilePaths } from './formats/json.mjs';
+import { loadExistingCustomPropsScoped } from './merge-css.mjs';
+
+/**
+ * @param {object}                 opts
+ * @param {Record<string,string[]>} opts.sourceModes    Resolved source paths per mode (see config.mjs)
+ * @param {string}                 opts.baseMode        Mode whose block stays a top-level `:root { ... }` rule
+ * @param {string}                 opts.buildPath        Absolute path for CSS output directory
+ * @param {string}                 opts.destFile         CSS output filename
+ * @param {string|null}            opts.jsonBuildPath    Absolute path for JSON output (null = disabled)
+ * @param {string|null}            opts.jsonDestFile     Base name for aggregated JSON file; null = one file per source
+ * @param {'json'|'jsonc'}         opts.jsonFormat        Output format for JSON files
+ * @param {'keep'|'calc'|'resolve'} opts.jsonExpression   How to handle math expressions in dimension tokens
+ * @param {{name:string,prefixes:string[]}[]} opts.customPropsGroups
+ * @param {boolean}                opts.pxToRem
+ * @param {string|null}            opts.addLayer
+ * @param {boolean}                opts.mergeCustomProps
+ * @returns {Promise<{cssDestPath: string, totalCustomProps: number, jsonFilesByMode: Record<string, object[]>}>}
+ */
+export const buildSourceModes = async ({
+  sourceModes,
+  baseMode,
+  buildPath,
+  destFile,
+  jsonBuildPath,
+  jsonDestFile,
+  jsonFormat,
+  jsonExpression,
+  customPropsGroups,
+  pxToRem,
+  addLayer,
+  mergeCustomProps,
+}) => {
+  const modeNames = Object.keys(sourceModes);
+
+  // Read the pre-existing destFile (if any) BEFORE any Style Dictionary
+  // instance runs, since the first one to write would overwrite it.
+  if (mergeCustomProps) {
+    loadExistingCustomPropsScoped(path.join(buildPath, destFile), baseMode);
+  }
+
+  const cssTransforms = pxToRem
+    ? CSS_TRANSFORMS
+    : CSS_TRANSFORMS.filter((name) => name !== 'size/pxToRem-smart');
+
+  /** @type {Record<string,string>} */
+  const modeBlocks = {};
+  let totalCustomProps = 0;
+  /** @type {Record<string, object[]>} */
+  const jsonFilesByMode = {};
+
+  for (const mode of modeNames) {
+    const sd = new StyleDictionary({
+      source: sourceModes[mode],
+      log: { verbosity: 'verbose' },
+      platforms: {
+        css: {
+          transforms: cssTransforms,
+          files: [
+            {
+              destination: destFile,
+              format: 'css/variables-sorted',
+              options: {
+                outputReferences: true,
+                customPropsGroups,
+                mode,
+                colorScheme: mode === baseMode ? modeNames.join(' ') : mode,
+              },
+            },
+          ],
+        },
+      },
+    });
+
+    // formatPlatform() runs the format function without writing to disk —
+    // the composed multi-mode file is written once, at the end, below.
+    const [formatted] = await sd.formatPlatform('css');
+    modeBlocks[mode] = /** @type {string} */ (formatted.output);
+    // customPropsCount is a live binding, updated synchronously by the
+    // format function called above (see formats/css.mjs).
+    totalCustomProps += customPropsCount;
+
+    if (jsonBuildPath) {
+      const concreteFilePaths = jsonDestFile ? [] : await collectConcreteFilePaths(sd);
+      const files = buildJsonFiles(concreteFilePaths, jsonDestFile, jsonFormat, jsonExpression, `-${mode}`);
+
+      const jsonSd = new StyleDictionary({
+        source: sourceModes[mode],
+        log: { verbosity: 'silent' },
+        platforms: {
+          json: {
+            buildPath: jsonBuildPath + '/',
+            transforms: JSON_TRANSFORMS,
+            files,
+          },
+        },
+      });
+      await jsonSd.buildAllPlatforms();
+      jsonFilesByMode[mode] = files;
+    }
+  }
+
+  // ── Compose the final CSS ────────────────────────────────────────────────
+  const otherModes = modeNames.filter((mode) => mode !== baseMode);
+
+  let composed = modeBlocks[baseMode];
+  for (const mode of otherModes) {
+    composed += `\n@media (prefers-color-scheme: ${mode}) {\n${modeBlocks[mode]}}\n`;
+  }
+
+  // addLayer wraps the whole composed result once, rather than once per
+  // mode. Indentation is left to stylelint's fix step (run right after the
+  // build), same as the single-source build.
+  const finalCss = addLayer
+    ? `@layer ${addLayer} {\n\n${composed}}\n`
+    : composed;
+
+  await mkdir(buildPath, { recursive: true });
+  const cssDestPath = path.join(buildPath, destFile);
+  await writeFile(cssDestPath, finalCss);
+
+  return { cssDestPath, totalCustomProps, jsonFilesByMode };
+};

package/{design-tokens/utilities → dev-tools/design-tokens-builder}/build-tokens-src/config.mjs

@@ -110,5 +110,39 @@ export const customPropsGroups = Array.isArray(buildConfig.customPropsGroups)
 // path.join() — it may corrupt the pattern syntax. Use template literals:
 //   OK:  `${minimo_path}/**/*.{json,mjs}`
 //   NO:  path.join(minimo_path, '/**/*.{json,mjs}')
+//
+// sourceModes: alternative to `source`, for a light/dark (or other) custom
+// properties split — see build-tokens-src/build-source-modes.mjs. When set
+// (buildConfig.sourceModes is a non-null object), `source` is ignored and
+// each mode's own array of source patterns is resolved the same way.
 // ---------------------------------------------------------------------------
-export const source = resolveSourcePaths(buildConfig.source, configDir);
+const sourceModesRaw = buildConfig.sourceModes ?? null;
+
+export const sourceModes = sourceModesRaw
+  ? Object.fromEntries(
+    Object.entries(sourceModesRaw).map(([mode, modeSource]) => [
+      mode,
+      resolveSourcePaths(modeSource, configDir),
+    ])
+  )
+  : null;
+
+// sourceModesBase: the mode whose declarations are written to the top-level
+// `:root { ... }` block (the others are nested under
+// `@media (prefers-color-scheme: <mode>) { ... }`). Default: the first key
+// of sourceModes (insertion order), e.g. 'light'. Ignored when sourceModes
+// is not set.
+export const sourceModesBase = sourceModes
+  ? (Object.prototype.hasOwnProperty.call(sourceModes, buildConfig.sourceModesBase)
+    ? buildConfig.sourceModesBase
+    : Object.keys(sourceModes)[0])
+  : null;
+
+if (sourceModes && buildConfig.sourceModesBase && sourceModesBase !== buildConfig.sourceModesBase) {
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[build-tokens] config: sourceModesBase "${buildConfig.sourceModesBase}" is not a key of sourceModes — falling back to "${sourceModesBase}"`
+  );
+}
+
+export const source = sourceModes ? null : resolveSourcePaths(buildConfig.source, configDir);

package/{design-tokens/utilities → dev-tools/design-tokens-builder}/build-tokens-src/formats/css.mjs

@@ -252,11 +252,14 @@ StyleDictionary.registerFormat({
 
     // Build a name → declaration-tail map from the declarations generated
     // above, then merge with any pre-existing custom properties loaded via
-    // loadExistingCustomProps() (see ../merge-css.mjs). Pre-existing values
-    // (including trailing comments) take priority when both exist;
-    // pre-existing-only properties are kept.
+    // loadExistingCustomProps() / loadExistingCustomPropsScoped() (see
+    // ../merge-css.mjs). Pre-existing values (including trailing comments)
+    // take priority when both exist; pre-existing-only properties are kept.
+    // options.mode (sourceModes build only, see ../build-source-modes.mjs)
+    // scopes the merge to that mode, so same-named props with different
+    // values across modes are never mixed up.
     const generatedProps = parseCustomProps(lines.join('\n'));
-    const finalProps = mergeCustomProps(generatedProps);
+    const finalProps = mergeCustomProps(generatedProps, options.mode ?? null);
 
     // Final output is always sorted alphabetically ascending by property
     // name, regardless of merge — this also keeps pre-existing-only
@@ -295,6 +298,15 @@ StyleDictionary.registerFormat({
     // first hyphen-separated segment (e.g. all `btn-*` together), to visually
     // group related custom properties in the generated file.
     const outLines = [];
+
+    // options.colorScheme (sourceModes build only, see ../build-source-modes.mjs):
+    // prepends a `color-scheme: <value>;` declaration, e.g. "light dark" for
+    // the base mode's block, or the mode's own name (e.g. "dark") for a
+    // block nested inside its @media (prefers-color-scheme: <mode>) rule.
+    if (options.colorScheme) {
+      outLines.push(`  color-scheme: ${options.colorScheme};`, '');
+    }
+
     let prevPrefix = null;
     const appendBlock = (props) => {
       for (const [name, tail] of props) {