@massimo-cassandro/minimo 0.3.6 → 0.4.0

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

@@ -0,0 +1,200 @@
+// build-tokens-src/transforms.mjs
+// Registers all custom Style Dictionary transforms.
+// Imported once by build-tokens.mjs before buildAllPlatforms() is called.
+
+import StyleDictionary from 'style-dictionary';
+
+const BASE_FONT_SIZE = 16;
+
+// Converts a px value to rem. Returns the original string unchanged for
+// non-px values, and '0' for zero values regardless of unit.
+const toRem = (val) => {
+  if (val === undefined || val === null) return '0';
+  const str = String(val).trim();
+  const num = parseFloat(str);
+  if (isNaN(num)) return str;
+  if (num === 0) return '0';
+  if (str.endsWith('px')) return `${num / BASE_FONT_SIZE}rem`;
+  return str;
+};
+
+// ---------------------------------------------------------------------------
+// 1. Shadow
+// Converts shadow token objects (single or array) to a CSS box-shadow string.
+// px values are converted to rem. Alias references are resolved transitively.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'shadow/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'shadow' || token.type === 'shadow',
+  transform: (token) => {
+    const original = token.original?.$value ?? token.original?.value;
+
+    const value = (typeof original === 'string' && original.startsWith('{'))
+      ? (token.$value ?? token.value)
+      : (original ?? token.$value ?? token.value);
+
+    const shadows = Array.isArray(value) ? value : [value];
+
+    // Already a resolved CSS string (e.g. from an alias)
+    if (shadows.length === 1 && typeof shadows[0] === 'string') return shadows[0];
+
+    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   = s.color ?? 'transparent';
+        const inset   = s.inset ? 'inset ' : '';
+        return `${inset}${offsetX} ${offsetY} ${blur} ${spread} ${color}`;
+      })
+      .join(', ');
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 2. px → rem (dimension tokens only, skips values already in rem)
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'size/pxToRem-smart',
+  type: 'value',
+  filter: (token) => {
+    const value = token.$value || token.value;
+    return (token.$type === 'dimension' || token.type === 'dimension')
+      && typeof value === 'string'
+      && !value.endsWith('rem');
+  },
+  transform: (token) => {
+    const value      = token.$value || token.value;
+    const floatValue = parseFloat(value);
+    if (isNaN(floatValue)) return value;
+    return `${floatValue / BASE_FONT_SIZE}rem`;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 3. Color passthrough
+// Ensures the resolved value is returned as-is, supporting both $value and
+// legacy value fields and transitive alias resolution.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'color/css-modern',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'color' || token.type === 'color',
+  transform: (token) => token.$value ?? token.value,
+});
+
+// ---------------------------------------------------------------------------
+// 4. Gradient
+// Converts gradient token objects to CSS gradient functions.
+// Supports linear, radial and conic types. Alias references are resolved
+// transitively; already-resolved strings are returned unchanged.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'gradient/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'gradient' || token.type === 'gradient',
+  transform: (token) => {
+    const original = token.original?.$value ?? token.original?.value;
+
+    const value = (typeof original === 'string' && original.startsWith('{'))
+      ? (token.$value ?? token.value)
+      : (original ?? token.$value ?? token.value);
+
+    if (typeof value === 'string') return value;
+
+    const { type = 'linear', angle = 90, stops = [] } = value;
+
+    const stopsList = stops
+      .map((s) => {
+        let color = 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 === 'linear') return `linear-gradient(${angle}deg, ${stopsList})`;
+    if (type === 'radial') return `radial-gradient(circle, ${stopsList})`;
+    if (type === 'conic')  return `conic-gradient(from ${angle}deg, ${stopsList})`;
+
+    return `linear-gradient(${angle}${typeof angle === 'number' ? 'deg' : ''}, ${stopsList})`;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 5. Composite (border, outline, transition, animation)
+// Converts composite token objects to their CSS shorthand equivalents.
+// Only applied to object values; strings pass through unchanged.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'composite/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => {
+    const type  = token.$type ?? token.type;
+    const value = token.$value ?? token.value;
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      !Array.isArray(value) &&
+      ['border', 'outline', 'transition', 'animation'].includes(type)
+    );
+  },
+  transform: (token) => {
+    const type = token.$type ?? token.type;
+    const v    = token.$value ?? token.value;
+
+    if (type === 'border') {
+      const parts = [v.width ?? '1px'];
+      if (v.style !== undefined && v.style !== null && v.style !== '') parts.push(v.style);
+      parts.push(v.color ?? 'transparent');
+      return parts.join(' ');
+    }
+
+    if (type === 'outline') {
+      return `${v.width ?? '1px'} ${v.style ?? 'solid'} ${v.color ?? 'transparent'}`;
+    }
+
+    if (type === 'transition') {
+      return [
+        v.duration       ?? '0s',
+        v.timingFunction ?? 'ease',
+        v.delay          ?? '0s',
+        v.property       ?? 'all',
+      ].join(' ');
+    }
+
+    if (type === 'animation') {
+      return [
+        v.duration       ?? '0s',
+        v.timingFunction ?? 'ease',
+        v.delay          ?? '0s',
+        v.iterationCount ?? '1',
+        v.direction      ?? 'normal',
+        v.fillMode       ?? 'none',
+        v.playState      ?? 'running',
+        v.name           ?? 'none',
+      ].join(' ');
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 6. Typography passthrough
+// Returns the token value as-is. The css/variables-sorted format is
+// responsible for exploding typography tokens into individual CSS properties.
+// ---------------------------------------------------------------------------
+StyleDictionary.registerTransform({
+  name: 'typography/css',
+  type: 'value',
+  transitive: true,
+  filter: (token) => token.$type === 'typography' || token.type === 'typography',
+  transform: (token) => token.$value ?? token.value,
+});

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

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+// build-tokens.mjs
+// Entry point: imports modules, runs the build, lints the CSS output, prints the log.
+//
+// Project structure:
+//   build-tokens.mjs              <- this file
+//   build-tokens-src/config.mjs   <- reads --config flag and resolves all paths
+//   build-tokens-src/transforms.mjs  <- registers custom Style Dictionary transforms
+//   build-tokens-src/formats/css.mjs    <- registers the css/variables-sorted format
+//   build-tokens-src/formats/penpot.mjs <- registers the json/penpot format, exports helpers
+//   build-tokens-src/platforms.mjs      <- builds the platforms object (css + optional penpot)
+
+import StyleDictionary from 'style-dictionary';
+import path from 'path';
+import { styleText } from 'node:util';
+import { homedir } from 'os';
+import stylelint from 'stylelint';
+import { pathToFileURL } from 'url';
+
+// ── 1. Configuration (args + resolved paths) ────────────────────────────────
+import {
+  configAbsPath,
+  buildPath,
+  destFile,
+  stylelintConfigPath,
+  penpotBuildPath,
+  penpotDestFile,
+  penpotFormat,
+  penpotExpressions,
+  source,
+} from './build-tokens-src/config.mjs';
+
+// ── 2. Custom transforms ─────────────────────────────────────────────────────
+import './build-tokens-src/transforms.mjs';
+
+// ── 3. CSS format ─────────────────────────────────────────────────────────────
+// customPropsCount is updated by the format at render time
+import { customPropsCount } from './build-tokens-src/formats/css.mjs';
+
+// ── 4. Penpot format ──────────────────────────────────────────────────────────
+import { buildPenpotFiles, collectConcreteFilePaths } from './build-tokens-src/formats/penpot.mjs';
+
+// ── 5. Platforms builder ──────────────────────────────────────────────────────
+import { buildPlatforms } from './build-tokens-src/platforms.mjs';
+
+// ── 6. Collect concrete source file paths (multi-file Penpot mode only) ──────
+// Source entries may be glob patterns. SD expands them internally and stores
+// the concrete path in token.filePath. We need those concrete paths to build
+// the per-file descriptors for the penpot platform.
+//
+// SD v5 lazy-loads sources: `await sd.hasInitialized` triggers loading;
+// after that sd.allTokens is a plain synchronous array with filePath populated.
+//
+// In single-file mode (penpotDestFile is set) we skip this step entirely.
+let concreteFilePaths = [];
+
+if (penpotBuildPath && !penpotDestFile) {
+  const sdInit = new StyleDictionary({ source, log: { verbosity: 'silent' }, platforms: {} });
+  concreteFilePaths = await collectConcreteFilePaths(sdInit);
+}
+
+// ── 7. Build ──────────────────────────────────────────────────────────────────
+const sd = new StyleDictionary({
+  source,
+  log: { verbosity: 'verbose' },
+  platforms: buildPlatforms({
+    buildPath,
+    destFile,
+    penpotBuildPath,
+    penpotDestFile,
+    penpotFormat,
+    penpotExpressions,
+    concreteFilePaths,
+  }),
+});
+
+await sd.buildAllPlatforms();
+
+// ── 8. CSS lint ───────────────────────────────────────────────────────────────
+const stylelintConfig = await import(pathToFileURL(stylelintConfigPath)).then(m => m.default);
+
+await stylelint.lint({
+  config: stylelintConfig,
+  files: [path.join(buildPath, destFile)],
+  fix: true,
+});
+
+// ── 9. Log ────────────────────────────────────────────────────────────────────
+const short = (p) => p.replace(homedir(), '~');
+
+console.log(styleText(['yellow'], `[build-tokens] config file : ${short(configAbsPath)}`));
+console.log(styleText(['yellow'], `[build-tokens] source      : ${source.map(short)}`));
+console.log(styleText(['yellow'], `[build-tokens] dest file   : ${short(path.join(buildPath, destFile))}`));
+
+if (penpotBuildPath) {
+  const penpotFiles = buildPenpotFiles(concreteFilePaths, penpotDestFile, penpotFormat, penpotExpressions);
+  if (penpotFiles.length === 1) {
+    console.log(styleText(['yellow'],
+      `[build-tokens] penpot json : ${short(path.join(penpotBuildPath, penpotFiles[0].destination))}`
+    ));
+  } else {
+    console.log(styleText(['yellow'],
+      `[build-tokens] penpot json : ${penpotFiles.length} files in ${short(penpotBuildPath)}`
+    ));
+  }
+} else {
+  console.log(styleText(['yellow'],
+    `[build-tokens] penpot json : (disabled — penpotBuildPath not set)`
+  ));
+}
+
+console.log(styleText(['green'], `[build-tokens] ${customPropsCount} custom properties processed`));
+console.log(styleText(['green'], '**** DONE ****'));

package/design-tokens-utilities/check-unresolved-custom-props.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-console */
+
+// check-unresolved-custom-props.mjs
+// Scans CSS files in the configured directory and reports any custom property
+// references (var(--...)) that are not defined in the generated token file.
+//
+// Usage: node check-unresolved-custom-props.mjs --config ./path/to/config.mjs
+
+import path from 'path';
+import fs from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname } from 'path';
+import { glob } from 'node:fs/promises';
+import { styleText, parseArgs } from 'node:util';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// 1. Parse flags
+// ---------------------------------------------------------------------------
+const options = {
+  config: {
+    type: 'string',
+    short: 'c',
+  },
+};
+
+const { values } = parseArgs({ options });
+
+if (!values.config) {
+  console.error(styleText(['red'], 'Error: you must provide the config path with --config or -c'));
+  console.log('Example: node check-unresolved-custom-props.mjs --config ./config.mjs');
+  process.exit(1);
+}
+
+const absoluteConfigPath = path.resolve(process.cwd(), values.config);
+const configDir = path.dirname(absoluteConfigPath);
+
+// ---------------------------------------------------------------------------
+// 2. Main
+// ---------------------------------------------------------------------------
+async function run() {
+  try {
+    const { default: config } = await import(pathToFileURL(absoluteConfigPath).href);
+
+    // Path of the generated CSS file containing all custom property definitions
+    const custom_prop_file_path = path.resolve(configDir, path.join(config.buildPath, config.destFile));
+    const custom_prop_filename  = path.basename(custom_prop_file_path);
+
+    // Directory to scan for CSS files
+    const checkdir = path.resolve(configDir, config.dir_to_check);
+
+    // Patterns for custom properties to exclude from the unresolved check
+    const exclude = config.exclude_pattern ?? [];
+
+    // Collect all .css files in the scan directory, excluding the token file itself
+    const files = [];
+    for await (const entry of glob(path.join(checkdir, '/**/*.css'))) {
+      if (!entry.endsWith(custom_prop_filename)) {
+        files.push(entry);
+      }
+    }
+
+    if (!fs.existsSync(custom_prop_file_path)) {
+      throw new Error(`Token CSS file not found: ${custom_prop_file_path}`);
+    }
+
+    // ---------------------------------------------------------------------------
+    // 3. Build the list of defined custom properties
+    // ---------------------------------------------------------------------------
+    const cssContent = fs.readFileSync(custom_prop_file_path, 'utf-8');
+    const definitionRegex = /--([a-z0-9-]+)(?=\s*:)/g;
+    const propertyNamesList = [...cssContent.matchAll(definitionRegex)].map(m => `--${m[1]}`);
+
+    // Also include any extra CSS files declared in extra_custom_props_files
+    for (const extraFile of (config.extra_custom_props_files ?? [])) {
+      const extraContent = fs.readFileSync(path.resolve(configDir, extraFile), 'utf-8');
+      const extraMatches = [...extraContent.matchAll(definitionRegex)].map(m => `--${m[1]}`);
+      propertyNamesList.push(...extraMatches);
+    }
+
+    // ---------------------------------------------------------------------------
+    // 4. Scan files for unresolved var() references
+    // ---------------------------------------------------------------------------
+    const usageRegex = /var\(\s*(--[a-z0-9-]+)\s*(,.*?)?\)/g;
+    const unresolved_props = [];
+
+    files.forEach(file => {
+      const fileContent = fs.readFileSync(file, 'utf-8');
+      const filename    = path.relative(configDir, file);
+      const matches     = [...fileContent.matchAll(usageRegex)];
+
+      matches.forEach(match => {
+        const cprop      = match[1];
+        const isExcluded = exclude.some(exRegex => exRegex.test(cprop));
+        const isDefined  = propertyNamesList.includes(cprop);
+        const lineNumber = fileContent.substring(0, match.index).split('\n').length;
+
+        if (!isExcluded && !isDefined) {
+          unresolved_props.push({ file: filename, line: lineNumber, prop: cprop });
+        }
+      });
+    });
+
+    unresolved_props.sort((a, b) => a.file.localeCompare(b.file));
+
+    // ---------------------------------------------------------------------------
+    // 5. Write the report
+    // ---------------------------------------------------------------------------
+    const result_file = path.resolve(configDir, 'unresolved-props.md');
+
+    console.log(styleText(['green'],
+      `${unresolved_props.length} unresolved custom properties found -> ${path.relative(process.cwd(), result_file)}`
+    ));
+
+    fs.writeFileSync(
+      result_file,
+      unresolved_props
+        .map(item =>
+          `* [${path.basename(item.file)} :: ${item.line}](${item.file}#L${item.line}) -> var(${item.prop})`
+        )
+        .join('\n'),
+      'utf-8'
+    );
+
+    console.log(styleText(['green'], '**** DONE ****'));
+
+  } catch (err) {
+    console.log(styleText(['redBright'], err.stack));
+    process.exit(1);
+  }
+}
+
+run();

package/design-tokens-utilities/readme.md

@@ -0,0 +1,185 @@
+# Design Token Utilities
+
+A set of Node.js scripts for managing CSS design tokens in a project. Built on top of [Style Dictionary v5](https://styledictionary.com/).
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `build-tokens.mjs` | Generates a CSS custom properties file from design token source files |
+| `check-unresolved-custom-props.mjs` | Scans CSS files and reports any `var(--...)` references not found in the generated token file |
+
+Both scripts share the same config file, passed via `--config`.
+
+## Setup
+
+The scripts are intended to be used as npm scripts. Add them to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build tokens": "npx buildTokens --config ./path/to/tokens-config.mjs",
+    "check unresolved props": "npx checkUnresolvedProps --config ./path/to/tokens-config.mjs"
+  }
+}
+```
+
+### Dependencies
+
+The following packages must be present in your project:
+
+```json
+{
+  "style-dictionary": "^5",
+  "stylelint": "^16"
+}
+```
+
+## Configuration file
+
+Both scripts read a shared config file passed with `--config`. Use `tokens-config-sample.mjs` as a starting point.
+
+Read comments inside the sample file for more info.
+
+
+## `build-tokens.mjs`
+
+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).
+
+### Usage
+
+```sh
+npx buildTokens --config ./path/to/tokens-config.mjs
+```
+
+### Source files
+
+The `source` array accepts any combination of:
+- Concrete file paths: `'./tokens/colors.jsonc'`
+- Glob patterns: `'./tokens/**/*.{json,jsonc,mjs}'`
+
+**Supported formats:**
+- `.json` / `.jsonc` — parsed directly as token data
+- `.mjs` / `.js` — imported as ES modules; must export a W3C DTCG-compliant object as `default`
+
+
+### Token file format (JS example)
+
+When using `.mjs` source files, export a default object following the [W3C Design Token Community Group format](https://design-tokens.github.io/community-group/format/):
+
+```js
+// colors.tokens.mjs
+export default {
+  color: {
+    brand: {
+      primary: { $type: 'color', $value: '#0057FF' },
+      secondary: { $type: 'color', $value: '#FF6B00' },
+    },
+    neutral: {
+      '100': { $type: 'color', $value: '#F5F5F5' },
+      '900': { $type: 'color', $value: '#1A1A1A' },
+    },
+  },
+  semantic: {
+    color: {
+      text: {
+        primary: { $type: 'color', $value: '{color.neutral.900}' }, // alias
+      },
+    },
+  },
+};
+```
+
+The main advantage of `.mjs` over `.json` is the ability to use JavaScript variables, comments, and computed values within the token definition.
+
+Values can be expressions like `"{size.base} * .25"`, see `tokens-config-sample.mjs` for more info.
+
+### Custom transforms
+
+The following transforms are registered on top of Style Dictionary's built-ins:
+
+| Name | Type | Description |
+|---|---|---|
+| `shadow/css` | value | Converts shadow objects (single or array) to a `box-shadow` CSS string. px values are converted to rem. |
+| `size/pxToRem-smart` | value | Converts `dimension` token values from px to rem. Skips values already in rem. |
+| `color/css-modern` | value | Color passthrough with transitive alias support. |
+| `gradient/css` | value | Converts gradient objects to CSS `linear-gradient`, `radial-gradient` or `conic-gradient`. |
+| `composite/css` | value | Converts `border`, `outline`, `transition` and `animation` objects to their CSS shorthand. |
+| `typography/css` | value | Typography passthrough — the format handles exploding the value into individual properties. |
+
+### CSS output
+
+All tokens are output as CSS custom properties inside `:root`, sorted alphabetically.
+
+Typography tokens are expanded into multiple properties:
+- `--token-name-font` — a `font` shorthand (when both `fontSize` and `fontFamily` are present)
+- `--token-name-letter-spacing`, `--token-name-text-transform`, `--token-name-text-decoration` — individual properties
+
+The generated file is linted and auto-fixed with stylelint using the config specified in `stylelintConfigPath`.
+
+### Penpot 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).
+
+**Single file** (`penpotDestFile` is a string):
+```
+penpotBuildPath/tokens.jsonc   ← all tokens in one file
+```
+
+**One file per source** (`penpotDestFile` is `null` or omitted):
+```
+penpotBuildPath/colors.tokens.jsonc
+penpotBuildPath/spacing.tokens.jsonc
+penpotBuildPath/typography.tokens.jsonc
+```
+
+The `penpotFormat` 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.
+
+> 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.
+
+---
+
+## `check-unresolved-custom-props.mjs`
+
+Scans all `.css` files in `dir_to_check` (recursively) and reports any `var(--...)` references that are not defined in the generated token CSS file or in any `extra_custom_props_files`.
+
+Results are written to `unresolved-props.md` in the same directory as the config file.
+
+### Usage
+
+```sh
+npx checkUnresolvedProps --config ./path/to/tokens-config.mjs
+```
+
+### Output
+
+The script creates a `unresolved-props.md` file next to the config file. Each line links to the file and line number where the unresolved property is used:
+
+```markdown
+* [components.css :: 42](../src/components.css#L42) -> var(--color-action-hover)
+* [layout.css :: 17](../src/layout.css#L17) -> var(--spacing-missing)
+```
+
+In VS Code, Option/Alt-clicking on the URL opens the file at the required line.
+
+
+### Excluding properties
+
+Use `exclude_pattern` to suppress false positives — for example, internal/private custom properties that are defined dynamically or inline:
+
+```js
+// skips all custom props starting with `--_` or `--js-`
+exclude_pattern: [
+  /^--_/,          
+  /^--js-/,        
+]
+```