@massimo-cassandro/minimo 1.33.6 → 1.34.0

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

@@ -216,20 +216,25 @@ export const collectConcreteFilePaths = async (sd) => {
 // @param {string|null}                    jsonDestFile       Aggregated file base name, or null
 // @param {'json'|'jsonc'}                 jsonFormat         Output format
 // @param {'keep'|'calc'|'resolve'}        jsonExpression     Expression handling mode
+// @param {string}                         [suffix]           Appended to every destination
+//   filename, before the extension — used by the sourceModes build
+//   (build-source-modes.mjs) to produce one set of files per mode, e.g.
+//   "-light" -> "tokens-light.jsonc" / "size-light.jsonc" (default: '')
 // @returns {object[]}  File descriptors for the Style Dictionary platform
 
 export const buildJsonFiles = (
   concreteFilePaths,
   jsonDestFile,
   jsonFormat = 'json',
-  jsonExpression = 'keep'
+  jsonExpression = 'keep',
+  suffix = ''
 ) => {
   const ext  = jsonFormat === 'jsonc' ? '.jsonc' : '.json';
   const jsonc = jsonFormat === 'jsonc';
 
   if (jsonDestFile) {
     return [{
-      destination: jsonDestFile + ext,
+      destination: jsonDestFile + suffix + ext,
       format: 'json/tokens',
       options: { jsonc, jsonExpression },
     }];
@@ -242,7 +247,7 @@ export const buildJsonFiles = (
   // one silently overwrite the other.
   const pathsByDestName = new Map();
   for (const filePath of concreteFilePaths) {
-    const destName = path.basename(filePath).replace(/\.[^.]+$/, '') + ext;
+    const destName = path.basename(filePath).replace(/\.[^.]+$/, '') + suffix + ext;
     if (!pathsByDestName.has(destName)) pathsByDestName.set(destName, []);
     pathsByDestName.get(destName).push(filePath);
   }
@@ -260,7 +265,7 @@ export const buildJsonFiles = (
   return concreteFilePaths.map((filePath) => {
     const absPath = path.resolve(filePath);
     return {
-      destination: path.basename(filePath).replace(/\.[^.]+$/, '') + ext,
+      destination: path.basename(filePath).replace(/\.[^.]+$/, '') + suffix + ext,
       format: 'json/tokens',
       options: { jsonc, jsonExpression },
       filter: (token) => {

package/dev-tools/design-tokens-builder/build-tokens-src/merge-css.mjs

@@ -0,0 +1,192 @@
+// build-tokens-src/merge-css.mjs
+// Supports the `mergeCustomProps` config option: pre-existing custom
+// properties in the CSS destination file take priority over the ones
+// generated by the current build (manual overrides/additions survive rebuilds).
+//
+// Usage (single `source` build):
+//   1. Call loadExistingCustomProps(absDestPath) BEFORE Style Dictionary runs,
+//      since it reads the file that is about to be overwritten.
+//   2. The css/variables-sorted format (see formats/css.mjs) calls
+//      mergeCustomProps(generatedMap) while building the output, right before
+//      serialising the final CSS text.
+//
+// Usage (sourceModes build, see build-source-modes.mjs):
+//   1. Call loadExistingCustomPropsScoped(absDestPath, baseMode) BEFORE any
+//      of the per-mode Style Dictionary instances run.
+//   2. The css/variables-sorted format calls mergeCustomProps(generatedMap, mode)
+//      once per mode. Declarations are matched only within the same mode's
+//      scope (the base `:root { ... }` block, or the `:root { ... }` nested
+//      inside that mode's `@media (prefers-color-scheme: <mode>) { ... }`),
+//      so the same custom property name defined with different values across
+//      modes is never mixed up.
+
+import { existsSync, readFileSync } from 'node:fs';
+
+const CUSTOM_PROP_RE = /^\s*--([\w-]+):\s*(.+)$/gm;
+
+/**
+ * Parses `--name: <tail>` declarations out of a CSS text block. <tail> is
+ * captured verbatim (value, terminating `;`, and anything else on the same
+ * line, e.g. a trailing comment) so it round-trips unchanged through a merge.
+ * Only single-line declarations are supported.
+ * @param {string} cssText
+ * @returns {Record<string,string>} name → declaration-tail map, in first-seen order
+ */
+export const parseCustomProps = (cssText) => {
+  /** @type {Record<string,string>} */
+  const map = {};
+  for (const match of cssText.matchAll(CUSTOM_PROP_RE)) {
+    map[match[1]] = match[2].trim();
+  }
+  return map;
+};
+
+// Returns the index of the closing brace matching the `{` at openIndex, by
+// simple depth counting. Braces inside comments/strings are not special-cased
+// — not expected to occur in generated custom-properties CSS.
+/** @param {string} text @param {number} openIndex */
+const matchBraces = (text, openIndex) => {
+  let depth = 0;
+  for (let i = openIndex; i < text.length; i++) {
+    if (text[i] === '{') depth++;
+    else if (text[i] === '}') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+};
+
+// Finds every @media (prefers-color-scheme: <mode>) { ... } block in a
+// previously generated sourceModes CSS destFile, with absolute character
+// offsets into cssText. Used to split the file into per-mode scopes (see
+// splitModeScopes() below) and, by check-unresolved-custom-props.mjs, to
+// tell which mode a given custom property declaration belongs to.
+// An optional wrapping `@layer { ... }` (addLayer option) is transparent to
+// this search, since it only looks for the `@media (prefers-color-scheme: ...)`
+// pattern itself.
+// @param {string} cssText
+// @returns {{mode:string,start:number,end:number}[]} start/end are the
+//   indices of the block's outer `{`/matching `}` (inclusive)
+export const findMediaModeBlocks = (cssText) => {
+  const MEDIA_RE = /@media\s*\(\s*prefers-color-scheme\s*:\s*([\w-]+)\s*\)\s*\{/g;
+  /** @type {{mode:string,start:number,end:number}[]} */
+  const mediaBlocks = [];
+  for (const match of cssText.matchAll(MEDIA_RE)) {
+    const openIdx = match.index + match[0].length - 1;
+    const closeIdx = matchBraces(cssText, openIdx);
+    if (closeIdx === -1) continue;
+    mediaBlocks.push({ mode: match[1], start: openIdx, end: closeIdx });
+  }
+  return mediaBlocks;
+};
+
+// Splits a previously generated sourceModes CSS destFile into per-mode
+// scopes (see build-source-modes.mjs for the shape of the generated file):
+//   - the base scope is the top-level `:root { ... }` block, i.e. the one
+//     NOT nested inside a `@media (prefers-color-scheme: ...)` rule
+//   - every other scope is the `:root { ... }` block nested inside its own
+//     `@media (prefers-color-scheme: <mode>) { ... }` rule
+// @param {string} cssText
+// @returns {Record<string,string>} mode → CSS body text (base mode keyed as '__base__')
+const splitModeScopes = (cssText) => {
+  /** @type {Record<string,string>} */
+  const scopes = {};
+
+  // 1. Every @media (prefers-color-scheme: <mode>) { ... } block, and the
+  // :root { ... } body nested inside each one.
+  const mediaBlocks = findMediaModeBlocks(cssText);
+  for (const { mode, start, end } of mediaBlocks) {
+    const body = cssText.slice(start + 1, end);
+    const rootMatch = /:root\s*\{/.exec(body);
+    if (rootMatch) {
+      const rootOpen = rootMatch.index + rootMatch[0].length - 1;
+      const rootClose = matchBraces(body, rootOpen);
+      if (rootClose !== -1) {
+        scopes[mode] = body.slice(rootOpen + 1, rootClose);
+      }
+    }
+  }
+
+  // 2. The base :root { ... } block: the first one not nested inside any of
+  // the media blocks found above.
+  const ROOT_RE = /:root\s*\{/g;
+  for (const match of cssText.matchAll(ROOT_RE)) {
+    const openIdx = match.index + match[0].length - 1;
+    const insideMedia = mediaBlocks.some((b) => openIdx > b.start && openIdx < b.end);
+    if (insideMedia) continue;
+    const closeIdx = matchBraces(cssText, openIdx);
+    if (closeIdx === -1) continue;
+    scopes.__base__ = cssText.slice(openIdx + 1, closeIdx);
+    break;
+  }
+
+  return scopes;
+};
+
+// null = merge disabled, or destination file not found yet (first build)
+/** @type {Record<string,string>|null} */
+let existingCustomProps = null;
+
+// Per-mode equivalent of existingCustomProps, populated by
+// loadExistingCustomPropsScoped() for a sourceModes build.
+/** @type {Record<string, Record<string,string>>|null} */
+let scopedExistingCustomProps = null;
+
+/**
+ * Reads the CSS destination file (if it exists) and stores a name → value
+ * map of its current custom properties for later merging.
+ * @param {string} absDestPath absolute path of the CSS file to read
+ * @returns {Record<string,string>|null}
+ */
+export const loadExistingCustomProps = (absDestPath) => {
+  existingCustomProps = existsSync(absDestPath)
+    ? parseCustomProps(readFileSync(absDestPath, 'utf8'))
+    : null;
+  return existingCustomProps;
+};
+
+/**
+ * sourceModes equivalent of loadExistingCustomProps(): reads the CSS
+ * destination file (if it exists) and stores a per-mode name → value map,
+ * scoped to each mode's own `:root { ... }` block (see splitModeScopes()).
+ * @param {string} absDestPath absolute path of the CSS file to read
+ * @param {string} baseMode mode whose declarations live in the top-level,
+ *   non-nested `:root { ... }` block (no default — always passed explicitly
+ *   by build-source-modes.mjs, from the resolved sourceModesBase)
+ * @returns {Record<string, Record<string,string>>|null}
+ */
+export const loadExistingCustomPropsScoped = (absDestPath, baseMode) => {
+  if (!existsSync(absDestPath)) {
+    scopedExistingCustomProps = null;
+    return scopedExistingCustomProps;
+  }
+  const scopes = splitModeScopes(readFileSync(absDestPath, 'utf8'));
+  scopedExistingCustomProps = {};
+  if (scopes.__base__ !== undefined) {
+    scopedExistingCustomProps[baseMode] = parseCustomProps(scopes.__base__);
+  }
+  for (const [mode, body] of Object.entries(scopes)) {
+    if (mode === '__base__') continue;
+    scopedExistingCustomProps[mode] = parseCustomProps(body);
+  }
+  return scopedExistingCustomProps;
+};
+
+/**
+ * Merges freshly generated custom properties with the ones previously loaded
+ * via loadExistingCustomProps() / loadExistingCustomPropsScoped(). Pre-existing
+ * values take priority; custom properties found only in the pre-existing file
+ * (no longer generated) are kept as well.
+ * @param {Record<string,string>} generated name → value map produced by this build
+ * @param {string|null} [mode] when set (sourceModes build), looks up the
+ *   pre-existing props scoped to this mode instead of the flat/global map (default: null)
+ * @returns {Record<string,string>}
+ */
+export const mergeCustomProps = (generated, mode = null) => {
+  if (mode !== null) {
+    const existing = scopedExistingCustomProps?.[mode];
+    return existing ? { ...generated, ...existing } : generated;
+  }
+  return existingCustomProps ? { ...generated, ...existingCustomProps } : generated;
+};

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

@@ -28,7 +28,9 @@ export const CSS_TRANSFORMS = [
 // Kept minimal on purpose: consuming tools expect original values (e.g. "16px"
 // not "1rem") and alias references ({...}) must be preserved to maintain
 // token links.
-const JSON_TRANSFORMS = [
+// Exported so build-source-modes.mjs can build a matching json platform per
+// sourceModes mode.
+export const JSON_TRANSFORMS = [
   'attribute/cti',
   'name/kebab',
   'color/css-modern',

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

@@ -12,6 +12,8 @@
 //   build-tokens-src/formats/css.mjs    <- registers the css/variables-sorted format
 //   build-tokens-src/formats/json.mjs   <- registers the json/tokens format, exports helpers
 //   build-tokens-src/platforms.mjs      <- builds the platforms object (css + optional json)
+//   build-tokens-src/build-source-modes.mjs  <- alternative build path used when sourceModes is set
+//   build-tokens-src/merge-css.mjs      <- supports the mergeCustomProps option (flat and per-mode)
 
 import StyleDictionary from 'style-dictionary';
 import * as path from 'node:path';
@@ -31,6 +33,8 @@ import {
   jsonFormat,
   jsonExpression,
   source,
+  sourceModes,
+  sourceModesBase,
   mergeCustomProps,
   customPropsGroups,
   pxToRem,
@@ -52,37 +56,15 @@ import { buildJsonFiles, collectConcreteFilePaths } from './build-tokens-src/for
 // ── 5. Platforms builder ──────────────────────────────────────────────────────
 import { buildPlatforms } from './build-tokens-src/platforms.mjs';
 
-// ── 5b. Pre-existing custom properties (mergeCustomProps option) ────────────
-// Read before Style Dictionary runs, since it overwrites the destination
-// file. The css/variables-sorted format (formats/css.mjs) merges these
-// values in — pre-existing values take priority — right before serialising
-// the final CSS output. See merge-css.mjs.
-if (mergeCustomProps) {
-  loadExistingCustomProps(path.join(buildPath, destFile));
-}
-
-// ── 6. Collect concrete source file paths (multi-file JSON mode only) ────────
-// Source entries may be glob patterns. SD expands them internally and stores
-// the concrete path in token.filePath. We need those concrete paths to build
-// the per-file descriptors for the json platform.
-//
-// SD v5 lazy-loads sources: `await sd.hasInitialized` triggers loading;
-// after that sd.allTokens is a plain synchronous array with filePath populated.
-//
-// In single-file mode (jsonDestFile is set) we skip this step entirely.
-let concreteFilePaths = [];
-
-if (jsonBuildPath && !jsonDestFile) {
-  const sdInit = new StyleDictionary({ source, log: { verbosity: 'silent' }, platforms: {} });
-  concreteFilePaths = await collectConcreteFilePaths(sdInit);
-}
+// ── 5b. sourceModes builder (alternative to the single-source build below) ──
+import { buildSourceModes } from './build-tokens-src/build-source-modes.mjs';
 
-// ── 7. Clean json output directory ───────────────────────────────────────────
+// ── 6. Clean json output directory ───────────────────────────────────────────
 // Remove only previously generated *.json/*.jsonc files, so that tokens
 // removed from the source are not left behind as stale artefacts, while any
 // other file placed in jsonBuildPath by the user (e.g. a README) is left
 // untouched. Files are written flat in jsonBuildPath (no subdirectories), so
-// only its top level is scanned.
+// only its top level is scanned. Runs regardless of sourceModes.
 if (jsonBuildPath) {
   const { readdir, rm, mkdir } = await import('fs/promises');
   const existingEntries = await readdir(jsonBuildPath, { withFileTypes: true }).catch(() => []);
@@ -94,27 +76,82 @@ if (jsonBuildPath) {
   await mkdir(jsonBuildPath, { recursive: true });
 }
 
-// ── 8. Build ──────────────────────────────────────────────────────────────────
-const sd = new StyleDictionary({
-  source,
-  log: { verbosity: 'verbose' },
-  platforms: buildPlatforms({
+// ── 7. Build ──────────────────────────────────────────────────────────────────
+// concreteFilePaths / modeResult are used below in the log section (10).
+/** @type {string[]} */
+let concreteFilePaths = [];
+/** @type {Awaited<ReturnType<typeof buildSourceModes>>|null} */
+let modeResult = null;
+
+if (sourceModes) {
+  // sourceModes build: one StyleDictionary instance per mode, composed into
+  // a single destFile — see build-tokens-src/build-source-modes.mjs.
+  modeResult = await buildSourceModes({
+    sourceModes,
+    baseMode: sourceModesBase,
     buildPath,
     destFile,
     jsonBuildPath,
     jsonDestFile,
     jsonFormat,
     jsonExpression,
-    concreteFilePaths,
     customPropsGroups,
     pxToRem,
     addLayer,
-  }),
-});
+    mergeCustomProps,
+  });
 
-await sd.buildAllPlatforms();
+} else {
+  // Single-source build (default).
+
+  // Pre-existing custom properties (mergeCustomProps option): read before
+  // Style Dictionary runs, since it overwrites the destination file. The
+  // css/variables-sorted format (formats/css.mjs) merges these values in —
+  // pre-existing values take priority — right before serialising the final
+  // CSS output. See merge-css.mjs.
+  if (mergeCustomProps) {
+    loadExistingCustomProps(path.join(buildPath, destFile));
+  }
 
-// ── 9. CSS lint ───────────────────────────────────────────────────────────────
+  // Collect concrete source file paths (multi-file JSON mode only). Source
+  // entries may be glob patterns. SD expands them internally and stores the
+  // concrete path in token.filePath. We need those concrete paths to build
+  // the per-file descriptors for the json platform.
+  //
+  // SD v5 lazy-loads sources: `await sd.hasInitialized` triggers loading;
+  // after that sd.allTokens is a plain synchronous array with filePath populated.
+  //
+  // In single-file mode (jsonDestFile is set) we skip this step entirely.
+  // source is only null when sourceModes is set (see config.mjs); this
+  // branch runs exclusively when sourceModes is not set.
+  const singleSource = /** @type {string[]} */ (source);
+
+  if (jsonBuildPath && !jsonDestFile) {
+    const sdInit = new StyleDictionary({ source: singleSource, log: { verbosity: 'silent' }, platforms: {} });
+    concreteFilePaths = await collectConcreteFilePaths(sdInit);
+  }
+
+  const sd = new StyleDictionary({
+    source: singleSource,
+    log: { verbosity: 'verbose' },
+    platforms: buildPlatforms({
+      buildPath,
+      destFile,
+      jsonBuildPath,
+      jsonDestFile,
+      jsonFormat,
+      jsonExpression,
+      concreteFilePaths,
+      customPropsGroups,
+      pxToRem,
+      addLayer,
+    }),
+  });
+
+  await sd.buildAllPlatforms();
+}
+
+// ── 8. CSS lint ───────────────────────────────────────────────────────────────
 const stylelintConfig = await import(pathToFileURL(stylelintConfigPath).href).then(m => m.default);
 
 
@@ -124,24 +161,39 @@ await stylelint.lint({
   fix: true,
 });
 
-// ── 10. Log ────────────────────────────────────────────────────────────────────
+// ── 9. Log ────────────────────────────────────────────────────────────────────
 /** @param {string} p */
 const short = (p) => p.replace(homedir(), '~');
 
 console.log(styleText(['yellow'], `[build-tokens] config file : ${short(configAbsPath)}`));
-console.log(styleText(['yellow'], `[build-tokens] source      : ${source.map(short)}`));
+
+if (sourceModes) {
+  console.log(styleText(['yellow'],
+    `[build-tokens] modes       : ${Object.keys(sourceModes).join(', ')} (base: ${sourceModesBase})`
+  ));
+} else {
+  console.log(styleText(['yellow'], `[build-tokens] source      : ${(/** @type {string[]} */ (source)).map(short)}`));
+}
 console.log(styleText(['yellow'], `[build-tokens] dest file   : ${short(path.join(buildPath, destFile))}`));
 
 if (jsonBuildPath) {
-  const jsonFiles = buildJsonFiles(concreteFilePaths, jsonDestFile, jsonFormat, jsonExpression);
-  if (jsonFiles.length === 1) {
+  if (sourceModes && modeResult) {
+    const totalJsonFiles = Object.values(modeResult.jsonFilesByMode)
+      .reduce((count, files) => count + files.length, 0);
     console.log(styleText(['yellow'],
-      `[build-tokens] json        : ${short(path.join(jsonBuildPath, jsonFiles[0].destination))}`
+      `[build-tokens] json        : ${totalJsonFiles} files in ${short(jsonBuildPath)} (${Object.keys(sourceModes).length} modes)`
     ));
   } else {
-    console.log(styleText(['yellow'],
-      `[build-tokens] json        : ${jsonFiles.length} files in ${short(jsonBuildPath)}`
-    ));
+    const jsonFiles = buildJsonFiles(concreteFilePaths, jsonDestFile, jsonFormat, jsonExpression);
+    if (jsonFiles.length === 1) {
+      console.log(styleText(['yellow'],
+        `[build-tokens] json        : ${short(path.join(jsonBuildPath, jsonFiles[0].destination))}`
+      ));
+    } else {
+      console.log(styleText(['yellow'],
+        `[build-tokens] json        : ${jsonFiles.length} files in ${short(jsonBuildPath)}`
+      ));
+    }
   }
 } else {
   console.log(styleText(['yellow'],
@@ -149,5 +201,7 @@ if (jsonBuildPath) {
   ));
 }
 
-console.log(styleText(['green'], `[build-tokens] ${customPropsCount} custom properties processed`));
+console.log(styleText(['green'],
+  `[build-tokens] ${sourceModes && modeResult ? modeResult.totalCustomProps : customPropsCount} custom properties processed`
+));
 console.log(styleText(['green'], '**** DONE ****'));

package/{design-tokens/utilities → dev-tools/design-tokens-builder}/check-unresolved-custom-props.mjs

@@ -25,6 +25,7 @@ import StyleDictionary from 'style-dictionary';
 import './build-tokens-src/transforms.mjs';
 import { CSS_TRANSFORMS } from './build-tokens-src/platforms.mjs';
 import { resolveSourcePaths } from './build-tokens-src/resolve-source-paths.mjs';
+import { findMediaModeBlocks } from './build-tokens-src/merge-css.mjs';
 
 // const __filename = fileURLToPath(import.meta.url);
 // const __dirname  = dirname(__filename);
@@ -90,25 +91,48 @@ async function run() {
     const definitionRegex = /--([a-z0-9-]+)(?=\s*:)/g;
 
     // defined_props keeps file/line info too, so unused properties (section 6)
-    // can be reported with a link back to their definition.
-    /** @type {{file: string, line: number, prop: string}[]} */
+    // can be reported with a link back to their definition. With sourceModes
+    // (see build-tokens-src/config.mjs), the same prop name can legitimately
+    // appear once per mode with a different value — `mode` disambiguates
+    // which one a given entry is, so section 5 resolves each to the correct
+    // per-mode source file instead of mixing them up (see findMediaModeBlocks
+    // in build-tokens-src/merge-css.mjs).
+    /** @type {{file: string, line: number, prop: string, mode: string|null}[]} */
     const defined_props = [];
 
     const cssContent = fs.readFileSync(custom_prop_file_path, 'utf-8');
     const custom_prop_relpath = path.relative(configDir, custom_prop_file_path);
+
+    // sourceModesBase mirrors the default-resolution logic in
+    // build-tokens-src/config.mjs: the configured sourceModesBase if it's
+    // actually a key of sourceModes, otherwise the first key.
+    const sourceModeNames = config.sourceModes ? Object.keys(config.sourceModes) : [];
+    const sourceModesBase = sourceModeNames.includes(config.sourceModesBase)
+      ? config.sourceModesBase
+      : sourceModeNames[0];
+    const mediaModeBlocks = config.sourceModes ? findMediaModeBlocks(cssContent) : [];
+
+    /** @param {number} index @returns {string|null} */
+    const modeAtIndex = (index) => {
+      if (!config.sourceModes) return null;
+      const block = mediaModeBlocks.find(b => index > b.start && index < b.end);
+      return block ? block.mode : sourceModesBase;
+    };
+
     [...cssContent.matchAll(definitionRegex)].forEach(m => {
       const line = cssContent.substring(0, m.index).split('\n').length;
-      defined_props.push({ file: custom_prop_relpath, line, prop: `--${m[1]}` });
+      defined_props.push({ file: custom_prop_relpath, line, prop: `--${m[1]}`, mode: modeAtIndex(m.index) });
     });
 
-    // Also include any extra CSS files declared in extraCustomPropsFiles
+    // Also include any extra CSS files declared in extraCustomPropsFiles.
+    // These are plain (non-sourceModes) files, so mode is always null.
     for (const extraFile of (config.extraCustomPropsFiles ?? [])) {
       const extraFilePath = path.resolve(configDir, extraFile);
       const extraContent  = fs.readFileSync(extraFilePath, 'utf-8');
       const extraRelpath  = path.relative(configDir, extraFilePath);
       [...extraContent.matchAll(definitionRegex)].forEach(m => {
         const line = extraContent.substring(0, m.index).split('\n').length;
-        defined_props.push({ file: extraRelpath, line, prop: `--${m[1]}` });
+        defined_props.push({ file: extraRelpath, line, prop: `--${m[1]}`, mode: null });
       });
     }
 
@@ -161,28 +185,57 @@ async function run() {
     // CSS (or an extraCustomPropsFiles entry) — e.g. manual additions kept
     // across rebuilds via the mergeCustomProps option — have no token source
     // and are reported by name only.
+    //
+    // With sourceModes, resolution runs once PER MODE, keyed by mode name in
+    // sourceFileByPropByMode: the same prop name can be defined by a
+    // different source file in each mode (see the `dead: {...}` example in
+    // both a light and dark token file), so a single flattened name -> file
+    // map would silently point some entries at the wrong mode's file.
+    // sourceFileByProp (mode: null) covers the non-sourceModes case and
+    // extraCustomPropsFiles entries.
     // ---------------------------------------------------------------------------
     /** @type {Map<string, string>} */
     const sourceFileByProp = new Map();
-
-    if (checkUnused && Array.isArray(config.source) && config.source.length) {
+    /** @type {Map<string, Map<string, string>>} */
+    const sourceFileByPropByMode = new Map();
+
+    /** @param {string[]} sourcePatterns @returns {Promise<Map<string,string>>} */
+    const resolveSourceFileMap = async (sourcePatterns) => {
+      /** @type {Map<string, string>} */
+      const map = new Map();
+      const resolvedPaths = resolveSourcePaths(sourcePatterns, configDir);
+      if (!resolvedPaths.length) return map;
       try {
-        const tokenSourcePaths = resolveSourcePaths(config.source, configDir);
         const sd = new StyleDictionary({
-          source: tokenSourcePaths,
+          source: resolvedPaths,
           log: { verbosity: 'silent' },
           platforms: { css: { transforms: CSS_TRANSFORMS } },
         });
         const dictionary = await sd.getPlatformTokens('css');
-
         for (const token of dictionary.allTokens) {
-          if (token.filePath) sourceFileByProp.set(`--${token.name}`, token.filePath);
+          if (token.filePath) map.set(`--${token.name}`, token.filePath);
         }
       } catch {
         // Non-fatal: unused properties will be reported by name only.
       }
+      return map;
+    };
+
+    if (checkUnused && config.sourceModes) {
+      for (const [mode, modeSource] of Object.entries(config.sourceModes)) {
+        sourceFileByPropByMode.set(mode, await resolveSourceFileMap(modeSource));
+      }
+    } else if (checkUnused && Array.isArray(config.source) && config.source.length) {
+      const map = await resolveSourceFileMap(config.source);
+      for (const [prop, filePath] of map) sourceFileByProp.set(prop, filePath);
     }
 
+    /** @param {{prop: string, mode: string|null}} item @returns {string|undefined} */
+    const resolveSourceFilePath = (item) =>
+      item.mode
+        ? sourceFileByPropByMode.get(item.mode)?.get(item.prop)
+        : sourceFileByProp.get(item.prop);
+
     // ---------------------------------------------------------------------------
     // 6. Build the list of unused custom properties (defined but never
     // referenced via var() in any scanned CSS file) — the opposite check
@@ -194,7 +247,7 @@ async function run() {
         .filter(item => !used_props_set.has(item.prop))
         .filter(item => {
           if (!ignoreUnusedInNodeModules) return true;
-          const sourceFilePath = sourceFileByProp.get(item.prop);
+          const sourceFilePath = resolveSourceFilePath(item);
           if (!sourceFilePath) return true;
           return !/(^|[\\/])node_modules([\\/]|$)/.test(sourceFilePath);
         })
@@ -232,7 +285,7 @@ async function run() {
         '## Unused custom properties\n\n'
         + unused_props
           .map(item => {
-            const sourceFilePath = sourceFileByProp.get(item.prop);
+            const sourceFilePath = resolveSourceFilePath(item);
             if (!sourceFilePath) return `* \`${item.prop}\``;
 
             const relSource = path.relative(configDir, sourceFilePath);

package/{design-tokens → dev-tools/design-tokens-builder}/tokens-config-sample.mjs

@@ -46,9 +46,47 @@ const config = {
 
     // your project tokens
     './project-tokens/*.{js,mjs,jsonc,json}',
-
   ],
 
+  // Optional light/dark (or other) custom properties split — alternative to
+  // `source`. If this key is set (a non-null object), `source` above is
+  // ignored: each key is a mode name with its own array of source patterns
+  // (same rules as `source`: paths, globs, or a mix).
+  //
+  // The generated CSS composes all modes into a single destFile:
+  //   - the base mode's props (see sourceModesBase below) go in a top-level
+  //     `:root { ... }` block, with `color-scheme: <all modes>;` prepended
+  //     (e.g. "light dark")
+  //   - 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 (see JSON TOKENS OUTPUT below) is produced once per
+  // mode, with the mode name appended to each filename, e.g. with
+  // jsonDestFile: 'tokens' -> "tokens-light.jsonc", "tokens-dark.jsonc".
+  //
+  // sample:
+  // sourceModes: {
+  //   light: [
+  //     `${minimo_path}/design-tokens/_src/**/*.tokens.{mjs,jsonc}`,
+  //     `${minimo_path}/src/**/*.tokens.{mjs,jsonc}`,
+  //     './project-tokens/light/*.{js,mjs,jsonc,json}',
+  //   ],
+  //   dark: [
+  //     './project-tokens/dark/*.{js,mjs,jsonc,json}',
+  //   ],
+  // },
+  sourceModes: null,
+
+  // With sourceModes set: the mode whose declarations go in the top-level
+  // `:root { ... }` block, instead of nested inside its own
+  // `@media (prefers-color-scheme: <mode>) { ... }` rule (default: the first
+  // key of sourceModes, e.g. 'light'). Ignored when sourceModes is not set.
+  sourceModesBase: 'light',
+
+
   // If true (default), dimension token values expressed in px are converted
   // to rem in the generated CSS. Values in other units (em, %, vh, dvw, ...)
   // are never touched regardless of this option.

package/dev-tools/starter-kit/source_files/root/package-tpl.json

@@ -17,9 +17,9 @@
     "*.avif"
   ],
   "scripts": {
-    "progetto JS webpack DEV": "npm run 'launchChrome' && NODE_ENV=development webpack serve --config ./webpack.config.mjs #--open-app-name 'Google Chrome'",
+    "progetto JS webpack DEV": "NODE_ENV=development webpack serve --config ./webpack.config.mjs #--open-app-name 'Google Chrome'",
     "php server": "php -S localhost:[[port8000]] # -t root_dir/",
-    "progetto sf webpack DEV": "npm run 'launchChrome' && rm -rf ./public/_dev && NODE_ENV=development webpack serve --config ./webpack.config.mjs # http://192.168.1.135:[[port5700]",
+    "progetto sf webpack DEV": "rm -rf ./public/_dev && NODE_ENV=development webpack serve --config ./webpack.config.mjs # http://192.168.1.135:[[port5700]",
     "symfony server": "symfony serve --port=[[port8000]] --listen-ip=0.0.0.0 # http://192.168.1.135:[[port8000]] # -d (deamon): rimane aperto anche dopo la chiusura del terminale, terminare con `symfony server:stop`",
     "webpack PROD": "npm run 'UPD-version' && NODE_ENV=production webpack --config ./webpack.config.mjs --stats minimal",
     "eslint-check": "npx eslint app/",