@massimo-cassandro/minimo 1.34.0 → 1.35.1

package/dev-tools/design-tokens-builder/README.md

@@ -66,6 +66,10 @@ The `source` array accepts any combination of:
 - `.json` / `.jsonc` — parsed directly as token data
 - `.mjs` / `.js` — imported as ES modules; must export a W3C DTCG-compliant object as `default`
 
+**Legacy token syntax (auto-detected, `.json` only):** `.json` source files written in the older, non-DTCG Style Dictionary syntax (`value`/`type` instead of `$value`/`$type`, references as `{group.token.value}` instead of `{group.token}` — e.g. a file exported from [Open Props](https://open-props.style/)) are converted to DTCG v5 syntax automatically at parse time, node by node. Files already using `$value`/`$type` are left untouched, so no config flag or file list is needed — mixing legacy and DTCG sources in the same `source` array just works. `.jsonc` is not covered (reserved for hand-authored DTCG sources, parsed by Style Dictionary's own loader) and these `.json` files are parsed with plain `JSON.parse` (no comments, no trailing commas). See `build-tokens-src/legacy-tokens-parser.mjs`.
+
+Known limitation: a legacy node that is at the same time a token (own `value`/`type`) *and* a group with further nested children (e.g. Open Props' `other.ease.out`, which has its own value plus `out.1` ... `out.5`) can't be represented in DTCG v5 — a node with `$value` is always a leaf, Style Dictionary doesn't descend into its children. Only the node's own value is converted; the nested children are silently lost.
+
 
 #### Token file format (JS example)
 
@@ -157,6 +161,8 @@ When set, each mode has its own `source` array, and the generated CSS composes a
 - the base mode's props go in a top-level `:root { ... }` block, with `color-scheme: <all modes>;` prepended
 - every other mode's props go in `@media (prefers-color-scheme: <mode>) { :root { ... } }`, with `color-scheme: <mode>;` prepended
 
+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, output as `var(--color-1)`). References to a non-base mode's tokens (from the base mode or from another non-base mode) fail with a "reference not defined" error, since the target would be undefined outside its own `@media` block.
+
 `customPropsGroups`, `mergeCustomProps`, `addLayer`, `pxToRem` etc. all apply the same way as with a single `source`. The JSON output (when `jsonBuildPath` is set) is produced once per mode, with the mode name appended to each filename (e.g. `tokens-light.jsonc` / `tokens-dark.jsonc`).
 
 ---

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

@@ -29,6 +29,7 @@ import { CSS_TRANSFORMS, JSON_TRANSFORMS } from './platforms.mjs';
 import { customPropsCount } from './formats/css.mjs';
 import { buildJsonFiles, collectConcreteFilePaths } from './formats/json.mjs';
 import { loadExistingCustomPropsScoped } from './merge-css.mjs';
+import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
 
 /**
  * @param {object}                 opts
@@ -79,8 +80,18 @@ 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 `:root`). 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.
+    const include = mode === baseMode ? [] : sourceModes[baseMode];
+
     const sd = new StyleDictionary({
+      include,
       source: sourceModes[mode],
+      parsers: [LEGACY_TOKENS_PARSER_NAME],
       log: { verbosity: 'verbose' },
       platforms: {
         css: {
@@ -114,7 +125,9 @@ export const buildSourceModes = async ({
       const files = buildJsonFiles(concreteFilePaths, jsonDestFile, jsonFormat, jsonExpression, `-${mode}`);
 
       const jsonSd = new StyleDictionary({
+        include,
         source: sourceModes[mode],
+        parsers: [LEGACY_TOKENS_PARSER_NAME],
         log: { verbosity: 'silent' },
         platforms: {
           json: {

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

@@ -189,8 +189,11 @@ StyleDictionary.registerFormat({
       return a.name.localeCompare(b.name, 'en', { numeric: true, sensitivity: 'base' });
     };
 
+    // Tokens loaded via `include` (sourceModes: base-mode tokens made
+    // available to other modes) stay in tokenByPath, so references to them
+    // resolve to var(--name), but are not declared in this mode's block.
     const lines = dictionary.allTokens
-      .slice()
+      .filter((token) => token.isSource !== false)
       // .sort((a, b) => a.name.localeCompare(b.name, 'en', {numeric: true, sensitivity: 'base'}))
       .sort((a, b) => sortFunction(a,b))
       .flatMap((token) => {
@@ -247,6 +250,15 @@ StyleDictionary.registerFormat({
           value = String(token.$value ?? token.value);
         }
 
+        // Multi-line values (e.g. Open Props' linear() easings) are collapsed
+        // to a single line: declarations are parsed one line at a time (see
+        // parseCustomProps in ../merge-css.mjs), so a multi-line value would
+        // be truncated to its first line.
+        value = String(value)
+          .replace(/\s*\n\s*/g, ' ')
+          .replace(/\(\s+/g, '(')
+          .replace(/\s+\)/g, ')');
+
         return [`  --${token.name}: ${value};${commentSuffix}`];
       });
 

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

@@ -136,6 +136,10 @@ StyleDictionary.registerFormat({
     const tokenMap = (expressionMode === 'resolve') ? makeTokenMap(dictionary) : null;
 
     for (const token of dictionary.allTokens) {
+      // Tokens loaded via `include` (sourceModes: base-mode tokens made
+      // available to other modes for reference resolution) are not output.
+      if (token.isSource === false) continue;
+
       // Rebuild the nested tree from the token path
       let node = root;
       for (let i = 0; i < token.path.length - 1; i++) {
@@ -205,7 +209,7 @@ 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);
+    if (token.filePath && token.isSource !== false) paths.add(token.filePath);
   }
   return [...paths].sort();
 };

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

@@ -0,0 +1,105 @@
+// build-tokens-src/legacy-tokens-parser.mjs
+// Registers a Style Dictionary parser that bridges "legacy" token files
+// (Style Dictionary v3/v4-style syntax: no `$` prefix on `value`/`type`,
+// references written as `{group.token.value}`) into the W3C DTCG syntax
+// (`$value`/`$type`, references as `{group.token}`) required by Style
+// Dictionary v5.
+//
+// Why this is needed: Style Dictionary v5 decides whether a build "usesDtcg"
+// ONCE per build, from whichever source file is processed first (see
+// detectDtcgSyntax() called inside combineJSON.js in style-dictionary) — it
+// is a single global flag, not a per-file check. Mixing a legacy-syntax file
+// (e.g. a file exported from Open Props, or from an old Style Dictionary
+// v3/v4 project) together with DTCG sources therefore causes the legacy
+// file's tokens to be silently dropped regardless of file order: they never
+// carry the `$value` key combineJSON's own tagging (and the rest of the
+// pipeline) expects.
+//
+// This parser intercepts every `.json` source file (not `.jsonc` — that
+// extension is reserved in this project for hand-authored DTCG sources,
+// already handled correctly by Style Dictionary's own built-in loader) and
+// converts, node by node:
+//   value -> $value, type -> $type, comment/description -> $description
+//   "{group.token.value}" -> "{group.token}" inside reference strings
+// Nodes that already use `$value` (DTCG v5 syntax) are left untouched, so
+// the parser is a safe no-op for files that don't need conversion — no
+// config flag or file list is required, detection is fully automatic.
+//
+// Limitation: `.json` files handled by this parser are parsed with plain
+// JSON.parse (no comments, no trailing commas), unlike Style Dictionary's
+// own built-in loader (which uses JSON5 for .json/.jsonc/.json5). This keeps
+// the builder dependency-free — legacy token exports (Open Props, old Style
+// Dictionary v3/v4 projects) are virtually always strict JSON anyway. Use
+// `.jsonc` or `.mjs` for hand-authored DTCG sources that need comments.
+
+import StyleDictionary from 'style-dictionary';
+
+export const LEGACY_TOKENS_PARSER_NAME = 'minimo/legacy-tokens';
+
+// Matches "{some.token.path.value}" -> captures "some.token.path"
+const LEGACY_REF = /\{([^}]+)\.value\}/g;
+
+/** @param {unknown} value @returns {unknown} */
+const convertLegacyRefs = (value) => {
+  if (typeof value === 'string') {
+    return value.replace(LEGACY_REF, '{$1}');
+  }
+  if (Array.isArray(value)) {
+    return value.map(convertLegacyRefs);
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, v]) => [key, convertLegacyRefs(v)])
+    );
+  }
+  return value;
+};
+
+/** @param {unknown} node @returns {node is Record<string, unknown>} */
+const isPlainObject = (node) => node !== null && typeof node === 'object' && !Array.isArray(node);
+
+/** @param {unknown} node @returns {unknown} */
+const convertLegacyNode = (node) => {
+  if (!isPlainObject(node)) return node;
+
+  // Already DTCG v5 syntax: leave untouched.
+  if (Object.hasOwn(node, '$value')) return node;
+
+  if (Object.hasOwn(node, 'value')) {
+    // Legacy token leaf. Some legacy files (e.g. Open Props) also attach
+    // sibling numbered/named children to a node that carries its own
+    // `value`/`type` (a group that is also a default token) — those
+    // children are converted too, even though Style Dictionary itself
+    // cannot represent "group + own $value" ambiguity natively.
+    const { value, type, comment, description, ...rest } = node;
+    const convertedRest = Object.fromEntries(
+      Object.entries(rest).map(([key, child]) => [key, convertLegacyNode(child)])
+    );
+    const desc = comment ?? description;
+
+    return {
+      ...convertedRest,
+      $value: convertLegacyRefs(value),
+      ...(type !== undefined ? { $type: type } : {}),
+      ...(desc !== undefined ? { $description: desc } : {}),
+    };
+  }
+
+  // Group node: recurse into children.
+  return Object.fromEntries(
+    Object.entries(node).map(([key, child]) => [key, convertLegacyNode(child)])
+  );
+};
+
+// Registers the parser globally on the StyleDictionary class. To actually
+// run it, a Style Dictionary instance must also opt in via
+// `parsers: [LEGACY_TOKENS_PARSER_NAME]` in its config (registering alone
+// does not activate it for every instance — see Style Dictionary's parser
+// hooks docs).
+export const registerLegacyTokensParser = () => {
+  StyleDictionary.registerParser({
+    name: LEGACY_TOKENS_PARSER_NAME,
+    pattern: /\.json$/,
+    parser: ({ contents }) => convertLegacyNode(JSON.parse(contents)),
+  });
+};

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

@@ -44,6 +44,12 @@ import {
 // ── 2. Custom transforms ─────────────────────────────────────────────────────
 import './build-tokens-src/transforms.mjs';
 
+// ── 2b. Legacy token syntax bridge ───────────────────────────────────────────
+// Converts legacy (non-DTCG, e.g. Open Props) .json/.jsonc source files to
+// DTCG v5 syntax at parse time — see build-tokens-src/legacy-tokens-parser.mjs.
+import { LEGACY_TOKENS_PARSER_NAME, registerLegacyTokensParser } from './build-tokens-src/legacy-tokens-parser.mjs';
+registerLegacyTokensParser();
+
 // ── 3. CSS format ─────────────────────────────────────────────────────────────
 // customPropsCount is updated by the format at render time
 // loadExistingCustomProps supports the mergeCustomProps option (see below)
@@ -127,12 +133,18 @@ if (sourceModes) {
   const singleSource = /** @type {string[]} */ (source);
 
   if (jsonBuildPath && !jsonDestFile) {
-    const sdInit = new StyleDictionary({ source: singleSource, log: { verbosity: 'silent' }, platforms: {} });
+    const sdInit = new StyleDictionary({
+      source: singleSource,
+      parsers: [LEGACY_TOKENS_PARSER_NAME],
+      log: { verbosity: 'silent' },
+      platforms: {},
+    });
     concreteFilePaths = await collectConcreteFilePaths(sdInit);
   }
 
   const sd = new StyleDictionary({
     source: singleSource,
+    parsers: [LEGACY_TOKENS_PARSER_NAME],
     log: { verbosity: 'verbose' },
     platforms: buildPlatforms({
       buildPath,

package/dev-tools/design-tokens-builder/check-unresolved-custom-props.mjs

@@ -26,6 +26,9 @@ import './build-tokens-src/transforms.mjs';
 import { CSS_TRANSFORMS } from './build-tokens-src/platforms.mjs';
 import { resolveSourcePaths } from './build-tokens-src/resolve-source-paths.mjs';
 import { findMediaModeBlocks } from './build-tokens-src/merge-css.mjs';
+import { LEGACY_TOKENS_PARSER_NAME, registerLegacyTokensParser } from './build-tokens-src/legacy-tokens-parser.mjs';
+
+registerLegacyTokensParser();
 
 // const __filename = fileURLToPath(import.meta.url);
 // const __dirname  = dirname(__filename);
@@ -199,21 +202,25 @@ async function run() {
     /** @type {Map<string, Map<string, string>>} */
     const sourceFileByPropByMode = new Map();
 
-    /** @param {string[]} sourcePatterns @returns {Promise<Map<string,string>>} */
-    const resolveSourceFileMap = async (sourcePatterns) => {
+    // includePatterns: base-mode sources, passed as `include` for non-base
+    // modes so cross-mode references resolve (same as build-source-modes.mjs).
+    /** @param {string[]} sourcePatterns @param {string[]} [includePatterns] @returns {Promise<Map<string,string>>} */
+    const resolveSourceFileMap = async (sourcePatterns, includePatterns = []) => {
       /** @type {Map<string, string>} */
       const map = new Map();
       const resolvedPaths = resolveSourcePaths(sourcePatterns, configDir);
       if (!resolvedPaths.length) return map;
       try {
         const sd = new StyleDictionary({
+          include: resolveSourcePaths(includePatterns, configDir),
           source: resolvedPaths,
+          parsers: [LEGACY_TOKENS_PARSER_NAME],
           log: { verbosity: 'silent' },
           platforms: { css: { transforms: CSS_TRANSFORMS } },
         });
         const dictionary = await sd.getPlatformTokens('css');
         for (const token of dictionary.allTokens) {
-          if (token.filePath) map.set(`--${token.name}`, token.filePath);
+          if (token.filePath && token.isSource !== false) map.set(`--${token.name}`, token.filePath);
         }
       } catch {
         // Non-fatal: unused properties will be reported by name only.
@@ -223,7 +230,8 @@ async function run() {
 
     if (checkUnused && config.sourceModes) {
       for (const [mode, modeSource] of Object.entries(config.sourceModes)) {
-        sourceFileByPropByMode.set(mode, await resolveSourceFileMap(modeSource));
+        const includePatterns = mode === sourceModesBase ? [] : config.sourceModes[sourceModesBase];
+        sourceFileByPropByMode.set(mode, await resolveSourceFileMap(modeSource, includePatterns));
       }
     } else if (checkUnused && Array.isArray(config.source) && config.source.length) {
       const map = await resolveSourceFileMap(config.source);

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

@@ -13,7 +13,8 @@
 
 
 // minimo package path in node_modules
-const minimo_path = '../../node_modules/@massimo-cassandro/minimo';
+const node_modules_path = '../../node_modules',
+  minimo_path = `${node_modules_path}/@massimo-cassandro/minimo`;
 
 const config = {
 
@@ -33,6 +34,19 @@ const config = {
   // 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).
+  //
+  // LIMITATION: a legacy node that is at the same time a token (own
+  // value/type) AND a group with further 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, Style
+  // Dictionary does not descend into its children. In that case only the
+  // node's own value is converted; the nested children are silently lost.
+  //
   // 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}`
@@ -42,7 +56,7 @@ const config = {
     `${minimo_path}/src/**/*.tokens.{mjs,jsonc}`, // components tokens
 
     // optional extra token source (in this example, openProps, https://open-props.style/)
-    // '../../node_modules/open-props/open-props.style-dictionary-tokens.json',
+    // `${node_modules_path}/open-props/open-props.style-dictionary-tokens.json`,
 
     // your project tokens
     './project-tokens/*.{js,mjs,jsonc,json}',
@@ -63,6 +77,13 @@ const config = {
   // 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".

package/dev-tools/starter-kit/source_files/root/__project__.code-workspace

@@ -37,6 +37,10 @@
       {
         "filePath": "node_modules/open-props",
         "group": "Default"
+      },
+      {
+        "filePath": "node_modules/open-props/open-props.style-dictionary-tokens.json",
+        "group": "Default"
       }
     ],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massimo-cassandro/minimo",
-  "version": "1.34.0",
+  "version": "1.35.1",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",