@massimo-cassandro/minimo 1.20.7 → 1.20.8

package/design-tokens/README.md

@@ -56,7 +56,7 @@ Read comments inside the sample file for more info.
 
 Reads design token source files and generates:
 - A **CSS file** containing all tokens as custom properties inside `:root { ... }`
-- Optionally, one or more **W3C DTCG JSON/JSONC** files to import into Penpot/Figma (use in Figma requires a plugin).
+- Optionally, one or more **W3C DTCG JSON/JSONC** files, independent of any specific consuming tool (usable in Penpot, Figma via plugin, Token Studio, ...).
 
 #### Usage
 
@@ -129,32 +129,33 @@ Typography tokens are expanded into multiple properties:
 
 The generated file is linted and auto-fixed with stylelint using the config specified in `stylelintConfigPath`.
 
-#### Penpot output
+#### JSON output
 
-When `penpotBuildPath` is set, the script also generates W3C DTCG token files for import into Penpot via the [Design Tokens plugin](https://penpot.app/penpot-files/design-tokens).
+When `jsonBuildPath` is set, the script also generates W3C DTCG token files, independent of any specific consuming tool (e.g. importable into Penpot via the [Design Tokens plugin](https://penpot.app/penpot-files/design-tokens), into Figma via a compatible plugin, or into Token Studio).
 
-**Single file** (`penpotDestFile` is a string):
+**Single file** (`jsonDestFile` is a string):
 ```
-penpotBuildPath/tokens.jsonc   ← all tokens in one file
+jsonBuildPath/tokens.jsonc   ← all tokens in one file
 ```
 
-**One file per source** (`penpotDestFile` is `null` or omitted):
+**One file per source** (`jsonDestFile` is `null` or omitted):
 ```
-penpotBuildPath/colors.tokens.jsonc
-penpotBuildPath/spacing.tokens.jsonc
-penpotBuildPath/typography.tokens.jsonc
+jsonBuildPath/colors.tokens.jsonc
+jsonBuildPath/spacing.tokens.jsonc
+jsonBuildPath/typography.tokens.jsonc
 ```
+All files are written flat in `jsonBuildPath`, regardless of the subdirectory structure of the source files — no subdirectories are created. If two source files with different paths would produce the same output filename, the build fails with an error listing the colliding files instead of silently overwriting one with the other.
 
-The `penpotFormat` option controls the output:
+The `jsonFormat` option controls the output:
 
 | Value | Extension | Disclaimer header |
 |---|---|---|
 | `'jsonc'` | `.jsonc` | Yes |
 | `'json'` | `.json` | No |
 
-Alias references (`{color.brand.primary}`) are preserved in the output so Penpot maintains token links between primitive and semantic tokens.
+Alias references (`{color.brand.primary}`) are preserved in the output so consuming tools maintain token links between primitive and semantic tokens.
 
-> Penpot token files intentionally use a minimal set of transforms (no px→rem conversion, no shorthand expansion) because Penpot expects original values and structured objects, not resolved CSS strings.
+> JSON token files intentionally use a minimal set of transforms (no px→rem conversion, no shorthand expansion) because consuming tools generally expect original values and structured objects, not resolved CSS strings.
 
 ---
 

package/design-tokens/_src/typography.minimo.tokens.mjs

@@ -12,43 +12,49 @@ export default {
     size: {
       base: {
         $value: 'clamp(.9rem, .6538rem + .3846vw, 1rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64 to 90 rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiLjlyZW0iLCJtYXhGb250U2l6ZSI6IjFyZW0ifQ%3D%3D'
       },
       xxs: {
         $value: 'clamp(.6rem, .3538rem + .3846vw, .7rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiLjZyZW0iLCJtYXhGb250U2l6ZSI6Ii43cmVtIn0%3D'
       },
       xs: {
         $value: 'clamp(.7rem, .4538rem + .3846vw, .8rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiLjdyZW0iLCJtYXhGb250U2l6ZSI6Ii44cmVtIn0%3D'
       },
       sm: {
         $value: 'clamp(.8rem, .5538rem + .3846vw, .9rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiLjhyZW0iLCJtYXhGb250U2l6ZSI6Ii45cmVtIn0%3D'
       },
-      // lead: {
-      //   $value: 'clamp(1rem, 0.6923rem + 0.4808vw, 1.125rem)',
-      //   $type: 'string'
-      // },
+
       md: {
         $value: 'clamp(1.05rem, .6808rem + .5769vw, 1.2rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiMS4wNXJlbSIsIm1heEZvbnRTaXplIjoiMS4ycmVtIn0%3D'
       },
       lg: {
         $value: 'clamp(1.2rem, .7077rem + .7692vw, 1.4rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiMS4ycmVtIiwibWF4Rm9udFNpemUiOiIxLjRyZW0ifQ%3D%3D'
       },
       xl: {
         $value: 'clamp(1.6rem, 1.1077rem + .7692vw, 1.8rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiMS42cmVtIiwibWF4Rm9udFNpemUiOiIxLjhyZW0ifQ%3D%3D'
       },
       '2xl': {
         $value: 'clamp(2rem, .7692rem + 1.9231vw, 2.5rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiMnJlbSIsIm1heEZvbnRTaXplIjoiMi41cmVtIn0%3D'
       },
       '3xl': {
         $value: 'clamp(2.2rem, .2308rem + 3.0769vw, 3rem)',
-        $type: 'string'
+        $type: 'string',
+        $description: '64-90rem: https://clamp.font-size.app/?config=eyJyb290IjoiMTYiLCJtaW5XaWR0aCI6IjY0cmVtIiwibWF4V2lkdGgiOiI5MHJlbSIsIm1pbkZvbnRTaXplIjoiMi4ycmVtIiwibWF4Rm9udFNpemUiOiIzcmVtIn0%3D'
       }
     },
 

package/design-tokens/tokens-config-sample.mjs

@@ -80,11 +80,12 @@ const config = {
 
 
   // ---------------------------------------------------------------------------
-  // PENPOT / FIGMA
+  // JSON TOKENS OUTPUT
   // ---------------------------------------------------------------------------
-  // Optional design tokens output
-  // Generates one or more json(c) files in addition to the CSS output file, for use
-  // in Penpot or Figma projects or as an alternative to the .mjs source files
+  // 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
   // ---------------------------------------------------------------------------
 
   // How to handle math expressions in dimension token $values (e.g. "{size.base} * .25"):
@@ -92,21 +93,25 @@ const config = {
   //   '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"
-  penpotExpressions: 'resolve',
+  jsonExpression: 'resolve',
 
-  // Output format for Penpot token files: 'jsonc' or 'json'
+  // 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
-  penpotFormat: 'jsonc',
+  jsonFormat: 'jsonc',
 
-  // Output directory for the Penpot design token files.
+  // Output directory for the JSON design token files.
   // Set to null (or omit) to disable json output entirely.
-  penpotBuildPath: null, // or './path/to/generated/design-tokens-dir',
-
-  // Base name (without extension) for the aggregated Penpot output file.
-  // The extension is added automatically based on penpotFormat.
-  // Set to null (or omit) to generate one file per .mjs source file instead.
-  penpotDestFile: null, // or 'tokens' (or else),
+  // 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',
+
+  // 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),
 
 
   // ---------------------------------------------------------------------------

package/design-tokens/utilities/build-tokens-src/config.mjs

@@ -51,29 +51,29 @@ export const destFile  = buildConfig.destFile;
 // Stylelint
 export const stylelintConfigPath = resolveFromConfig(buildConfig.stylelintConfigPath);
 
-// Penpot — platform is active only if penpotBuildPath is set in the config
-const penpotBuildPathRaw = buildConfig.penpotBuildPath ?? null;
-export const penpotBuildPath = penpotBuildPathRaw ? resolveFromConfig(penpotBuildPathRaw) : null;
+// JSON — platform is active only if jsonBuildPath is set in the config
+const jsonBuildPathRaw = buildConfig.jsonBuildPath ?? null;
+export const jsonBuildPath = jsonBuildPathRaw ? resolveFromConfig(jsonBuildPathRaw) : null;
 
-// penpotDestFile: base name (no extension) for the aggregated output file.
+// 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 penpotFormat.
-export const penpotDestFile = buildConfig.penpotDestFile ?? null;
+// The extension is added automatically based on jsonFormat.
+export const jsonDestFile = buildConfig.jsonDestFile ?? null;
 
-// penpotFormat: controls output format for Penpot token files.
+// 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'.
-export const penpotFormat = buildConfig.penpotFormat === 'jsonc' ? 'jsonc' : 'json';
+export const jsonFormat = buildConfig.jsonFormat === 'jsonc' ? 'jsonc' : 'json';
 
-// penpotExpressions: controls how math expressions in dimension token values are handled.
+// 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
 const VALID_EXPR_MODES = ['keep', 'calc', 'resolve'];
-export const penpotExpressions = VALID_EXPR_MODES.includes(buildConfig.penpotExpressions)
-  ? buildConfig.penpotExpressions
+export const jsonExpression = VALID_EXPR_MODES.includes(buildConfig.jsonExpression)
+  ? buildConfig.jsonExpression
   : 'resolve';
 
 // pxToRem: if true (default), dimension token values expressed in px are

package/design-tokens/utilities/build-tokens-src/formats/css.mjs

@@ -131,6 +131,17 @@ const buildTypography = (tokenName, original, resolveRefs) => {
   return lines.join('\n');
 };
 
+// Builds a trailing ` /* ... */` comment from a token's $description, to be
+// appended at the end of its generated custom prop declaration (same line).
+// Newlines are collapsed (declarations are parsed one line at a time, see
+// parseCustomProps in ../merge-css.mjs) and `*/` is escaped so the comment
+// can't be closed early by its own content.
+const buildDescriptionComment = (description) => {
+  if (!description) return '';
+  const flat = String(description).replace(/\s*\n\s*/g, ' ').trim().replace(/\*\//g, '* /');
+  return flat ? ` /* ${flat} */` : '';
+};
+
 // Builds a customPropsGroups title comment, e.g.:
 //   /* ****** LAYOUT ****** */
 // Dashes fill out a fixed total width so titles line up regardless of name length.
@@ -185,9 +196,15 @@ StyleDictionary.registerFormat({
       .flatMap((token) => {
         const type = token.$type ?? token.type;
         const orig = token.original?.$value ?? token.original?.value;
+        const description = token.$description ?? token.description ?? token.comment;
+        const commentSuffix = buildDescriptionComment(description);
 
         if (type === 'typography') {
-          return [buildTypography(token.name, orig ?? {}, resolveRefs)];
+          const typographyLines = buildTypography(token.name, orig ?? {}, resolveRefs)
+            .split('\n')
+            .map((line) => `${line}${commentSuffix}`)
+            .join('\n');
+          return [typographyLines];
         }
 
         let value;
@@ -230,7 +247,7 @@ StyleDictionary.registerFormat({
           value = String(token.$value ?? token.value);
         }
 
-        return [`  --${token.name}: ${value};`];
+        return [`  --${token.name}: ${value};${commentSuffix}`];
       });
 
     // Build a name → declaration-tail map from the declarations generated

package/design-tokens/utilities/build-tokens-src/formats/{penpot.mjs → json.mjs}

@@ -1,30 +1,33 @@
-// build-tokens-src/formats/penpot.mjs
-// Registers the 'json/penpot' format and exports buildPenpotFiles() and
+// build-tokens-src/formats/json.mjs
+// Registers the 'json/tokens' format and exports buildJsonFiles() and
 // collectConcreteFilePaths().
 //
-// The format produces a W3C DTCG nested file importable into Penpot via the
-// "Design Tokens" plugin (also compatible with Token Studio and Supernova).
+// The format produces a W3C DTCG nested JSON(C) file, independent of any
+// specific consuming tool (usable in Penpot, Figma via plugin, Token Studio,
+// Supernova, or any other DTCG-compatible tool).
 //
-// Output format is controlled by the penpotFormat option in the project config:
+// Output format is controlled by the jsonFormat option in the project config:
 //   'jsonc' -> .jsonc extension + generated-file disclaimer header
 //   'json'  -> plain .json, no disclaimer
 //
-// buildPenpotFiles() builds the `files` array for the penpot platform:
-//   penpotDestFile set  -> single aggregated file
-//   penpotDestFile null -> one file per concrete source file, mirroring the
-//                          subdirectory structure of the source tree
+// buildJsonFiles() builds the `files` array for the json platform:
+//   jsonDestFile set  -> single aggregated file
+//   jsonDestFile null -> one file per concrete source file, all placed flat
+//                        in jsonBuildPath (no subdirectories) — see the
+//                        collision check in buildJsonFiles()
 //
-// ── Expression handling (penpotExpressions option) ───────────────────────────
+// ── Expression handling (jsonExpression option) ─────────────────────────────
 //
 // Dimension tokens may carry math expressions in their $value, e.g.:
 //   { $type: "dimension", $value: "{size.base} * .25" }
 //
-// The penpotExpressions config option controls how these are handled:
+// The jsonExpression config option controls how these are handled:
 //
-//   'keep'    (default) — write the expression as-is; Penpot or the consuming
-//                         tool is expected to evaluate it.
+//   'keep'    (default) — write the expression as-is; the consuming tool is
+//                         expected to evaluate it.
 //   'calc'    — wrap in a CSS calc(): "calc({size.base} * .25)"
-//                         aliases are left as {references} for Penpot to resolve.
+//                         aliases are left as {references} for the consuming
+//                         tool to resolve.
 //   'resolve' — evaluate the expression numerically and write a concrete value.
 //                         The unit is inherited from the first dimension token
 //                         referenced in the expression (e.g. {size.base} = 16px
@@ -34,7 +37,7 @@
 import StyleDictionary from 'style-dictionary';
 import path from 'node:path';
 
-// Disclaimer prepended to every generated file when penpotFormat is 'jsonc'
+// Disclaimer prepended to every generated file when jsonFormat is 'jsonc'
 const DISCLAIMER = [
   '// -----------------------------------------------------------------------',
   '// Generated file — do not edit manually.',
@@ -126,10 +129,10 @@ const toCalc = (orig) => `calc(${orig})`;
 // ── Format ───────────────────────────────────────────────────────────────────
 
 StyleDictionary.registerFormat({
-  name: 'json/penpot',
+  name: 'json/tokens',
   format: ({ dictionary, options }) => {
     const root = {};
-    const expressionMode = options.penpotExpressions ?? 'keep'; // 'keep' | 'calc' | 'resolve'
+    const expressionMode = options.jsonExpression ?? 'keep'; // 'keep' | 'calc' | 'resolve'
     const tokenMap = (expressionMode === 'resolve') ? makeTokenMap(dictionary) : null;
 
     for (const token of dictionary.allTokens) {
@@ -161,7 +164,7 @@ StyleDictionary.registerFormat({
           } else {
             // Resolution failed — keep the original and emit a warning
             // eslint-disable-next-line no-console
-            console.warn(`[build-tokens] penpot: could not resolve expression "${orig}" for token "${token.path.join('.')}". Keeping original.`);
+            console.warn(`[build-tokens] json: could not resolve expression "${orig}" for token "${token.path.join('.')}". Keeping original.`);
             value = orig;
           }
         } else if (expressionMode === 'calc') {
@@ -173,7 +176,7 @@ StyleDictionary.registerFormat({
         }
       } else {
         // Non-expression value: preserve {references} wherever they appear.
-        //   - Pure alias:   "{some.token}"           → kept as-is for Penpot token links
+        //   - Pure alias:   "{some.token}"           → kept as-is to preserve token links
         //   - CSS function: "color-mix(in srgb, {some.token} 60%, #000)" → kept as-is
         //   - Plain value:  "#ff0000", "16px", …     → use the resolved $value
         const containsRef = typeof orig === 'string' && orig.includes('{');
@@ -193,23 +196,6 @@ StyleDictionary.registerFormat({
   },
 });
 
-// ── commonDir ────────────────────────────────────────────────────────────────
-// Returns the longest common directory prefix shared by all given file paths.
-// Used to compute relative paths that mirror the source subdirectory structure.
-
-const commonDir = (filePaths) => {
-  if (filePaths.length === 0) return '';
-  if (filePaths.length === 1) return path.dirname(filePaths[0]);
-
-  const dirs  = filePaths.map(fp => path.dirname(path.resolve(fp)));
-  const parts = dirs[0].split(path.sep);
-
-  let i = 0;
-  while (i < parts.length && dirs.every(d => d.split(path.sep)[i] === parts[i])) i++;
-
-  return parts.slice(0, i).join(path.sep);
-};
-
 // ── collectConcreteFilePaths ──────────────────────────────────────────────────
 //
 // Extracts the unique concrete file paths from a Style Dictionary instance.
@@ -224,42 +210,59 @@ export const collectConcreteFilePaths = async (sd) => {
   return [...paths].sort();
 };
 
-// ── buildPenpotFiles ──────────────────────────────────────────────────────────
+// ── buildJsonFiles ──────────────────────────────────────────────────────────
 //
 // @param {string[]}                       concreteFilePaths  From collectConcreteFilePaths()
-// @param {string|null}                    penpotDestFile     Aggregated file base name, or null
-// @param {'json'|'jsonc'}                 penpotFormat       Output format
-// @param {'keep'|'calc'|'resolve'}        penpotExpressions  Expression handling mode
+// @param {string|null}                    jsonDestFile       Aggregated file base name, or null
+// @param {'json'|'jsonc'}                 jsonFormat         Output format
+// @param {'keep'|'calc'|'resolve'}        jsonExpression     Expression handling mode
 // @returns {object[]}  File descriptors for the Style Dictionary platform
 
-export const buildPenpotFiles = (
+export const buildJsonFiles = (
   concreteFilePaths,
-  penpotDestFile,
-  penpotFormat = 'json',
-  penpotExpressions = 'keep'
+  jsonDestFile,
+  jsonFormat = 'json',
+  jsonExpression = 'keep'
 ) => {
-  const ext  = penpotFormat === 'jsonc' ? '.jsonc' : '.json';
-  const jsonc = penpotFormat === 'jsonc';
+  const ext  = jsonFormat === 'jsonc' ? '.jsonc' : '.json';
+  const jsonc = jsonFormat === 'jsonc';
 
-  if (penpotDestFile) {
+  if (jsonDestFile) {
     return [{
-      destination: penpotDestFile + ext,
-      format: 'json/penpot',
-      options: { jsonc, penpotExpressions },
+      destination: jsonDestFile + ext,
+      format: 'json/tokens',
+      options: { jsonc, jsonExpression },
     }];
   }
 
-  const sourceRoot = commonDir(concreteFilePaths);
+  // One file per source, all placed flat in jsonBuildPath — no subdirectories
+  // mirroring the source tree. Since source files can share a basename across
+  // different directories (e.g. two components each with their own
+  // <name>.minimo.tokens.mjs), fail loudly on collisions instead of letting
+  // one silently overwrite the other.
+  const pathsByDestName = new Map();
+  for (const filePath of concreteFilePaths) {
+    const destName = path.basename(filePath).replace(/\.[^.]+$/, '') + ext;
+    if (!pathsByDestName.has(destName)) pathsByDestName.set(destName, []);
+    pathsByDestName.get(destName).push(filePath);
+  }
 
-  return concreteFilePaths.map((filePath) => {
-    const absPath  = path.resolve(filePath);
-    const relPath  = path.relative(sourceRoot, absPath);
-    const destName = relPath.replace(/\.[^.]+$/, '') + ext;
+  const collisions = [...pathsByDestName.entries()].filter(([, paths]) => paths.length > 1);
+  if (collisions.length > 0) {
+    const details = collisions
+      .map(([destName, paths]) => `  "${destName}" <- ${paths.join(', ')}`)
+      .join('\n');
+    throw new Error(
+      `[build-tokens] json: output filename collision — these source files would overwrite each other (json output files are flattened into a single directory):\n${details}`
+    );
+  }
 
+  return concreteFilePaths.map((filePath) => {
+    const absPath = path.resolve(filePath);
     return {
-      destination: destName,
-      format: 'json/penpot',
-      options: { jsonc, penpotExpressions },
+      destination: path.basename(filePath).replace(/\.[^.]+$/, '') + ext,
+      format: 'json/tokens',
+      options: { jsonc, jsonExpression },
       filter: (token) => {
         const fp = token.filePath ? path.resolve(token.filePath) : '';
         return fp === absPath;

package/design-tokens/utilities/build-tokens-src/platforms.mjs

@@ -1,10 +1,10 @@
 // build-tokens-src/platforms.mjs
 // Builds and returns the `platforms` object for the Style Dictionary config.
 //
-// The `penpot` platform is included only if penpotBuildPath is set.
-// Output format (json/jsonc) and file splitting are delegated to buildPenpotFiles().
+// The `json` platform is included only if jsonBuildPath is set.
+// Output format (json/jsonc) and file splitting are delegated to buildJsonFiles().
 
-import { buildPenpotFiles } from './formats/penpot.mjs';
+import { buildJsonFiles } from './formats/json.mjs';
 
 /** @typedef {import('style-dictionary/types').PlatformConfig} PlatformConfig */
 
@@ -24,10 +24,11 @@ export const CSS_TRANSFORMS = [
   'typography/css',
 ];
 
-// Transforms applied to the Penpot platform.
-// Kept minimal on purpose: Penpot expects original values (e.g. "16px" not "1rem")
-// and alias references ({...}) must be preserved to maintain token links.
-const PENPOT_TRANSFORMS = [
+// Transforms applied to the JSON platform.
+// 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 = [
   'attribute/cti',
   'name/kebab',
   'color/css-modern',
@@ -37,13 +38,13 @@ const PENPOT_TRANSFORMS = [
  * @param {object}          opts
  * @param {string}          opts.buildPath           Absolute path for CSS output directory
  * @param {string}          opts.destFile            CSS output filename (e.g. "tokens.css")
- * @param {string|null}     opts.penpotBuildPath     Absolute path for Penpot output (null = disabled)
- * @param {string|null}     opts.penpotDestFile      Base name for aggregated file; null = one file per source
- * @param {'json'|'jsonc'}  opts.penpotFormat        Output format for Penpot files
+ * @param {string|null}     opts.jsonBuildPath       Absolute path for JSON output (null = disabled)
+ * @param {string|null}     opts.jsonDestFile        Base name for aggregated file; null = one file per source
+ * @param {'json'|'jsonc'}  opts.jsonFormat          Output format for JSON files
  * @param {string[]}        opts.concreteFilePaths   Concrete (expanded) source file paths for multi-file mode.
  *                                                   Collected from sd.allTokens after SD initialisation.
- *                                                   Ignored when penpotDestFile is set.
- * @param {'keep'|'calc'|'resolve'} opts.penpotExpressions  How to handle math expressions in dimension tokens.
+ *                                                   Ignored when jsonDestFile is set.
+ * @param {'keep'|'calc'|'resolve'} opts.jsonExpression  How to handle math expressions in dimension tokens.
  * @param {{name: string, prefixes: string[]}[]} opts.customPropsGroups  Named groups of name prefixes, moved to the top of the CSS output in list order.
  * @param {boolean}         opts.pxToRem             If false, skips the px→rem transform on the CSS platform. Default: true.
  * @returns {Record<string, PlatformConfig>} platforms object ready for Style Dictionary config
@@ -51,10 +52,10 @@ const PENPOT_TRANSFORMS = [
 export const buildPlatforms = ({
   buildPath,
   destFile,
-  penpotBuildPath,
-  penpotDestFile,
-  penpotFormat,
-  penpotExpressions = 'keep',
+  jsonBuildPath,
+  jsonDestFile,
+  jsonFormat,
+  jsonExpression = 'keep',
   concreteFilePaths = [],
   customPropsGroups = [],
   pxToRem = true,
@@ -82,11 +83,11 @@ export const buildPlatforms = ({
     },
   };
 
-  if (penpotBuildPath) {
-    platforms.penpot = {
-      buildPath: penpotBuildPath + '/',
-      transforms: PENPOT_TRANSFORMS,
-      files: buildPenpotFiles(concreteFilePaths, penpotDestFile, penpotFormat, penpotExpressions),
+  if (jsonBuildPath) {
+    platforms.json = {
+      buildPath: jsonBuildPath + '/',
+      transforms: JSON_TRANSFORMS,
+      files: buildJsonFiles(concreteFilePaths, jsonDestFile, jsonFormat, jsonExpression),
     };
   }