@massimo-cassandro/minimo 0.3.6 → 0.4.0

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

@@ -0,0 +1,108 @@
+// 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.
+
+/* globals process */
+
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+// ---------------------------------------------------------------------------
+// Read the --config flag
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+const configFlagIndex = args.indexOf('--config');
+
+if (configFlagIndex === -1 || !args[configFlagIndex + 1]) {
+  // eslint-disable-next-line no-console
+  console.error(
+    'Error: you must specify the config file with --config ./path/to/config/file'
+  );
+  process.exit(1);
+}
+
+const configArgPath = args[configFlagIndex + 1];
+export const configAbsPath = path.resolve(process.cwd(), configArgPath);
+export const configDir     = path.dirname(configAbsPath);
+
+// ---------------------------------------------------------------------------
+// Import the project config
+// ---------------------------------------------------------------------------
+const buildConfig = (await import(pathToFileURL(configAbsPath))).default;
+
+// Helper: resolves a path relative to the config directory.
+// Leaves already-absolute paths untouched.
+const resolveFromConfig = (p) => path.resolve(configDir, p);
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+// CSS output
+export const buildPath = resolveFromConfig(buildConfig.buildPath);
+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;
+
+// penpotDestFile: 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;
+
+// penpotFormat: controls output format for Penpot 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';
+
+// penpotExpressions: 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
+  : 'resolve';
+
+// ---------------------------------------------------------------------------
+// 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).
+//
+// Glob patterns (containing *, ?, {, [) are NOT passed through path.join,
+// because path.join can normalise/collapse sequences that carry syntactic
+// meaning in a glob (e.g. "**"). They are only prefixed with configDir and
+// converted to forward slashes.
+// Concrete paths (no glob characters) are resolved canonically with path.resolve.
+//
+// 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}')
+// ---------------------------------------------------------------------------
+const GLOB_CHARS = /[*?{[]/;
+
+const resolveSource = (s) => {
+  if (path.isAbsolute(s)) {
+    // Already absolute: only normalise separators (needed on Windows)
+    return s.split(path.sep).join('/');
+  }
+  if (GLOB_CHARS.test(s)) {
+    // Glob pattern: prefix with configDir without touching the pattern
+    const prefix = configDir.split(path.sep).join('/');
+    return `${prefix}/${s}`;
+  }
+  // Concrete relative path: canonical resolution
+  return path.resolve(configDir, s).split(path.sep).join('/');
+};
+
+export const source = buildConfig.source.map(resolveSource);

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

@@ -0,0 +1,201 @@
+// build-tokens-src/formats/css.mjs
+// Registers the 'css/variables-sorted' format.
+// Generates a :root { ... } block with custom properties sorted alphabetically.
+// Typography tokens are exploded into multiple CSS properties:
+//   - a `font` shorthand (when both fontSize and fontFamily are present)
+//   - individual properties for letterSpacing, textTransform, textDecoration
+
+import StyleDictionary from 'style-dictionary';
+
+const BASE_FONT_SIZE = 16;
+
+// Converts a px value to rem. Returns the original string for non-px values.
+const toRem = (val) => {
+  if (val === undefined || val === null) return '0';
+  const str = String(val).trim();
+  const num = parseFloat(str);
+  if (isNaN(num) || num === 0) return num === 0 ? '0' : str;
+  if (str.endsWith('px')) return `${num / BASE_FONT_SIZE}rem`;
+  return str;
+};
+
+// Replaces {a.b.c} references with var(--token-name) using the tokenByPath map.
+const makeResolveRefs = (tokenByPath) => (str) =>
+  String(str).replace(/\{([^}]+)\}/g, (_, p) => {
+    const ref = tokenByPath[p];
+    return ref ? `var(--${ref.name})` : `{${p}}`;
+  });
+
+// ── Complex-type builders ────────────────────────────────────────────────────
+
+const buildShadow = (original, resolveRefs) => {
+  const shadows = Array.isArray(original) ? original : [original];
+  return shadows.map((s) => {
+    const offsetX = toRem(s.offsetX ?? s.x);
+    const offsetY = toRem(s.offsetY ?? s.y);
+    const blur    = toRem(s.blur);
+    const spread  = toRem(s.spread);
+    const color   = resolveRefs(s.color ?? 'transparent');
+    const inset   = s.inset ? 'inset ' : '';
+    return `${inset}${offsetX} ${offsetY} ${blur} ${spread} ${color}`;
+  }).join(', ');
+};
+
+const buildGradient = (original, resolveRefs) => {
+  const { type = 'linear', angle = 90, stops = [] } = original;
+  const stopsList = stops.map((s) => {
+    let color = resolveRefs(s.color ?? 'transparent');
+    if (s.alpha !== undefined) {
+      color = `color-mix(in srgb, ${color} ${s.alpha * 100}%, transparent)`;
+    }
+    const position = s.position !== undefined ? ` ${s.position * 100}%` : '';
+    return `${color}${position}`;
+  }).join(', ');
+
+  if (type === 'radial') return `radial-gradient(circle, ${stopsList})`;
+  if (type === 'conic')  return `conic-gradient(from ${angle}deg, ${stopsList})`;
+  return `linear-gradient(${angle}deg, ${stopsList})`;
+};
+
+const buildBorderLike = (original, resolveRefs) => {
+  const parts = [resolveRefs(String(original.width ?? '1px'))];
+  if (original.style !== undefined && original.style !== null && original.style !== '') {
+    parts.push(resolveRefs(String(original.style)));
+  }
+  parts.push(resolveRefs(String(original.color ?? 'transparent')));
+  return parts.join(' ');
+};
+
+const buildTransition = (original, resolveRefs) => [
+  resolveRefs(String(original.duration       ?? '0s')),
+  resolveRefs(String(original.timingFunction ?? 'ease')),
+  resolveRefs(String(original.delay          ?? '0s')),
+  resolveRefs(String(original.property       ?? 'all')),
+].join(' ');
+
+const buildAnimation = (original, resolveRefs) => [
+  resolveRefs(String(original.duration       ?? '0s')),
+  resolveRefs(String(original.timingFunction ?? 'ease')),
+  resolveRefs(String(original.delay          ?? '0s')),
+  resolveRefs(String(original.iterationCount ?? '1')),
+  resolveRefs(String(original.direction      ?? 'normal')),
+  resolveRefs(String(original.fillMode       ?? 'none')),
+  resolveRefs(String(original.playState      ?? 'running')),
+  resolveRefs(String(original.name           ?? 'none')),
+].join(' ');
+
+// Builds CSS custom properties for a typography token.
+// Produces a `font` shorthand when both fontSize and fontFamily are present,
+// plus separate properties for letterSpacing, textTransform and textDecoration.
+const buildTypography = (tokenName, original, resolveRefs) => {
+  const {
+    fontStyle, fontVariant, fontWeight, fontStretch,
+    fontSize, lineHeight, fontFamily,
+    letterSpacing, textTransform, textDecoration,
+  } = original;
+
+  const lines = [];
+
+  if (fontSize && fontFamily) {
+    const parts = [];
+    if (fontStyle)   parts.push(resolveRefs(String(fontStyle)));
+    if (fontVariant) parts.push(resolveRefs(String(fontVariant)));
+    if (fontWeight)  parts.push(resolveRefs(String(fontWeight)));
+    if (fontStretch) parts.push(resolveRefs(String(fontStretch)));
+
+    const sizeSlash = lineHeight
+      ? `${resolveRefs(String(fontSize))}/${resolveRefs(String(lineHeight))}`
+      : resolveRefs(String(fontSize));
+
+    parts.push(sizeSlash);
+    parts.push(resolveRefs(String(fontFamily)));
+    lines.push(`  --${tokenName}-font: ${parts.join(' ')};`);
+  }
+
+  const EXTRA_PROPS = {
+    letterSpacing:  ['letter-spacing',  letterSpacing],
+    textTransform:  ['text-transform',  textTransform],
+    textDecoration: ['text-decoration', textDecoration],
+    // Fallback: expose size/family individually if the shorthand could not be built
+    ...(!fontSize   ? { fontSize:   ['font-size',   original.fontSize]   } : {}),
+    ...(!fontFamily ? { fontFamily: ['font-family', original.fontFamily] } : {}),
+  };
+
+  for (const [, [cssProp, val]] of Object.entries(EXTRA_PROPS)) {
+    if (val !== undefined) {
+      lines.push(`  --${tokenName}-${cssProp}: ${resolveRefs(String(val))};`);
+    }
+  }
+
+  return lines.join('\n');
+};
+
+// ── Format registration ──────────────────────────────────────────────────────
+
+// Exported counter — read by build-tokens.mjs for the final log line
+export let customPropsCount = 0;
+
+StyleDictionary.registerFormat({
+  name: 'css/variables-sorted',
+  format: ({ dictionary, options }) => {
+    const selector = options.selector ?? ':root';
+
+    const tokenByPath = {};
+    for (const token of dictionary.allTokens) {
+      tokenByPath[token.path.join('.')] = token;
+    }
+
+    const resolveRefs = makeResolveRefs(tokenByPath);
+
+    const lines = dictionary.allTokens
+      .slice()
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .flatMap((token) => {
+        const type = token.$type ?? token.type;
+        const orig = token.original?.$value ?? token.original?.value;
+
+        if (type === 'typography') {
+          return [buildTypography(token.name, orig ?? {}, resolveRefs)];
+        }
+
+        let value;
+
+        if (type === 'shadow' && options.outputReferences) {
+          value = (typeof orig === 'string' && orig.startsWith('{'))
+            ? resolveRefs(orig) : buildShadow(orig, resolveRefs);
+
+        } else if (type === 'gradient' && options.outputReferences) {
+          value = (typeof orig === 'string' && orig.startsWith('{'))
+            ? resolveRefs(orig) : buildGradient(orig, resolveRefs);
+
+        } else if ((type === 'border' || type === 'outline') && options.outputReferences) {
+          value = (typeof orig === 'string' && orig.startsWith('{'))
+            ? resolveRefs(orig) : buildBorderLike(orig, resolveRefs);
+
+        } else if (type === 'transition' && options.outputReferences) {
+          value = (typeof orig === 'string' && orig.startsWith('{'))
+            ? resolveRefs(orig) : buildTransition(orig, resolveRefs);
+
+        } else if (type === 'animation' && options.outputReferences) {
+          value = (typeof orig === 'string' && orig.startsWith('{'))
+            ? resolveRefs(orig) : buildAnimation(orig, resolveRefs);
+
+        } else if (options.outputReferences && typeof orig === 'string' && orig.includes('{')) {
+          // Resolve {references} to var(--name). If arithmetic operators remain
+          // after substitution the value is a math expression and must be wrapped
+          // in calc() to produce valid CSS.
+          const resolved = resolveRefs(orig);
+          const isCalcNeeded = /[+\-*/]/.test(resolved.replace(/var\([^)]+\)/g, '0'));
+          value = isCalcNeeded ? `calc(${resolved})` : resolved;
+
+        } else {
+          value = String(token.$value ?? token.value);
+        }
+
+        return [`  --${token.name}: ${value};`];
+      });
+
+    customPropsCount = lines.length;
+    return `${selector} {\n${lines.join('\n')}\n}\n`;
+  },
+});

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

@@ -0,0 +1,262 @@
+// build-tokens-src/formats/penpot.mjs
+// Registers the 'json/penpot' format and exports buildPenpotFiles() 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).
+//
+// Output format is controlled by the penpotFormat 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
+//
+// ── Expression handling (penpotExpressions 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:
+//
+//   'keep'    (default) — write the expression as-is; Penpot or 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.
+//   '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
+//                         -> 16 * .25 = 4 -> "4px"). If evaluation fails the
+//                         original expression is kept with a warning.
+
+import StyleDictionary from 'style-dictionary';
+import path from 'path';
+
+// Disclaimer prepended to every generated file when penpotFormat is 'jsonc'
+const DISCLAIMER = [
+  '// -----------------------------------------------------------------------',
+  '// Generated file — do not edit manually.',
+  '// This file is produced by the design-token build pipeline.',
+  '// Source of truth: the token files in the project source directory.',
+  '// Re-generate with: node build-tokens.mjs --config <path/to/config>',
+  '// -----------------------------------------------------------------------',
+  '',
+].join('\n');
+
+// ── Expression helpers ────────────────────────────────────────────────────────
+
+// Returns true if the string contains a math expression — i.e. it has at least
+// one operator (+, -, *, /) outside of a token reference ({...}).
+const isExpression = (str) => {
+  if (typeof str !== 'string') return false;
+  // Strip token references, then check for operators
+  const stripped = str.replace(/\{[^}]+\}/g, '0');
+  return /[+\-*/]/.test(stripped);
+};
+
+// Builds a token lookup map (dot-path -> token) from the dictionary.
+const makeTokenMap = (dictionary) => {
+  const map = {};
+  for (const token of dictionary.allTokens) {
+    map[token.path.join('.')] = token;
+  }
+  return map;
+};
+
+// Resolves a dimension expression to a concrete value string (e.g. "4px").
+//
+// Strategy:
+//   1. Find the first {reference} in the expression.
+//   2. Look it up in the token map to obtain its resolved numeric value and unit.
+//   3. Replace ALL {references} in the expression with their numeric values.
+//   4. Evaluate the resulting arithmetic expression with Function().
+//   5. Reattach the unit from step 2.
+//
+// Returns null if resolution fails (caller falls back to the original string).
+const resolveExpression = (orig, tokenMap) => {
+  // Collect all {reference} keys in order of appearance
+  const refPattern = /\{([^}]+)\}/g;
+  const refs = [...orig.matchAll(refPattern)];
+  if (refs.length === 0) return null;
+
+  // Determine unit from the first referenced dimension token
+  const firstRef  = tokenMap[refs[0][1]];
+  if (!firstRef) return null;
+
+  const firstVal  = String(firstRef.$value ?? firstRef.value ?? '');
+  const unitMatch = firstVal.match(/[a-z%]+$/i);
+  const unit      = unitMatch ? unitMatch[0] : '';
+  const baseNum   = parseFloat(firstVal);
+  if (isNaN(baseNum)) return null;
+
+  // Replace every {ref} with its numeric value
+  let expr = orig;
+  for (const match of refs) {
+    const refKey = match[1];
+    const refToken = tokenMap[refKey];
+    if (!refToken) return null;
+    const refVal = parseFloat(String(refToken.$value ?? refToken.value ?? ''));
+    if (isNaN(refVal)) return null;
+    expr = expr.replace(match[0], String(refVal));
+  }
+
+  // Evaluate — only allow digits, whitespace and arithmetic operators
+  if (!/^[\d\s+\-*/.()]+$/.test(expr)) return null;
+
+  try {
+    // eslint-disable-next-line no-new-func
+    const result = Function(`"use strict"; return (${expr})`)();
+    if (typeof result !== 'number' || !isFinite(result)) return null;
+    // Round to a reasonable precision to avoid floating-point noise
+    const rounded = parseFloat(result.toPrecision(10));
+    return unit ? `${rounded}${unit}` : String(rounded);
+  } catch {
+    return null;
+  }
+};
+
+// Wraps a dimension expression in CSS calc(), leaving {references} intact.
+const toCalc = (orig) => `calc(${orig})`;
+
+// ── Format ───────────────────────────────────────────────────────────────────
+
+StyleDictionary.registerFormat({
+  name: 'json/penpot',
+  format: ({ dictionary, options }) => {
+    const root = {};
+    const expressionMode = options.penpotExpressions ?? 'keep'; // 'keep' | 'calc' | 'resolve'
+    const tokenMap = (expressionMode === 'resolve') ? makeTokenMap(dictionary) : null;
+
+    for (const token of dictionary.allTokens) {
+      // Rebuild the nested tree from the token path
+      let node = root;
+      for (let i = 0; i < token.path.length - 1; i++) {
+        const segment = token.path[i];
+        node[segment] = node[segment] ?? {};
+        node = node[segment];
+      }
+
+      const leafKey = token.path[token.path.length - 1];
+      const type    = token.$type ?? token.type;
+      const orig    = token.original?.$value ?? token.original?.value;
+
+      // ── Value resolution ────────────────────────────────────────────────────
+      let value;
+
+      if (
+        type === 'dimension' &&
+        typeof orig === 'string' &&
+        isExpression(orig)
+      ) {
+        // The original $value is a math expression
+        if (expressionMode === 'resolve') {
+          const resolved = resolveExpression(orig, tokenMap);
+          if (resolved !== null) {
+            value = resolved;
+          } else {
+            // Resolution failed — keep the original and emit a warning
+            console.warn(`[build-tokens] penpot: could not resolve expression "${orig}" for token "${token.path.join('.')}". Keeping original.`);
+            value = orig;
+          }
+        } else if (expressionMode === 'calc') {
+          // Replace {refs} with their alias notation and wrap in calc()
+          value = toCalc(orig);
+        } else {
+          // 'keep' — write the expression unchanged
+          value = orig;
+        }
+      } else {
+        // Non-expression value: preserve aliases for Penpot token links
+        const isAlias = typeof orig === 'string' && orig.startsWith('{') && !orig.includes(' ');
+        value = isAlias ? orig : (token.$value ?? token.value);
+      }
+
+      const entry = { $type: type, $value: value };
+
+      const desc = token.$description ?? token.description ?? token.comment;
+      if (desc) entry.$description = desc;
+
+      node[leafKey] = entry;
+    }
+
+    const body = JSON.stringify(root, null, 2) + '\n';
+    return options.jsonc ? DISCLAIMER + body : body;
+  },
+});
+
+// ── 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.
+// Must be called AFTER `await sd.hasInitialized`.
+
+export const collectConcreteFilePaths = async (sd) => {
+  await sd.hasInitialized;
+  const paths = new Set();
+  for (const token of sd.allTokens) {
+    if (token.filePath) paths.add(token.filePath);
+  }
+  return [...paths].sort();
+};
+
+// ── buildPenpotFiles ──────────────────────────────────────────────────────────
+//
+// @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
+// @returns {object[]}  File descriptors for the Style Dictionary platform
+
+export const buildPenpotFiles = (
+  concreteFilePaths,
+  penpotDestFile,
+  penpotFormat = 'json',
+  penpotExpressions = 'keep'
+) => {
+  const ext  = penpotFormat === 'jsonc' ? '.jsonc' : '.json';
+  const jsonc = penpotFormat === 'jsonc';
+
+  if (penpotDestFile) {
+    return [{
+      destination: penpotDestFile + ext,
+      format: 'json/penpot',
+      options: { jsonc, penpotExpressions },
+    }];
+  }
+
+  const sourceRoot = commonDir(concreteFilePaths);
+
+  return concreteFilePaths.map((filePath) => {
+    const absPath  = path.resolve(filePath);
+    const relPath  = path.relative(sourceRoot, absPath);
+    const destName = relPath.replace(/\.[^.]+$/, '') + ext;
+
+    return {
+      destination: destName,
+      format: 'json/penpot',
+      options: { jsonc, penpotExpressions },
+      filter: (token) => {
+        const fp = token.filePath ? path.resolve(token.filePath) : '';
+        return fp === absPath;
+      },
+    };
+  });
+};

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

@@ -0,0 +1,80 @@
+// 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().
+
+import { buildPenpotFiles } from './formats/penpot.mjs';
+
+// Transforms applied to the CSS platform
+const CSS_TRANSFORMS = [
+  'attribute/cti',
+  'name/kebab',
+  'time/seconds',
+  'asset/url',
+  'size/pxToRem-smart',
+  'color/css-modern',
+  'shadow/css',
+  'gradient/css',
+  'composite/css',
+  '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 = [
+  'attribute/cti',
+  'name/kebab',
+  'color/css-modern',
+];
+
+/**
+ * @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[]}        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.
+ * @returns {object} platforms object ready for Style Dictionary config
+ */
+export const buildPlatforms = ({
+  buildPath,
+  destFile,
+  penpotBuildPath,
+  penpotDestFile,
+  penpotFormat,
+  penpotExpressions = 'keep',
+  concreteFilePaths = [],
+}) => {
+  const platforms = {
+    css: {
+      buildPath: buildPath + '/',
+      transforms: CSS_TRANSFORMS,
+      files: [
+        {
+          destination: destFile,
+          format: 'css/variables-sorted',
+          options: {
+            outputReferences: true,
+            showFileHeader: true,
+          },
+        },
+      ],
+    },
+  };
+
+  if (penpotBuildPath) {
+    platforms.penpot = {
+      buildPath: penpotBuildPath + '/',
+      transforms: PENPOT_TRANSFORMS,
+      files: buildPenpotFiles(concreteFilePaths, penpotDestFile, penpotFormat, penpotExpressions),
+    };
+  }
+
+  return platforms;
+};