@massimo-cassandro/minimo 1.34.0 → 1.35.0

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)
 

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
@@ -81,6 +82,7 @@ export const buildSourceModes = async ({
   for (const mode of modeNames) {
     const sd = new StyleDictionary({
       source: sourceModes[mode],
+      parsers: [LEGACY_TOKENS_PARSER_NAME],
       log: { verbosity: 'verbose' },
       platforms: {
         css: {
@@ -115,6 +117,7 @@ export const buildSourceModes = async ({
 
       const jsonSd = new StyleDictionary({
         source: sourceModes[mode],
+        parsers: [LEGACY_TOKENS_PARSER_NAME],
         log: { verbosity: 'silent' },
         platforms: {
           json: {

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);
@@ -208,6 +211,7 @@ async function run() {
       try {
         const sd = new StyleDictionary({
           source: resolvedPaths,
+          parsers: [LEGACY_TOKENS_PARSER_NAME],
           log: { verbosity: 'silent' },
           platforms: { css: { transforms: CSS_TRANSFORMS } },
         });

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}',

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.0",
   "description": "Light css framework & utilities",
   "type": "module",
   "main": "./index.js",