@massimo-cassandro/minimo 1.41.4 → 1.41.5

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

@@ -1,118 +1,123 @@
-// tokens-config-sample.mjs
-// Sample project config for build-tokens.mjs and check-unresolved-custom-props.mjs.
-// Copy and adapt this file for each project; pass it via the --config flag.
-//
-// All paths are relative to this config file (not to the CWD).
+/*
+  tokens-config-sample.mjs
+  Configurazione di esempio per build-tokens.mjs e check-unresolved-custom-props.mjs.
+  Copiare e adattare questo file per ogni progetto; passarlo con il flag --config.
+
+  Tutti i percorsi sono relativi a questo file di configurazione (non alla CWD).
+*/
 
 // import { homedir } from 'os';
 // import path from 'path';
 
-// Path to the design token source files.
-// You can use an absolute path, a relative path, or build it programmatically.
+// Percorso dei file sorgente dei design token.
+// Si può usare un percorso assoluto, un percorso relativo, oppure costruirlo programmaticamente.
 
 
 
-// minimo package path in node_modules
+// percorso del pacchetto minimo in node_modules
 const node_modules_path = '../../node_modules',
   minimo_path = `${node_modules_path}/@massimo-cassandro/minimo`;
 
 const config = {
 
   // ---------------------------------------------------------------------------
-  // BUILD-TOKENS & STYLE-DICTIONARY SETTINGS
+  // IMPOSTAZIONI DI BUILD-TOKENS E STYLE-DICTIONARY
   // ---------------------------------------------------------------------------
 
-  // Path to the stylelint config used to lint the generated CSS file
+  // Percorso della config stylelint usata per il lint del file CSS generato
   stylelintConfigPath: '../../stylelint.config.mjs',
 
-  // Output directory for the CSS file generated by Style Dictionary
+  // Directory di output del file CSS generato da Style Dictionary
   buildPath: './',
 
-  // Output filename for the generated CSS file
+  // Nome del file CSS generato
   destFile: 'custom-properties.css',
 
-  // Source token files — accept paths, globs, or a mix of both.
-  // Supported formats: .json, .jsonc, .mjs (must export a DTCG-compliant default object)
-  //
-  // Legacy (non-DTCG) .json files — e.g. exported from Open Props — are
-  // auto-detected and converted to DTCG v5 syntax at parse time, so they can
-  // be freely mixed with regular DTCG sources (see README.md). Not covered:
-  // .jsonc, reserved for hand-authored DTCG sources. These .json files are
-  // parsed with plain JSON.parse (no comments, no trailing commas).
-  //
-  // A legacy node that is at the same time a token (own value/type) AND a
-  // group with nested children (e.g. Open Props' other.ease.out, which has
-  // its own value plus out.1 ... out.5) cannot be represented in DTCG v5 —
-  // a node with $value is always a leaf. Its own value is moved to a child
-  // token named `default` (other.ease.out.default, i.e. --other-ease-out-default),
-  // or `base` if a `default` child already exists; if both exist the build
-  // fails. References to such a node from the same file are rewritten
-  // accordingly; from other files they must use the child name explicitly.
-  //
-  // WARNING: do not use path.join() to build glob patterns — it may corrupt
-  // the pattern syntax. Use template literals instead:
-  //   OK:  `${minimo_path}/**/*.{json,mjs}`
-  //   NO:  path.join(minimo_path, '/**/*.{json,mjs}')
-  //
-  // An entry can also be an object `{ src, prefix, transform }` (src: string
-  // or array of strings/globs).
-  //
-  // `prefix`: renders the custom properties of those files with a prefix,
-  // e.g. { src: '...open-props...json', prefix: 'op' } turns Open Props'
-  // gray.0 into --op-gray-0. Only the property name changes: {references} to
-  // those tokens are rendered as var(--op-gray-0), and the JSON output stays
-  // unprefixed. 'op', 'op-' and '--op-' are equivalent. Two different
-  // prefixes for the same file make the build fail.
-  //
-  // `transform`: moves/renames token nodes within those files' own tree —
-  // e.g. { primary: 'primary.100' } takes whatever is defined at dot-path
-  // `primary` and moves it to `primary.100`, BEFORE Style Dictionary resolves
-  // {references} or builds the CSS/JSON output (unlike `prefix`, which is a
-  // purely cosmetic CSS name change applied after the fact — see
-  // build-tokens-src/source-transforms.mjs). Typical use case: a preexisting
-  // project (e.g. driven by Figma/Penpot) names its own base color `primary`,
-  // while minimo's own tokens reference `{primary.100}` — instead of
-  // renaming the property by hand after every build, or hunting down every
-  // minimo reference to change it, `transform` fixes the token's own path
-  // once, here.
-  //   - Both sides of the map use Style Dictionary's own DOT-PATH notation
-  //     ('primary.100'), NOT the hyphen-joined custom-property notation
-  //     ('primary-100'): token name segments in this project can themselves
-  //     contain hyphens (e.g. btn-close), so a hyphen can't reliably tell a
-  //     path separator from a literal part of a segment name — a dot can,
-  //     since it's already reserved by Style Dictionary as the {reference}
-  //     path separator.
-  //   - {References} to the OLD path — in the same file or a completely
-  //     different one — are rewritten automatically, tree-wide, to the NEW
-  //     path once all sources are merged: e.g. every {primary} in the whole
-  //     build becomes {primary.100}, whether minimo's own tokens already
-  //     wrote {primary.100} directly (no-op) or something else in the
-  //     project still says {primary}.
-  //   - WARNING: this rewrite is by design file-independent (a bare
-  //     {reference} doesn't know which file it "belongs" to) — so if the
-  //     SAME source key (e.g. "primary") is given a DIFFERENT destination in
-  //     two different files' `transform` maps, each rename itself still
-  //     works fine, but {primary} becomes ambiguous: which destination should
-  //     it be rewritten to? In that case the automatic rewrite is skipped
-  //     for that key (a warning is logged), and every {primary} reference
-  //     must be fixed by hand to point at the right one of the two new
-  //     paths.
-  //   - A source key not found in the file only logs a warning, it does not
-  //     fail the build.
-  //   - Applies to both the CSS and the JSON output (see JSON TOKENS OUTPUT
-  //     below), since both are rebuilt from the token's path, by then already
-  //     renamed.
-  //
-  // Both options work the same way inside sourceModes.
+  /*
+    File token sorgente — accetta percorsi, glob o una combinazione dei due.
+    Formati supportati: .json, .jsonc, .mjs (deve esportare come default un oggetto conforme a DTCG)
+
+    I file .json legacy (non DTCG) — ad es. esportati da Open Props — vengono
+    rilevati automaticamente e convertiti alla sintassi DTCG v5 in fase di parsing, quindi
+    possono essere mescolati liberamente con le normali sorgenti DTCG (vedi README.md). Non coperti:
+    i .jsonc, riservati alle sorgenti DTCG scritte a mano. Questi file .json vengono
+    letti con un semplice JSON.parse (niente commenti, niente trailing comma).
+
+    Un nodo legacy che è al tempo stesso un token (value/type propri) E un
+    gruppo con figli annidati (ad es. other.ease.out di Open Props, che ha
+    un valore proprio più out.1 ... out.5) non può essere rappresentato in DTCG v5 —
+    un nodo con $value è sempre una foglia. Il suo valore viene spostato in un token
+    figlio chiamato `default` (other.ease.out.default, cioè --other-ease-out-default),
+    oppure `base` se esiste già un figlio `default`; se esistono entrambi la build
+    fallisce. I riferimenti a un nodo di questo tipo dallo stesso file vengono riscritti
+    di conseguenza; da altri file devono usare esplicitamente il nome del figlio.
+
+    ATTENZIONE: non usare path.join() per costruire i pattern glob — può corrompere
+    la sintassi del pattern. Usare i template literal:
+      OK:  `${minimo_path}/**\/*.{json,mjs}`
+      NO:  path.join(minimo_path, '/**\/*.{json,mjs}')
+
+    Una voce può essere anche un oggetto `{ src, prefix, transform }` (src: stringa
+    o array di stringhe/glob).
+
+    `prefix`: rende le custom properties di quei file con un prefisso,
+    ad es. { src: '...open-props...json', prefix: 'op' } trasforma gray.0 di
+    Open Props in --op-gray-0. Cambia solo il nome della proprietà: i {riferimenti} a
+    quei token vengono resi come var(--op-gray-0) e l'output JSON resta
+    senza prefisso. 'op', 'op-' e '--op-' sono equivalenti. Due prefissi diversi
+    per lo stesso file fanno fallire la build.
+
+    `transform`: sposta/rinomina i nodi dei token all'interno dell'albero di quei file —
+    ad es. { primary: 'primary.100' } prende ciò che è definito al dot-path
+    `primary` e lo sposta in `primary.100`, PRIMA che Style Dictionary risolva
+    i {riferimenti} o costruisca l'output CSS/JSON (a differenza di `prefix`, che è una
+    modifica puramente estetica del nome CSS applicata a posteriori — vedi
+    build-tokens-src/source-transforms.mjs). Caso d'uso tipico: un progetto
+    preesistente (ad es. guidato da Figma/Penpot) chiama `primary` il proprio colore base,
+    mentre i token di minimo referenziano `{primary.100}` — invece di
+    rinominare la proprietà a mano dopo ogni build, o di cercare ogni
+    riferimento di minimo per modificarlo, `transform` corregge una volta sola
+    il percorso del token, qui.
+      - Entrambi i lati della mappa usano la notazione DOT-PATH di Style Dictionary
+        ('primary.100'), NON la notazione delle custom properties con trattini
+        ('primary-100'): i segmenti dei nomi dei token in questo progetto possono
+        contenere trattini (ad es. btn-close), quindi un trattino non permette di
+        distinguere in modo affidabile un separatore di percorso da una parte letterale
+        del nome di un segmento — un punto invece sì, perché è già riservato da
+        Style Dictionary come separatore di percorso dei {riferimenti}.
+      - I {riferimenti} al VECCHIO percorso — nello stesso file o in uno completamente
+        diverso — vengono riscritti automaticamente, in tutto l'albero, col NUOVO
+        percorso una volta uniti tutti i sorgenti: ad es. ogni {primary} dell'intera
+        build diventa {primary.100}, sia che i token di minimo scrivessero già
+        direttamente {primary.100} (nessun effetto) sia che altro nel
+        progetto dica ancora {primary}.
+      - ATTENZIONE: questa riscrittura è per design indipendente dal file (un semplice
+        {riferimento} non sa a quale file "appartiene") — quindi se la
+        STESSA chiave sorgente (ad es. "primary") ha una destinazione DIVERSA nelle
+        mappe `transform` di due file diversi, ogni rinomina funziona comunque da sola,
+        ma {primary} diventa ambiguo: a quale destinazione va riscritto?
+        In quel caso la riscrittura automatica viene saltata per quella chiave
+        (viene registrato un warning) e ogni riferimento {primary} va corretto
+        a mano per puntare al giusto fra i due nuovi percorsi.
+      - Una chiave sorgente non trovata nel file registra solo un warning, non fa
+        fallire la build.
+      - Si applica sia all'output CSS sia a quello JSON (vedi OUTPUT JSON DEI TOKEN
+        più sotto), perché entrambi vengono ricostruiti dal percorso del token, ormai
+        già rinominato.
+
+    Entrambe le opzioni funzionano allo stesso modo dentro sourceModes.
+  */
   source: [
-    `${minimo_path}/design-tokens/_src/**/*.tokens.{mjs,jsonc}`, // main tokens
-    `${minimo_path}/src/**/*.tokens.{mjs,jsonc}`, // components tokens
+    `${minimo_path}/design-tokens/_src/**/*.tokens.{mjs,jsonc}`, // token principali
+    `${minimo_path}/src/**/*.tokens.{mjs,jsonc}`, // token dei componenti
 
-    // optional extra token source (in this example, openProps, https://open-props.style/)
+    // sorgente di token extra opzionale (in questo esempio, openProps, https://open-props.style/)
     // { src: `${node_modules_path}/open-props/open-props.style-dictionary-tokens.json`, prefix: 'op' },
 
-    // your project tokens — e.g. remaps a Figma/Penpot-exported `primary`
-    // color to minimo's own `primary.100` naming
+    /*
+      i token del tuo progetto — ad es. rimappa il colore `primary`
+      esportato da Figma/Penpot sulla nomenclatura `primary.100` di minimo
+    */
     {
       src: './design-tokens/*.{js,mjs,jsonc,json}',
       prefix: 'my-project',
@@ -120,129 +125,145 @@ const config = {
     }
   ],
 
-  // 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`.
-  //
-  // Cross-mode references: tokens of a non-base mode can reference tokens
-  // defined in the base mode (e.g. a dark token using {color.1} defined in
-  // light); it resolves to var(--color-1). The reverse (or between two
-  // non-base modes) is not supported and fails with a "reference not
-  // defined" error, since the target would be undefined outside its own
-  // @media block.
-  //
-  // 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}',
-  //   ],
-  // },
+  /*
+    Suddivisione opzionale light/dark (o altra) delle custom properties — alternativa a
+    `source`. Se questa chiave è impostata (un oggetto non null), `source` qui sopra viene
+    ignorato: ogni chiave è il nome di una modalità, con il proprio array di pattern sorgente
+    (stesse regole di `source`: percorsi, glob o una combinazione).
+
+    Il CSS generato compone tutte le modalità in un unico destFile:
+      - le proprietà della modalità base (vedi sourceModesBase più sotto) vanno in un blocco
+        `:root { ... }` di primo livello, con `color-scheme: <tutte le modalità>;` anteposto
+        (ad es. "light dark")
+      - le proprietà di ogni altra modalità vanno in
+        `@media (prefers-color-scheme: <modalità>) { :root { ... } }`, con
+        `color-scheme: <modalità>;` anteposto
+    customPropsGroups, mergeCustomProps, addLayer, pxToRem ecc. si applicano
+    allo stesso modo che con un singolo `source`.
+
+    Riferimenti tra modalità: i token di una modalità non base possono referenziare i token
+    definiti nella modalità base (ad es. un token dark che usa {color.1} definito in
+    light); viene risolto in var(--color-1). Il contrario (o tra due
+    modalità non base) non è supportato e fallisce con un errore "reference not
+    defined", perché il target risulterebbe non definito fuori dal proprio
+    blocco @media.
+
+    L'output JSON (vedi OUTPUT JSON DEI TOKEN più sotto) viene prodotto una volta per
+    modalità, con il nome della modalità aggiunto a ogni nome di file, ad es. con
+    jsonDestFile: 'tokens' -> "tokens-light.jsonc", "tokens-dark.jsonc".
+
+    esempio:
+    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, and only if it defines both a `light` and a `dark`
-  // key: custom properties present in BOTH — matched by name — are written
-  // once as `--name: light-dark(<light-value>, <dark-value>);`, instead of
-  // being split across the base mode's top-level block and a
-  // `@media (prefers-color-scheme: dark) { ... }` rule.
-  //
-  // Unaffected:
-  //   - any other key in sourceModes besides light/dark (e.g. a third,
-  //     custom mode) — always stays on its own
-  //     `@media (prefers-color-scheme: <mode>) { ... }` rule
-  //   - a property present in only one of `light`/`dark` — stays in its own
-  //     mode's block (still behind `@media`, unless that mode happens to be
-  //     sourceModesBase)
-  //
-  // Whenever this option is active (sourceModes has both a light and a dark
-  // key), the base mode's `color-scheme` declaration is always normalised to
-  // read "light dark [...any other mode]", with light before dark — matching
-  // light-dark()'s own (light-value, dark-value) argument order — regardless
-  // of the order sourceModes keys were declared in, or of which of the two
-  // is configured as sourceModesBase below.
-  //
-  // Interaction with mergeCustomProps: no special handling needed — the
-  // per-mode merge with pre-existing custom properties always runs first;
-  // this option then reconciles whatever value ends up in each mode
-  // (freshly generated or preserved from a pre-existing file) into
-  // light-dark(), matched by name. This also means that re-running a build
-  // with this option newly turned on, over a destFile previously generated
-  // with it off (classic `@media (prefers-color-scheme: dark)` split) and
-  // mergeCustomProps: true, converts the preserved values into light-dark()
-  // calls too — as with any mergeCustomProps case, a resulting mismatch is
-  // left for you to fix.
-  //
-  // Default: true. Ignored when sourceModes is not set (null/undefined).
+  /*
+    Con sourceModes impostato, e solo se definisce sia una chiave `light` sia una `dark`:
+    le custom properties presenti in ENTRAMBE — individuate per nome — vengono scritte
+    una sola volta come `--name: light-dark(<valore-light>, <valore-dark>);`, invece di
+    essere divise tra il blocco di primo livello della modalità base e una regola
+    `@media (prefers-color-scheme: dark) { ... }`.
+
+    Non vengono toccati:
+      - gli altri eventuali valori di sourceModes oltre a light/dark (ad es. una terza
+        modalità personalizzata) — restano sempre sulla propria regola
+        `@media (prefers-color-scheme: <modalità>) { ... }`
+      - una proprietà presente in una sola tra `light`/`dark` — resta nel blocco della
+        propria modalità (sempre dietro `@media`, a meno che quella modalità non sia
+        sourceModesBase)
+
+    Ogni volta che questa opzione è attiva (sourceModes ha sia una chiave light sia una
+    dark), la dichiarazione `color-scheme` della modalità base viene sempre normalizzata
+    in "light dark [...ogni altra modalità]", con light prima di dark — coerentemente con
+    l'ordine degli argomenti (valore-light, valore-dark) di light-dark() — indipendentemente
+    dall'ordine in cui sono dichiarate le chiavi di sourceModes o da quale delle due
+    sia configurata come sourceModesBase qui sotto.
+
+    Interazione con mergeCustomProps: non serve alcuna gestione speciale — il merge
+    per modalità con le custom properties preesistenti viene sempre eseguito per primo;
+    questa opzione poi riconcilia il valore che risulta in ogni modalità
+    (appena generato o conservato da un file preesistente) in light-dark(),
+    individuando le proprietà per nome. Ciò significa anche che rieseguire una build
+    con questa opzione appena attivata, su un destFile generato in precedenza
+    con l'opzione disattivata (divisione classica `@media (prefers-color-scheme: dark)`) e
+    mergeCustomProps: true, converte anche i valori conservati in chiamate light-dark() —
+    come in ogni caso di mergeCustomProps, un eventuale disallineamento resta da
+    correggere a mano.
+
+    Default: true. Ignorata quando sourceModes non è impostato (null/undefined).
+  */
   useLightDarkFunc: true,
 
-  // 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.
+  /*
+    Con sourceModes impostato: la modalità le cui dichiarazioni vanno nel blocco
+    `:root { ... }` di primo livello, invece che annidate nella propria regola
+    `@media (prefers-color-scheme: <modalità>) { ... }` (default: la prima
+    chiave di sourceModes, ad es. 'light'). Ignorata quando sourceModes non è impostato.
+  */
   sourceModesBase: 'light',
 
-  // CSS selector wrapping the generated custom properties block(s), instead
-  // of the default `:root`. Applies uniformly whether using a single
-  // `source` or `sourceModes` (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 this same
-  // selector). Falsy or blank values fall back to ':root'.
+  /*
+    Selettore CSS che racchiude i blocchi di custom properties generati, al posto
+    del default `:root`. Si applica in modo uniforme sia con un singolo
+    `source` sia 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'.
+  */
   customPropsSelector: ':where(html)',
 
-  // 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.
+  /*
+    Se true (default), i valori dei token di tipo dimension espressi in px vengono convertiti
+    in rem nel CSS generato. I valori in altre unità (em, %, vh, dvw, ...)
+    non vengono mai toccati, indipendentemente da questa opzione.
+  */
   pxToRem: false,
 
-  // Preserves custom properties already present in the CSS destination file
-  // (destFile, from a previous build) across rebuilds: their values take
-  // priority over the ones generated by this build. Useful to keep manual
-  // overrides/additions made directly in the compiled CSS. Ignored if the
-  // destFile does not exist yet. Accepted values:
-  //   false           - no merge: the destination file is fully regenerated
-  //   true (default)  - merge all the sources
-  //   array           - strings and/or RegExps matched against the path of the
-  //                     token source files (those in `source` or `sourceModes`):
-  //                     only the properties generated by a matching file are
-  //                     merged, the others are overwritten by the generated value.
-  //                     A string matches if contained in the file path.
-  //                     An empty array is treated as false.
-  //                     e.g. ['/theme.minimo.tokens', /colors\.tokens\.(mjs|jsonc?)$/]
-  // With true or an array, properties found only in the pre-existing file (no
-  // longer generated, e.g. added by hand) are always kept.
-  // Comments at the end of a custom property line are preserved; full-line
-  // comments are lost, and a multi-line comment is cut at the end of its first
-  // line (and closed, to keep the CSS valid).
+  /*
+    Conserva, tra una build e l'altra, le custom properties già presenti nel file CSS di
+    destinazione (destFile, da una build precedente): i loro valori hanno priorità
+    su quelli generati da questa build. Utile per mantenere override/aggiunte
+    manuali fatte direttamente nel CSS compilato. Ignorata se destFile non esiste
+    ancora. Valori accettati:
+      false           - nessun merge: il file di destinazione viene rigenerato completamente
+      true (default)  - merge di tutte le sorgenti
+      array           - stringhe e/o RegExp confrontate con il percorso dei
+                        file token sorgente (quelli in `source` o `sourceModes`):
+                        vengono unite solo le proprietà generate da un file corrispondente,
+                        le altre vengono sovrascritte dal valore generato.
+                        Una stringa corrisponde se è contenuta nel percorso del file.
+                        Un array vuoto è trattato come false.
+                        ad es. ['/theme.minimo.tokens', /colors\.tokens\.(mjs|jsonc?)$/]
+    Con true o con un array, le proprietà presenti solo nel file preesistente (non più
+    generate, ad es. aggiunte a mano) vengono sempre conservate.
+    I commenti a fine riga di una custom property vengono conservati; i commenti su riga
+    intera vanno persi e un commento su più righe viene troncato alla fine della sua prima
+    riga (e chiuso, per mantenere valido il CSS).
+  */
   mergeCustomProps: true,
 
-  // Wraps the generated custom properties inside a CSS `@layer` at-rule,
-  // e.g. addLayer: 'project' -> `@layer project { :root { ... } }`.
-  // Set to null, undefined or false (default) to emit no layer.
+  /*
+    Racchiude le custom properties generate in una regola at-rule CSS `@layer`,
+    ad es. addLayer: 'project' -> `@layer project { :root { ... } }`.
+    Impostare a null, undefined o false (default) per non emettere alcun layer.
+  */
   addLayer: false,
 
-  // Named groups of custom properties. Properties whose first hyphen-separated
-  // name segment matches one of a group's `prefixes` are pulled out, labelled
-  // with the group's `name` and placed at the beginning of the output CSS
-  // file, in the order the groups are listed here.
+  /*
+    Gruppi nominati di custom properties. Le proprietà il cui primo segmento del nome
+    (separato da trattini) corrisponde a uno dei `prefixes` di un gruppo vengono estratte,
+    etichettate con il `name` del gruppo e collocate all'inizio del file CSS
+    di output, nell'ordine in cui i gruppi sono elencati qui.
+  */
   customPropsGroups: [
     {
       name: 'COLORS',
@@ -260,68 +281,84 @@ const config = {
 
 
   // ---------------------------------------------------------------------------
-  // JSON TOKENS OUTPUT
+  // OUTPUT JSON DEI TOKEN
   // ---------------------------------------------------------------------------
-  // Optional design tokens output, independent of any specific consuming tool
-  // Generates one or more json(c) files in addition to the CSS output file —
-  // usable in Penpot, Figma (via plugin), Token Studio, or as an alternative
-  // to the .mjs source files
+  /*
+    Output opzionale dei design token, indipendente da qualsiasi strumento specifico
+    Genera uno o più file json(c) in aggiunta al file CSS di output —
+    utilizzabili in Penpot, Figma (tramite plugin), Token Studio, oppure in alternativa
+    ai file sorgente .mjs
+  */
   // ---------------------------------------------------------------------------
 
-  // How to handle math expressions in dimension token $values (e.g. "{size.base} * .25"):
-  //   'keep'    write the expression unchanged
-  //   'calc'    — wrap in CSS calc(): "calc({size.base} * .25)"
-  //   'resolve' — (default) evaluate numerically, inheriting the unit from the first referenced token
-  //               e.g. {size.base} = 16px, "{size.base} * .25" -> "4px"
+  /*
+    Come gestire le espressioni matematiche nei $value dei token dimension (es. "{size.base} * .25"):
+      'keep'    scrive l'espressione invariata
+      'calc'    — la racchiude in calc() CSS: "calc({size.base} * .25)"
+      'resolve' — (default) la valuta numericamente, ereditando l'unità dal primo token referenziato
+                  es. {size.base} = 16px, "{size.base} * .25" -> "4px"
+  */
   jsonExpression: 'resolve',
 
-  // Output format for the JSON token files: 'jsonc' or 'json'
-  //   'jsonc' -> adds a generated-file disclaimer header, uses .jsonc extension
-  //   'json'  -> plain JSON, no disclaimer
+  /*
+    Formato di output dei file JSON dei token: 'jsonc' o 'json'
+      'jsonc' -> aggiunge un'intestazione che segnala il file generato, usa l'estensione .jsonc
+      'json'  -> JSON semplice, senza intestazione
+  */
   jsonFormat: 'jsonc',
 
-  // Output directory for the JSON design token files.
-  // Set to null (or omit) to disable json output entirely.
-  // In multi-file mode (jsonDestFile: null), all files are written flat in
-  // this directory (no subdirectories mirroring the source tree); the build
-  // fails with an error if two source files would produce the same filename.
-  jsonBuildPath: null, // or './path/to/generated/design-tokens-dir',
+  /*
+    Directory di output dei file JSON dei design token.
+    Impostare a null (o omettere) per disattivare del tutto l'output json.
+    In modalità multi-file (jsonDestFile: null), tutti i file vengono scritti nella stessa
+    directory (senza sottocartelle che replicano l'albero dei sorgenti); la build
+    fallisce con un errore se due file sorgente producono lo stesso nome file.
+  */
+  jsonBuildPath: null, // oppure './path/to/generated/design-tokens-dir',
 
-  // Base name (without extension) for the aggregated JSON output file.
-  // The extension is added automatically based on jsonFormat.
-  // Set to null (or omit) to generate one file per .mjs source file instead
-  // (all placed flat in jsonBuildPath — see jsonBuildPath above).
-  jsonDestFile: null, // or 'tokens' (or else),
+  /*
+    Nome base (senza estensione) del file JSON aggregato di output.
+    L'estensione viene aggiunta automaticamente in base a jsonFormat.
+    Impostare a null (o omettere) per generare invece un file per ogni file sorgente .mjs
+    (tutti nella stessa cartella jsonBuildPath — vedi jsonBuildPath qui sopra).
+  */
+  jsonDestFile: null, // oppure 'tokens' (o altro),
 
 
   // ---------------------------------------------------------------------------
-  // CHECK UNRESOLVED & UNUSED CUSTOM PROPS SETTINGS
+  // IMPOSTAZIONI DI CONTROLLO CUSTOM PROPS NON RISOLTE E NON USATE
   // ---------------------------------------------------------------------------
 
-  // If true, also reports custom properties that are defined (in destFile or
-  // an extraCustomPropsFiles entry) but never referenced via var() in any
-  // scanned CSS file. Opt-in because it re-runs the Style Dictionary
-  // transform pipeline over the token sources to resolve, when possible, the
-  // .mjs source file for each unused property. Default: false.
+  /*
+    Se true, segnala anche le custom properties definite (in destFile o
+    in una voce di extraCustomPropsFiles) ma mai referenziate tramite var() in nessun
+    file CSS analizzato. Opt-in perché riesegue la pipeline di trasformazione
+    di Style Dictionary sui sorgenti dei token per risalire, quando possibile, al
+    file sorgente .mjs di ogni proprietà non usata. Default: false.
+  */
   checkUnused: true,
 
-  // When checkUnused is true: if true (default), custom properties sourced
-  // from a token file under node_modules (e.g. a third-party token package)
-  // are never reported as unused — the consuming project isn't expected to
-  // prune those.
+  /*
+    Quando checkUnused è true: se true (default), le custom properties provenienti
+    da un file token sotto node_modules (es. un pacchetto di token di terze parti)
+    non vengono mai segnalate come non usate — il progetto che le usa non è tenuto
+    a ripulirle.
+  */
   ignoreUnusedInNodeModules: true,
 
-  // Additional CSS files that define custom properties used in the project
-  // but not generated by build-tokens (e.g. third-party libraries)
+  // File CSS aggiuntivi che definiscono custom properties usate nel progetto
+  // ma non generate da build-tokens (ad es. librerie di terze parti)
   extraCustomPropsFiles: [
     // `${node_modules_path}/open-props/open-props.min.css`
   ],
 
-  // Directory containing the CSS files to scan for unresolved custom properties
+  // Directory che contiene i file CSS da analizzare per le custom properties non risolte
   dirToCheck: '../../app',
 
-  // Regular expressions for custom property names to exclude from the check.
-  // Useful for intentionally private/internal props (e.g. prefixed with --_).
+  /*
+    Espressioni regolari dei nomi di custom property da escludere dal controllo.
+    Utile per le proprietà volutamente private/interne (es. con prefisso --_).
+  */
   excludePattern: [
     /^--_/,
   ],