@massimo-cassandro/minimo 1.41.4 → 1.41.5

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

@@ -1,33 +1,35 @@
-// 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 `<selector> { ... }` CSS blocks
-// (selector: customPropsSelector, default ':root' — see config.mjs) are then
-// composed into a single destFile:
-//   - the base mode's block stays as a plain `<selector> { ... }` 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>) { <selector> { ... } }`, 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.
-//
-// When sourceModes defines both a `light` and a `dark` key and
-// useLightDarkFunc is true (default), custom properties shared by both are
-// reconciled into a single `light-dark()` declaration instead of being split
-// across the base block and a `@media (prefers-color-scheme: dark)` rule —
-// see light-dark.mjs.
-//
-// 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).
+/*
+  build-tokens-src/build-source-modes.mjs
+  Percorso di build alternativo usato quando la config del progetto imposta `sourceModes`
+  (vedi config.mjs) al posto di un singolo array `source` — tipicamente per una
+  suddivisione light/dark delle custom properties.
+
+  Per ogni modalità viene costruita un'istanza separata di StyleDictionary a partire
+  dall'array `source` di quella modalità. I blocchi CSS generati `<selector> { ... }`
+  (selector: customPropsSelector, default ':root' — vedi config.mjs) vengono poi
+  composti in un unico destFile:
+    - il blocco della modalità base resta una semplice regola `<selector> { ... }`, con
+      una dichiarazione `color-scheme: <tutte le modalità unite>;` anteposta (ad es.
+      "light dark")
+    - il blocco di ogni altra modalità viene racchiuso in
+      `@media (prefers-color-scheme: <modalità>) { <selector> { ... } }`, con una
+      dichiarazione `color-scheme: <modalità>;` anteposta
+  customPropsGroups, mergeCustomProps e pxToRem si applicano per modalità, esattamente come
+  nella build a sorgente singola. addLayer (se impostato) racchiude l'intero risultato
+  composto in un unico `@layer`, anziché uno per modalità.
+
+  Quando sourceModes definisce sia una chiave `light` sia una `dark` e
+  useLightDarkFunc è true (default), le custom properties condivise da entrambe vengono
+  riconciliate in un'unica dichiarazione `light-dark()` invece di essere divise
+  tra il blocco base e una regola `@media (prefers-color-scheme: dark)` —
+  vedi light-dark.mjs.
+
+  I token JSON (se jsonBuildPath è impostato) vengono prodotti per modalità: un set di
+  file per modalità, con `-<modalità>` aggiunto a ogni nome di file (vedi
+  buildJsonFiles() in formats/json.mjs), ad es. "tokens-light.jsonc" /
+  "tokens-dark.jsonc", oppure "size-light.jsonc" / "size-dark.jsonc" in
+  modalità multi-file (jsonDestFile: null).
+*/
 
 import StyleDictionary from 'style-dictionary';
 import * as path from 'node:path';
@@ -40,22 +42,22 @@ import { applyLightDarkFunc } from './light-dark.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 `<selector> { ... }` 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 {Record<string,string[]>} opts.sourceModes    Percorsi sorgente risolti per modalità (vedi config.mjs)
+ * @param {string}                 opts.baseMode        Modalità il cui blocco resta una regola `<selector> { ... }` di primo livello
+ * @param {string}                 opts.buildPath        Percorso assoluto della directory di output CSS
+ * @param {string}                 opts.destFile         Nome del file CSS di output
+ * @param {string|null}            opts.jsonBuildPath    Percorso assoluto dell'output JSON (null = disattivato)
+ * @param {string|null}            opts.jsonDestFile     Nome base del file JSON aggregato; null = un file per sorgente
+ * @param {'json'|'jsonc'}         opts.jsonFormat        Formato di output dei file JSON
+ * @param {'keep'|'calc'|'resolve'} opts.jsonExpression   Come gestire le espressioni matematiche nei token dimension
  * @param {{name:string,prefixes:string[]}[]} opts.customPropsGroups
  * @param {boolean}                opts.pxToRem
  * @param {string|null}            opts.addLayer
- * @param {boolean|(string|RegExp)[]} opts.mergeCustomProps  true = merge all sources, array = only the matching token source files
- * @param {boolean}                opts.useLightDarkFunc  reconcile shared `light`/`dark` properties into `light-dark()` calls (default: true — see config.mjs and light-dark.mjs). Ignored unless sourceModes defines both a `light` and a `dark` key.
- * @param {string}                 opts.customPropsSelector  CSS selector wrapping the generated block(s) (default: ':root' — see config.mjs)
- * @param {string[]}               opts.parserNames  Style Dictionary parser names to opt every instance into (legacy bridge, plus the token-rename parser when at least one source has a `transform` — see build-tokens.mjs)
- * @param {string[]}               opts.preprocessorNames  Style Dictionary preprocessor names to opt every instance into (the token-rename reference rewriter, when at least one source has a `transform` — see build-tokens.mjs)
+ * @param {boolean|(string|RegExp)[]} opts.mergeCustomProps  true = unisce tutte le sorgenti, array = solo i file token sorgente corrispondenti
+ * @param {boolean}                opts.useLightDarkFunc  riconcilia le proprietà `light`/`dark` condivise in chiamate `light-dark()` (default: true — vedi config.mjs e light-dark.mjs). Ignorato a meno che sourceModes definisca sia una chiave `light` sia una `dark`.
+ * @param {string}                 opts.customPropsSelector  selettore CSS che racchiude i blocchi generati (default: ':root' — vedi config.mjs)
+ * @param {string[]}               opts.parserNames  nomi dei parser di Style Dictionary a cui far aderire ogni istanza (bridge legacy, più il parser di rinomina dei token quando almeno una sorgente ha un `transform` — vedi build-tokens.mjs)
+ * @param {string[]}               opts.preprocessorNames  nomi dei preprocessor di Style Dictionary a cui far aderire ogni istanza (il riscrittore dei riferimenti di rinomina dei token, quando almeno una sorgente ha un `transform` — vedi build-tokens.mjs)
  * @returns {Promise<{cssDestPath: string, totalCustomProps: number, jsonFilesByMode: Record<string, object[]>}>}
  */
 export const buildSourceModes = async ({
@@ -78,8 +80,8 @@ export const buildSourceModes = async ({
 }) => {
   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.
+  // Legge il destFile preesistente (se c'è) PRIMA che venga eseguita qualsiasi istanza
+  // di Style Dictionary, dato che la prima a scrivere lo sovrascriverebbe.
   if (mergeCustomProps) {
     loadExistingCustomPropsScoped(path.join(buildPath, destFile), baseMode, mergeCustomProps, customPropsSelector);
   }
@@ -90,12 +92,14 @@ export const buildSourceModes = async ({
 
   /** @type {Record<string,string>} */
   const modeBlocks = {};
-  // Per-mode custom-prop count and structured (name -> tail) props map,
-  // captured right after each per-mode format call (customPropsCount and
-  // lastFinalProps are live bindings, updated synchronously by the format
-  // function — see formats/css.mjs). Kept per mode (rather than summed on
-  // the fly) so applyLightDarkFunc() can later overwrite just the entries it
-  // actually touches (light, dark, and the base mode).
+  /*
+    Conteggio delle custom props per modalità e mappa strutturata delle props (nome -> coda),
+    catturati subito dopo ogni chiamata al format per modalità (customPropsCount e
+    lastFinalProps sono live binding, aggiornati in modo sincrono dalla funzione
+    format — vedi formats/css.mjs). Conservati per modalità (invece di sommarli
+    al volo) così che applyLightDarkFunc() possa poi sovrascrivere solo le voci che
+    tocca davvero (light, dark e la modalità base).
+  */
   /** @type {Record<string,number>} */
   const modeCounts = {};
   /** @type {Record<string, Record<string,string>>} */
@@ -104,12 +108,14 @@ export const buildSourceModes = async ({
   const jsonFilesByMode = {};
 
   for (const mode of modeNames) {
-    // Non-base modes may reference base-mode tokens (always defined, since
-    // the base block is the unconditional top-level `<selector>`). The base
-    // sources are passed as `include`: available for reference resolution
-    // but flagged isSource: false, and skipped by the css/json formats.
-    // Base-mode-only on purpose: a reference to a token that exists only in
-    // another `@media` block would build fine but be undefined at runtime.
+    /*
+      Le modalità non base possono referenziare i token della modalità base (sempre definiti, dato che
+      il blocco base è il `<selector>` di primo livello incondizionato). Le sorgenti
+      base vengono passate come `include`: disponibili per la risoluzione dei riferimenti
+      ma contrassegnate isSource: false, e saltate dai format css/json.
+      Solo la modalità base, volutamente: un riferimento a un token che esiste solo in
+      un altro blocco `@media` verrebbe compilato senza errori ma risulterebbe non definito a runtime.
+    */
     const include = mode === baseMode ? [] : sourceModes[baseMode];
 
     const sd = new StyleDictionary({
@@ -138,12 +144,12 @@ export const buildSourceModes = async ({
       },
     });
 
-    // formatPlatform() runs the format function without writing to disk —
-    // the composed multi-mode file is written once, at the end, below.
+    // formatPlatform() esegue la funzione format senza scrivere su disco —
+    // il file composto multi-modalità viene scritto una sola volta, alla fine, qui sotto.
     const [formatted] = await sd.formatPlatform('css');
     modeBlocks[mode] = /** @type {string} */ (formatted.output);
-    // customPropsCount / lastFinalProps are live bindings, updated
-    // synchronously by the format function called above (see formats/css.mjs).
+    // customPropsCount / lastFinalProps sono live binding, aggiornati in modo
+    // sincrono dalla funzione format chiamata qui sopra (vedi formats/css.mjs).
     modeCounts[mode] = customPropsCount;
     modeFinalProps[mode] = lastFinalProps;
 
@@ -170,10 +176,12 @@ export const buildSourceModes = async ({
     }
   }
 
-  // ── light-dark() reconciliation (light/dark modes only) ──────────────────
-  // Rebuilds just the `light`, `dark` and base-mode blocks from the adjusted
-  // props maps — see light-dark.mjs. No-op (returns null) unless sourceModes
-  // defines both a `light` and a `dark` key.
+  // ── Riconciliazione light-dark() (solo modalità light/dark) ──────────────────
+  /*
+    Ricostruisce solo i blocchi `light`, `dark` e della modalità base a partire dalle mappe
+    di props modificate — vedi light-dark.mjs. Non fa nulla (restituisce null) a meno che sourceModes
+    definisca sia una chiave `light` sia una `dark`.
+  */
   if (useLightDarkFunc) {
     const reconciled = applyLightDarkFunc({
       modeFinalProps,
@@ -190,11 +198,13 @@ export const buildSourceModes = async ({
 
   const totalCustomProps = Object.values(modeCounts).reduce((sum, n) => sum + n, 0);
 
-  // ── Compose the final CSS ────────────────────────────────────────────────
-  // A mode left with zero custom properties — typically a `light`/`dark`
-  // mode fully absorbed by applyLightDarkFunc() into the base mode's
-  // light-dark() declarations — gets no `@media` block at all, rather than
-  // an empty (but harmless) one.
+  // ── Composizione del CSS finale ────────────────────────────────────────────────
+  /*
+    Una modalità rimasta senza alcuna custom property — tipicamente una modalità `light`/`dark`
+    completamente assorbita da applyLightDarkFunc() nelle dichiarazioni light-dark()
+    della modalità base — non ottiene alcun blocco `@media`, invece di
+    un blocco vuoto (ma innocuo).
+  */
   const otherModes = modeNames.filter((mode) => mode !== baseMode && modeCounts[mode] > 0);
 
   let composed = modeBlocks[baseMode];
@@ -202,9 +212,11 @@ export const buildSourceModes = async ({
     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.
+  /*
+    addLayer racchiude l'intero risultato composto una sola volta, anziché una volta per
+    modalità. L'indentazione è lasciata al passaggio di fix di stylelint (eseguito subito dopo la
+    build), come nella build a sorgente singola.
+  */
   const finalCss = addLayer
     ? `@layer ${addLayer} {\n\n${composed}}\n`
     : composed;

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

@@ -1,10 +1,12 @@
 /// <reference types="node" />
-// build-tokens-src/config.mjs
-// Reads the --config flag from argv, imports the project config file,
-// resolves all paths and exports them for build-tokens.mjs.
-//
-// Keeping this logic separate from the entry point makes it easier to test
-// and reuse in other scripts.
+/*
+  build-tokens-src/config.mjs
+  Legge il flag --config da argv, importa il file di configurazione del progetto,
+  risolve tutti i percorsi e li esporta per build-tokens.mjs.
+
+  Tenere questa logica separata dal punto di ingresso ne facilita il test
+  e il riutilizzo in altri script.
+*/
 
 /* globals process */
 
@@ -13,7 +15,7 @@ import { pathToFileURL } from 'node:url';
 import { splitSourceEntries } from './source-prefixes.mjs';
 
 // ---------------------------------------------------------------------------
-// Read the --config flag
+// Legge il flag --config
 // ---------------------------------------------------------------------------
 const args = process.argv.slice(2);
 const configFlagIndex = args.indexOf('--config');
@@ -31,64 +33,74 @@ export const configAbsPath = path.resolve(process.cwd(), configArgPath);
 export const configDir     = path.dirname(configAbsPath);
 
 // ---------------------------------------------------------------------------
-// Import the project config
+// Importa la config del progetto
 // ---------------------------------------------------------------------------
 const buildConfig = (await import(pathToFileURL(configAbsPath).href)).default;
 
-// Helper: resolves a path relative to the config directory.
-// Leaves already-absolute paths untouched.
+// Helper: risolve un percorso relativo alla directory della config.
+// Lascia invariati i percorsi già assoluti.
 /** @param {string} p */
 const resolveFromConfig = (p) => path.resolve(configDir, p);
 
 // ---------------------------------------------------------------------------
-// Path resolution
+// Risoluzione dei percorsi
 // ---------------------------------------------------------------------------
 
-// CSS output
+// Output CSS
 export const buildPath = resolveFromConfig(buildConfig.buildPath);
 export const destFile  = buildConfig.destFile;
 
 // Stylelint
 export const stylelintConfigPath = resolveFromConfig(buildConfig.stylelintConfigPath);
 
-// JSON — platform is active only if jsonBuildPath is set in the config
+// JSON — la platform è attiva solo se jsonBuildPath è impostato nella config
 const jsonBuildPathRaw = buildConfig.jsonBuildPath ?? null;
 export const jsonBuildPath = jsonBuildPathRaw ? resolveFromConfig(jsonBuildPathRaw) : null;
 
-// jsonDestFile: base name (no extension) for the aggregated output file.
-// null  → one file per source (mirrors the source structure)
-// string → single aggregated file (e.g. 'tokens' → 'tokens.jsonc')
-// The extension is added automatically based on jsonFormat.
+/*
+  jsonDestFile: nome base (senza estensione) del file aggregato di output.
+  null  → un file per sorgente (replica la struttura dei sorgenti)
+  string → singolo file aggregato (ad es. 'tokens' → 'tokens.jsonc')
+  L'estensione viene aggiunta automaticamente in base a jsonFormat.
+*/
 export const jsonDestFile = buildConfig.jsonDestFile ?? null;
 
-// jsonFormat: controls output format for the generated JSON token files.
-// 'jsonc' → .jsonc extension + generated-file disclaimer header
-// 'json'  → plain .json, no disclaimer
-// Any value other than 'jsonc' is normalised to 'json'.
+/*
+  jsonFormat: controlla il formato di output dei file JSON dei token generati.
+  'jsonc' → estensione .jsonc + intestazione che segnala il file generato
+  'json'  → .json semplice, senza intestazione
+  Qualsiasi valore diverso da 'jsonc' viene normalizzato a 'json'.
+*/
 export const jsonFormat = buildConfig.jsonFormat === 'jsonc' ? 'jsonc' : 'json';
 
-// jsonExpression: controls how math expressions in dimension token values are handled.
-//   'keep'    (default) — write the expression as-is
-//   'calc'    — wrap in CSS calc()
-//   'resolve' — evaluate numerically; unit inherited from the first referenced token
+/*
+  jsonExpression: controlla come vengono gestite le espressioni matematiche nei valori dei token dimension.
+    'keep'    (default) — scrive l'espressione così com'è
+    'calc'    — la racchiude in calc() CSS
+    'resolve' — la valuta numericamente; unità ereditata dal primo token referenziato
+*/
 const VALID_EXPR_MODES = ['keep', 'calc', 'resolve'];
 export const jsonExpression = VALID_EXPR_MODES.includes(buildConfig.jsonExpression)
   ? buildConfig.jsonExpression
   : 'resolve';
 
-// pxToRem: if true (default), dimension token values expressed in px are
-// converted to rem in the generated CSS (see the size/pxToRem-smart
-// transform in build-tokens-src/transforms.mjs). Values in other units
-// (em, %, vh, dvw, ...) are never touched regardless of this option.
+/*
+  pxToRem: se true (default), i valori dei token dimension espressi in px vengono
+  convertiti in rem nel CSS generato (vedi la transform size/pxToRem-smart
+  in build-tokens-src/transforms.mjs). I valori in altre unità
+  (em, %, vh, dvw, ...) non vengono mai toccati, indipendentemente da questa opzione.
+*/
 export const pxToRem = buildConfig.pxToRem !== false;
 
-// mergeCustomProps: if true, custom properties already present in the CSS
-// destination file take priority over the ones generated by this build (see
-// build-tokens-src/merge-css.mjs). It can also be an array of strings/RegExps:
-// only the properties generated by the token source files matching one of its
-// entries are merged. An empty or invalid array means false. Explicit false
-// disables the merge entirely (the destination file is fully regenerated).
-// Default: true (i.e. when the key is left unset).
+/*
+  mergeCustomProps: se true, le custom properties già presenti nel file CSS di
+  destinazione hanno priorità su quelle generate da questa build (vedi
+  build-tokens-src/merge-css.mjs). Può essere anche un array di stringhe/RegExp:
+  vengono unite solo le proprietà generate dai file token sorgente che corrispondono a una
+  delle sue voci. Un array vuoto o non valido equivale a false. false esplicito
+  disattiva del tutto il merge (il file di destinazione viene rigenerato completamente).
+  Default: true (cioè quando la chiave non è impostata).
+*/
 /** @type {boolean|(string|RegExp)[]} */
 export const mergeCustomProps = (() => {
   const value = buildConfig.mergeCustomProps;
@@ -101,63 +113,73 @@ export const mergeCustomProps = (() => {
   return false;
 })();
 
-// addLayer: wraps the generated custom properties inside a CSS `@layer`
-// at-rule (see formats/css.mjs), e.g. `@layer project { :root { ... } }`.
-// Set to null, undefined or false (default) to emit no layer.
+/*
+  addLayer: racchiude le custom properties generate in una at-rule CSS `@layer`
+  (vedi formats/css.mjs), ad es. `@layer project { :root { ... } }`.
+  Impostare a null, undefined o false (default) per non emettere alcun layer.
+*/
 export const addLayer = buildConfig.addLayer ? String(buildConfig.addLayer).trim() : null;
 
-// customPropsSelector: CSS selector wrapping the generated custom properties
-// block(s) (see formats/css.mjs buildCssBlock()), instead of the default
-// `:root`. Applies uniformly to a single-source build and to a sourceModes
-// build (the base mode's top-level block and every other mode's block
-// nested under its own `@media (prefers-color-scheme: <mode>)` rule all use
-// the same selector). Falsy or blank values fall back to ':root'.
+/*
+  customPropsSelector: selettore CSS che racchiude i blocchi di custom properties
+  generati (vedi formats/css.mjs buildCssBlock()), al posto del default
+  `:root`. Si applica in modo uniforme a una build a sorgente singola e a una build
+  con sourceModes (il blocco di primo livello della modalità base e il blocco di ogni altra modalità,
+  annidato nella propria regola `@media (prefers-color-scheme: <modalità>)`, usano
+  lo stesso selettore). Valori falsy o vuoti ripiegano su ':root'.
+*/
 export const customPropsSelector = typeof buildConfig.customPropsSelector === 'string'
   && buildConfig.customPropsSelector.trim()
   ? buildConfig.customPropsSelector.trim()
   : ':root';
 
-// useLightDarkFunc: with sourceModes set (see below) and defining both a
-// `light` and a `dark` key, custom properties present in both are written
-// once as `--name: light-dark(<light>, <dark>);` instead of being split
-// across the base mode's block and a
-// `@media (prefers-color-scheme: dark) { ... }` rule (see light-dark.mjs).
-// Ignored when sourceModes is not set, or does not define both a light and a
-// dark mode. Default: true.
+/*
+  useLightDarkFunc: con sourceModes impostato (vedi sotto) e che definisce sia una
+  chiave `light` sia una `dark`, le custom properties presenti in entrambe vengono scritte
+  una sola volta come `--name: light-dark(<light>, <dark>);` invece di essere divise
+  tra il blocco della modalità base e una regola
+  `@media (prefers-color-scheme: dark) { ... }` (vedi light-dark.mjs).
+  Ignorata quando sourceModes non è impostato o non definisce sia una modalità light sia una
+  dark. Default: true.
+*/
 export const useLightDarkFunc = buildConfig.useLightDarkFunc !== false;
 
-// customPropsGroups: custom properties whose first hyphen-separated name
-// segment matches one of a group's prefixes are pulled out, labelled with
-// that group's name and moved to the beginning of the generated CSS file, in
-// group-list order (see formats/css.mjs). Each entry: { name, prefixes }.
-// Default: [].
+/*
+  customPropsGroups: le custom properties il cui primo segmento del nome (separato
+  da trattini) corrisponde a uno dei prefissi di un gruppo vengono estratte, etichettate con
+  il nome del gruppo e spostate all'inizio del file CSS generato, nell'ordine
+  dell'elenco dei gruppi (vedi formats/css.mjs). Ogni voce: { name, prefixes }.
+  Default: [].
+*/
 export const customPropsGroups = Array.isArray(buildConfig.customPropsGroups)
   ? buildConfig.customPropsGroups
   : [];
 
-// ---------------------------------------------------------------------------
-// Source: resolve patterns relative to the config directory and normalise to
-// forward-slash absolute paths (fast-glob, used internally by Style Dictionary,
-// requires forward slashes even on Windows). See resolve-source-paths.mjs.
-//
-// WARNING: in the project config file, avoid building glob patterns with
-// 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.
-//
-// Entries of `source` / of each mode can also be `{ src, prefix, transform }`
-// objects, to render the custom properties of those files with a prefix
-// (see source-prefixes.mjs) and/or to rename token nodes within those files
-// (see source-transforms.mjs). They are flattened here into plain patterns
-// for Style Dictionary; the prefixed/transformed ones are also collected in
-// `prefixedSources`/`transformedSources`, to be registered by
-// build-tokens.mjs.
-// ---------------------------------------------------------------------------
+/*
+  ---------------------------------------------------------------------------
+  Source: risolve i pattern relativi alla directory della config e li normalizza in
+  percorsi assoluti con forward slash (fast-glob, usato internamente da Style Dictionary,
+  richiede i forward slash anche su Windows). Vedi resolve-source-paths.mjs.
+
+  ATTENZIONE: nel file di configurazione del progetto, evitare di costruire i pattern glob con
+  path.join() — può corrompere la sintassi del pattern. Usare i template literal:
+    OK:  `${minimo_path}/**\/*.{json,mjs}`
+    NO:  path.join(minimo_path, '/**\/*.{json,mjs}')
+
+  sourceModes: alternativa a `source`, per una suddivisione light/dark (o altra) delle
+  custom properties — vedi build-tokens-src/build-source-modes.mjs. Quando è impostato
+  (buildConfig.sourceModes è un oggetto non null), `source` viene ignorato e
+  l'array di pattern sorgente di ogni modalità viene risolto allo stesso modo.
+
+  Le voci di `source` / di ogni modalità possono essere anche oggetti `{ src, prefix, transform }`,
+  per rendere le custom properties di quei file con un prefisso
+  (vedi source-prefixes.mjs) e/o per rinominare i nodi dei token al loro interno
+  (vedi source-transforms.mjs). Qui vengono appiattite in semplici pattern
+  per Style Dictionary; quelle con prefisso/transform vengono raccolte anche in
+  `prefixedSources`/`transformedSources`, da registrare in
+  build-tokens.mjs.
+  ---------------------------------------------------------------------------
+*/
 const sourceModesRaw = buildConfig.sourceModes ?? null;
 
 /** @type {import('./source-prefixes.mjs').PrefixedSource[]} */
@@ -186,11 +208,13 @@ export const sourceModes = sourceModesRaw
   )
   : 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.
+/*
+  sourceModesBase: la modalità le cui dichiarazioni vengono scritte nel blocco
+  `:root { ... }` di primo livello (le altre sono annidate in
+  `@media (prefers-color-scheme: <modalità>) { ... }`). Default: la prima chiave
+  di sourceModes (ordine di inserimento), ad es. 'light'. Ignorata quando sourceModes
+  non è impostato.
+*/
 export const sourceModesBase = sourceModes
   ? (Object.prototype.hasOwnProperty.call(sourceModes, buildConfig.sourceModesBase)
     ? buildConfig.sourceModesBase