feat: --output-references CLI arg for building tokens, registers filt…

…ers, and updates CSS vars format

* Exposes --output-references CLI argument for build-tokens command. Defaults to true. Ensures brand package output with the CLI includes references in build output out-of-the-box.
* Registers filter(s) isThemeVariant{"Light"}.
* Migrates createCustomCSSVariables to use formattedVariables to rely on out-of-the-box CSS variable formatting. The formatter still supports token-specific overrides of `outputReferences`
* Relies on default style-dictionary fileHeader, with opt-in timestamp.

Makefile

@@ -1,3 +1,4 @@
+.PHONY: build
 build:
 	rm -rf ./dist
 	tsc --project tsconfig.build.json

bin/paragon-scripts.js

@@ -85,11 +85,21 @@ const COMMANDS = {
         description: 'Include only source design tokens in the build.',
         defaultValue: false,
       },
+      {
+        name: '--output-references',
+        description: 'Include references in the build output.',
+        defaultValue: true,
+      },
       {
         name: '-t, --themes',
         description: 'Specify themes to include in the token build.',
         defaultValue: 'light',
       },
+      {
+        name: '-v, --verbose',
+        description: 'Enable verbose logging.',
+        defaultValue: false,
+      },
     ],
   },
   'replace-variables': {

lib/build-tokens.js

@@ -13,24 +13,37 @@ const { createIndexCssFile } = require('../tokens/utils');
  * @param {string|string[]} [commandArgs.themes=['light']] - The themes (variants) for which to build tokens.
  */
 async function buildTokensCommand(commandArgs) {
-  const StyleDictionary = await initializeStyleDictionary();
-
   const defaultParams = {
     themes: ['light'],
     'build-dir': './build/',
+    'source-tokens-only': false,
+    'output-references': true,
+    verbose: false,
   };
 
   const alias = {
     'build-dir': 'b',
     themes: 't',
+    verbose: '-v',
   };
 
   const {
     'build-dir': buildDir,
     source: tokensSource,
     'source-tokens-only': hasSourceTokensOnly,
+    'output-references': outputReferences,
     themes,
-  } = minimist(commandArgs, { alias, default: defaultParams, boolean: 'source-tokens-only' });
+    verbose,
+  } = minimist(
+    commandArgs,
+    {
+      alias,
+      default: defaultParams,
+      boolean: ['source-tokens-only', 'output-references', 'verbose'],
+    },
+  );
+
+  const StyleDictionary = await initializeStyleDictionary({ themes });
 
   const coreConfig = {
     include: [
@@ -52,24 +65,30 @@ async function buildTokensCommand(commandArgs) {
             destination: 'core/variables.css',
             filter: hasSourceTokensOnly ? 'isSource' : undefined,
             options: {
-              outputReferences: !hasSourceTokensOnly,
+              outputReferences,
+              formatting: {
+                fileHeaderTimestamp: true,
+              },
             },
           },
           {
             format: 'css/custom-media-breakpoints',
             destination: 'core/custom-media-breakpoints.css',
             filter: hasSourceTokensOnly ? 'isSource' : undefined,
             options: {
-              outputReferences: !hasSourceTokensOnly,
+              outputReferences,
+              formatting: {
+                fileHeaderTimestamp: true,
+              },
             },
           },
         ],
         transforms: StyleDictionary.hooks.transformGroups.css.filter(item => item !== 'size/rem').concat('color/sass-color-functions', 'str-replace'),
-        options: {
-          fileHeader: 'customFileHeader',
-        },
       },
     },
+    log: {
+      verbosity: verbose ? 'verbose' : 'default',
+    },
   };
 
   const getStyleDictionaryConfig = (themeVariant) => ({
@@ -104,17 +123,25 @@ async function buildTokensCommand(commandArgs) {
           {
             format: 'css/custom-variables',
             destination: `themes/${themeVariant}/variables.css`,
-            filter: hasSourceTokensOnly ? 'isSource' : undefined,
+            filter: hasSourceTokensOnly
+              ? `isThemeVariant${themeVariant.charAt(0).toUpperCase()}${themeVariant.slice(1)}SourceOnly`
+              : `isThemeVariant${themeVariant.charAt(0).toUpperCase()}${themeVariant.slice(1)}`,
             options: {
-              outputReferences: !hasSourceTokensOnly,
+              outputReferences,
+              formatting: {
+                fileHeaderTimestamp: true,
+              },
             },
           },
           {
             format: 'css/utility-classes',
             destination: `themes/${themeVariant}/utility-classes.css`,
             filter: hasSourceTokensOnly ? 'isSource' : undefined,
             options: {
-              outputReferences: !hasSourceTokensOnly,
+              outputReferences,
+              formatting: {
+                fileHeaderTimestamp: true,
+              },
             },
           },
         ],

package.json

@@ -52,7 +52,8 @@
     "prepare": "husky || true",
     "build-tokens": "./bin/paragon-scripts.js build-tokens --build-dir ./styles/css",
     "replace-variables-usage-with-css": "./bin/paragon-scripts.js replace-variables -p src -t usage",
-    "replace-variables-definition-with-css": "./bin/paragon-scripts.js replace-variables -p src -t definition"
+    "replace-variables-definition-with-css": "./bin/paragon-scripts.js replace-variables -p src -t definition",
+    "cli:help": "./bin/paragon-scripts.js help"
   },
   "dependencies": {
     "@popperjs/core": "^2.11.4",

styles/css/core/custom-media-breakpoints.css

@@ -1,7 +1,6 @@
-/*
- * IMPORTANT: This file is the result of assembling design tokens.
- * Do not edit directly.
- * Generated on Tue, 27 Aug 2024 17:14:44 GMT
+/**
+ * Do not edit directly, this file was auto-generated.
+ * Generated on Sat, 31 Aug 2024 19:26:11 GMT
  */
 
 @custom-media --pgn-size-breakpoint-min-width-xs (min-width: 0rem);