style-dictionary 4.3.2 → 4.4.0

package/examples/complete/tokens/color/font.json

@@ -1,33 +1,33 @@
 {
   "color": {
     "font": {
-      "base": { "value": "{color.base.grey.900.value}", "type": "color" },
-      "secondary": { "value": "{color.base.grey.800.value}", "type": "color" },
-      "tertiary": { "value": "{color.base.grey.600.value}", "type": "color" },
-      "quaternary": { "value": "{color.base.grey.400.value}", "type": "color" },
-      "link": { "value": "{color.brand.primary.base.value}", "type": "color" },
-      "active": { "value": "{color.brand.secondary.base.value}", "type": "color" },
-      "error": { "value": "{color.base.red.600.value}", "type": "color" },
-      "warning": { "value": "{color.base.orange.800.value}", "type": "color" },
-      "success": { "value": "{color.base.green.600.value}", "type": "color" },
-      "disabled": { "value": "{color.font.secondary.value}", "type": "color" },
+      "base": { "value": "{color.base.grey.900}", "type": "color" },
+      "secondary": { "value": "{color.base.grey.800}", "type": "color" },
+      "tertiary": { "value": "{color.base.grey.600}", "type": "color" },
+      "quaternary": { "value": "{color.base.grey.400}", "type": "color" },
+      "link": { "value": "{color.brand.primary.base}", "type": "color" },
+      "active": { "value": "{color.brand.secondary.base}", "type": "color" },
+      "error": { "value": "{color.base.red.600}", "type": "color" },
+      "warning": { "value": "{color.base.orange.800}", "type": "color" },
+      "success": { "value": "{color.base.green.600}", "type": "color" },
+      "disabled": { "value": "{color.font.secondary}", "type": "color" },
 
       "inverse": {
-        "base": { "value": "{color.base.white.value}", "type": "color" },
-        "secondary": { "value": "{color.base.grey.100.value}", "type": "color" },
-        "tertiary": { "value": "{color.base.grey.200.value}", "type": "color" },
-        "quaternary": { "value": "{color.base.grey.400.value}", "type": "color" },
-        "link": { "value": "{color.brand.primary.light.value}", "type": "color" },
-        "active": { "value": "{color.brand.secondary.light.value}", "type": "color" },
-        "error": { "value": "{color.base.red.400.value}", "type": "color" },
-        "warning": { "value": "{color.base.orange.400.value}", "type": "color" },
-        "success": { "value": "{color.base.green.400.value}", "type": "color" },
-        "disabled": { "value": "{color.font.inverse.secondary.value}", "type": "color" }
+        "base": { "value": "{color.base.white}", "type": "color" },
+        "secondary": { "value": "{color.base.grey.100}", "type": "color" },
+        "tertiary": { "value": "{color.base.grey.200}", "type": "color" },
+        "quaternary": { "value": "{color.base.grey.400}", "type": "color" },
+        "link": { "value": "{color.brand.primary.light}", "type": "color" },
+        "active": { "value": "{color.brand.secondary.light}", "type": "color" },
+        "error": { "value": "{color.base.red.400}", "type": "color" },
+        "warning": { "value": "{color.base.orange.400}", "type": "color" },
+        "success": { "value": "{color.base.green.400}", "type": "color" },
+        "disabled": { "value": "{color.font.inverse.secondary}", "type": "color" }
       },
 
       "button": {
-        "primary": { "value": "{color.font.inverse.base.value}", "type": "color" },
-        "secondary": { "value": "{color.font.link.value}", "type": "color" }
+        "primary": { "value": "{color.font.inverse.base}", "type": "color" },
+        "secondary": { "value": "{color.font.link}", "type": "color" }
       }
     }
   }

package/examples/complete/tokens/font.json

@@ -2,11 +2,11 @@
   "font": {
     "family": {
       "base": {
-        "value": "{asset.font.opensans.name.value}",
+        "value": "{asset.font.opensans.name}",
         "type": "fontFamily"
       },
       "icons": {
-        "value": "{asset.font.icon.name.value}",
+        "value": "{asset.font.icon.name}",
         "type": "fontFamily"
       }
     }

package/examples/complete/tokens/size/font.json

@@ -8,7 +8,7 @@
       "xl": { "value": "1.5", "type": "fontSize" },
       "xxl": { "value": "2", "type": "fontSize" },
       "xxxl": { "value": "3", "type": "fontSize" },
-      "base": { "value": "{size.font.medium.value}", "type": "fontSize" }
+      "base": { "value": "{size.font.medium}", "type": "fontSize" }
     }
   }
 }

package/examples/complete/tokens/size/padding.json

@@ -7,7 +7,7 @@
       "large": { "value": "1.5", "type": "dimension" },
       "xl": { "value": "2", "type": "dimension" },
       "xxl": { "value": "3", "type": "dimension" },
-      "base": { "value": "{size.padding.medium.value}", "type": "dimension" }
+      "base": { "value": "{size.padding.medium}", "type": "dimension" }
     }
   }
 }

package/lib/StyleDictionary.js

@@ -80,7 +80,7 @@ export default class StyleDictionary extends Register {
   // Placeholder is transformed on prepublish -> see scripts/inject-version.js
   // Another option might be import pkg from './package.json' with { "type": "json" } which would work in both browser and node, but support is not there yet.
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#browser_compatibility
-  static VERSION = '4.3.2';
+  static VERSION = '4.4.0';
 
   /** @returns {Config} */
   get options() {
@@ -492,7 +492,7 @@ export default class StyleDictionary extends Register {
       // }
       //
       // color.background.button.primary.base = {
-      //   value: "{color.brand.value}",
+      //   value: "{color.brand}",
       //   color: {
       //     desaturate: 0.5
       //   }

package/lib/common/formatHelpers/createPropertyFormatter.d.ts

@@ -36,7 +36,7 @@ export function addComment(to_ret_token: string, comment: string, options: Forma
  * @param {boolean} [options.outputReferenceFallbacks] - Whether or not to output css variable fallback values when using output references. You will want to pass this from the `options` object sent to the format function.
  * @param {Dictionary} options.dictionary - The dictionary object sent to the format function
  * @param {string} [options.format] - Available formats are: 'css', 'sass', 'less', and 'stylus'. If you want to customize the format and can't use one of those predefined formats, use the `formatting` option
- * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `prefix`, `indentation`, `separator`, `suffix`, `lineSeparator`, `fileHeaderTimestamp`, `header`, `footer`, `commentStyle` and `commentPosition`. Those are used to generate a line like this: `${indentation}${prefix}${token.name}${separator} ${prop.value}${suffix}`. The remaining formatting options are used for the fileHeader helper.
+ * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `prefix`, `indentation`, `separator`, `suffix`, `lineSeparator`, `fileHeaderTimestamp`, `header`, `footer`, `commentStyle` and `commentPosition`. Those are used to generate a line like this: `${indentation}${prefix}${token.name}${separator} ${token.value}${suffix}`. The remaining formatting options are used for the fileHeader helper.
  * @param {boolean} [options.themeable] [false] - Whether tokens should default to being themeable.
  * @param {boolean} [options.usesDtcg] [false] - Whether DTCG token syntax should be uses.
  * @returns {(token: import('../../../types/DesignToken.d.ts').TransformedToken) => string}

package/lib/common/formatHelpers/createPropertyFormatter.js

@@ -76,7 +76,7 @@ export function addComment(to_ret_token, comment, options) {
         );
         processedComment += `${indentation} */`;
       } else {
-        processedComment = `${commentPosition === above ? indentation : ''}/* ${comment} */`;
+        processedComment = `${commentPosition === above ? indentation : ''}/** ${comment} */`;
       }
       break;
   }
@@ -120,7 +120,7 @@ export function addComment(to_ret_token, comment, options) {
  * @param {boolean} [options.outputReferenceFallbacks] - Whether or not to output css variable fallback values when using output references. You will want to pass this from the `options` object sent to the format function.
  * @param {Dictionary} options.dictionary - The dictionary object sent to the format function
  * @param {string} [options.format] - Available formats are: 'css', 'sass', 'less', and 'stylus'. If you want to customize the format and can't use one of those predefined formats, use the `formatting` option
- * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `prefix`, `indentation`, `separator`, `suffix`, `lineSeparator`, `fileHeaderTimestamp`, `header`, `footer`, `commentStyle` and `commentPosition`. Those are used to generate a line like this: `${indentation}${prefix}${token.name}${separator} ${prop.value}${suffix}`. The remaining formatting options are used for the fileHeader helper.
+ * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `prefix`, `indentation`, `separator`, `suffix`, `lineSeparator`, `fileHeaderTimestamp`, `header`, `footer`, `commentStyle` and `commentPosition`. Those are used to generate a line like this: `${indentation}${prefix}${token.name}${separator} ${token.value}${suffix}`. The remaining formatting options are used for the fileHeader helper.
  * @param {boolean} [options.themeable] [false] - Whether tokens should default to being themeable.
  * @param {boolean} [options.usesDtcg] [false] - Whether DTCG token syntax should be uses.
  * @returns {(token: import('../../../types/DesignToken.d.ts').TransformedToken) => string}
@@ -180,10 +180,10 @@ export default function createPropertyFormatter({
         : outputReferences);
     /**
      * A single value can have multiple references either by interpolation:
-     * "value": "{size.border.width.value} solid {color.border.primary.value}"
+     * "value": "{size.border.width} solid {color.border.primary}"
      * or if the value is an object:
      * "value": {
-     *    "size": "{size.border.width.value}",
+     *    "size": "{size.border.width}",
      *    "style": "solid",
      *    "color": "{color.border.primary.value"}
      * }

package/lib/common/formats.js

@@ -53,11 +53,13 @@ import scssMapFlatTemplate from './templates/scss/map-flat.template.js';
 import macrosTemplate from './templates/ios/macros.template.js';
 import plistTemplate from './templates/ios/plist.template.js';
 import {
+  commentPositions,
   commentStyles,
   fileHeaderCommentStyles,
   formats as fileFormats,
   propertyFormatNames,
 } from '../enums/index.js';
+import { addComment } from './formatHelpers/createPropertyFormatter.js';
 
 /**
  * @typedef {import('../../types/Format.d.ts').Format} Format
@@ -71,6 +73,7 @@ import {
  * @typedef {import('../utils/stripMeta.js').StripMetaOptions} StripMetaOptions
  */
 
+const { above } = commentPositions;
 const { none } = commentStyles;
 const { long, short, xml } = fileHeaderCommentStyles;
 const { css, sass, less, stylus } = propertyFormatNames;
@@ -158,7 +161,11 @@ function stripMetaProps(tokens, options) {
 async function formatJS(content, ts = false) {
   return prettier.format(content, {
     parser: ts ? `typescript` : `babel`,
-    plugins: [prettierPluginBabel, prettierPluginEstree, prettierPluginTypescript],
+    plugins: [
+      prettierPluginBabel,
+      /** @type {import('prettier').Plugin} */ (prettierPluginEstree),
+      prettierPluginTypescript,
+    ],
   });
 }
 
@@ -193,25 +200,53 @@ const formats = {
    * ```
    */
   [cssVariables]: async function ({ dictionary, options = {}, file }) {
-    const selector = options.selector ? options.selector : `:root`;
+    const selector = Array.isArray(options.selector)
+      ? options.selector
+      : options.selector
+        ? [options.selector]
+        : [`:root`];
     const { outputReferences, outputReferenceFallbacks, usesDtcg, formatting } = options;
     const header = await fileHeader({
       file,
       formatting: getFormattingCloneWithoutPrefix(formatting),
       options,
     });
+    const indentation = formatting?.indentation || '  ';
+
+    const nestInSelector = (
+      /** @type {string} */ content,
+      /** @type {string} */ selector,
+      /** @type {string} */ indentation,
+    ) => {
+      return `${indentation}${selector} {\n` + content + `\n${indentation}}`;
+    };
+
+    const variables = formattedVariables({
+      format: css,
+      dictionary,
+      outputReferences,
+      outputReferenceFallbacks,
+      formatting: {
+        ...formatting,
+        indentation: indentation.repeat(selector.length),
+      },
+      usesDtcg,
+    });
+
     return (
       header +
-      `${selector} {\n` +
-      formattedVariables({
-        format: css,
-        dictionary,
-        outputReferences,
-        outputReferenceFallbacks,
-        formatting,
-        usesDtcg,
-      }) +
-      `\n}\n`
+      selector
+        .reverse()
+        .reduce(
+          (content, currentSelector, index) =>
+            nestInSelector(
+              content,
+              currentSelector,
+              indentation.repeat(selector.length - 1 - index),
+            ),
+          variables,
+        ) +
+      '\n'
     );
   },
 
@@ -640,7 +675,13 @@ const formats = {
         const comment = options.usesDtcg ? token.$description : token.comment;
         const to_ret = `export const ${token.name} = ${value};`;
 
-        return comment ? to_ret.concat(`// ${comment}`) : to_ret;
+        const format = {
+          commentStyle: short,
+          indentation: '',
+          ...formatting,
+        };
+
+        return comment ? addComment(to_ret, comment, format) : to_ret;
       }),
     ]
       .flat()
@@ -665,7 +706,7 @@ const formats = {
    * ```
    */
   [javascriptEsm]: async function ({ dictionary, file, options }) {
-    const { formatting, minify = false } = options;
+    const { formatting, minify = false, flat = false } = options;
     let { tokens } = dictionary;
     tokens = stripMetaProps(
       tokens,
@@ -678,11 +719,25 @@ const formats = {
       options,
     });
 
-    const dictionaryString = JSON.stringify(
-      minify ? minifyDictionary(tokens, options.usesDtcg) : tokens,
-      null,
-      2,
-    );
+    let dictionaryString;
+    if (flat) {
+      dictionaryString = JSON.stringify(
+        Object.fromEntries(
+          dictionary.allTokens.map((token) => [
+            token.name,
+            options.usesDtcg ? token.$value : token.value,
+          ]),
+        ),
+        null,
+        2,
+      );
+    } else {
+      dictionaryString = JSON.stringify(
+        minify ? minifyDictionary(tokens, options.usesDtcg) : tokens,
+        null,
+        2,
+      );
+    }
 
     const content = `${header}export default ${dictionaryString};\n`;
     return formatJS(content);
@@ -735,15 +790,19 @@ const formats = {
           options,
         );
         const comment = options.usesDtcg ? token.$description : token.comment;
-
-        return [
-          `${comment ? `/** ${comment} */` : ''}`,
-          `export const ${token.name} : ${typescriptType};`,
-        ].join('\n');
+        const to_ret = `export const ${token.name} : ${typescriptType};`;
+        const format = {
+          commentPosition: above,
+          commentStyle: long,
+          indentation: '',
+          ...formatting,
+        };
+
+        return comment ? addComment(to_ret, comment, format) : to_ret;
       }),
     ]
       .flat()
-      .join('');
+      .join('\n');
     return formatJS(content, true);
   },
 

package/lib/common/transforms.d.ts

@@ -198,12 +198,12 @@ declare const _default: {
         transform: (token: import("../../types/DesignToken.d.ts").TransformedToken, _: import("../../types/Config.d.ts").PlatformConfig, options: import("../../types/Config.d.ts").Config) => string;
     };
     /**
-     * Transforms the value into an 6-digit hex string
+     * Transforms the value into a 6-digit (if alpha is undefined or 1.0) or 8-digit hex string
      *
      * ```js
      * // Matches: token.type === 'color'
      * // Returns:
-     * "#009688"
+     * "#009688DE"
      * ```
      *
      * @memberof Transforms
@@ -221,7 +221,7 @@ declare const _default: {
      * // Returns:
      * "#009688ff"
      * ```
-     *
+     * @deprecated use colorHex ('color/hex') instead, which supports hex8 now.
      * @memberof Transforms
      */
     "color/hex8": {

package/lib/common/transforms.js

@@ -44,9 +44,15 @@ const camelOpts = {
  * @returns {boolean}
  */
 export function isColor(token, options) {
+  const val = options.usesDtcg ? token.$value : token.value;
+  const type = options.usesDtcg ? token.$type : token.type;
   return (
-    (options.usesDtcg ? token.$type : token.type) === 'color' &&
-    Color(options.usesDtcg ? token.$value : token.value).isValid()
+    type === 'color' &&
+    Color(val).isValid() &&
+    // exclude gradients from being color transformed
+    ['linear', 'radial', 'conic']
+      .map((pre) => `${pre}-gradient`)
+      .every((pre) => !`${val}`.startsWith(pre) && !`${val}`.startsWith(`repeating-${pre}`))
   );
 }
 
@@ -454,12 +460,12 @@ export default {
   },
 
   /**
-   * Transforms the value into an 6-digit hex string
+   * Transforms the value into a 6-digit (if alpha is undefined or 1.0) or 8-digit hex string
    *
    * ```js
    * // Matches: token.type === 'color'
    * // Returns:
-   * "#009688"
+   * "#009688DE"
    * ```
    *
    * @memberof Transforms
@@ -468,7 +474,12 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      return Color(options.usesDtcg ? token.$value : token.value).toHexString();
+      const color = Color(options.usesDtcg ? token.$value : token.value);
+      if (color.getAlpha() === 1) {
+        return color.toHexString();
+      } else {
+        return color.toHex8String();
+      }
     },
   },
 
@@ -480,7 +491,7 @@ export default {
    * // Returns:
    * "#009688ff"
    * ```
-   *
+   * @deprecated use colorHex ('color/hex') instead, which supports hex8 now.
    * @memberof Transforms
    */
   [transforms.colorHex8]: {

package/lib/enums/transforms.d.ts

@@ -11,7 +11,6 @@ export namespace transforms {
     let colorHsl: "color/hsl";
     let colorHsl4: "color/hsl-4";
     let colorHex: "color/hex";
-    let colorHex8: "color/hex8";
     let colorHex8android: "color/hex8android";
     let colorComposeColor: "color/composeColor";
     let colorUIColor: "color/UIColor";
@@ -54,4 +53,5 @@ export namespace transforms {
     let contentFlutterLiteral: "content/flutter/literal";
     let assetFlutterLiteral: "asset/flutter/literal";
     let sizeFlutterRemToDouble: "size/flutter/remToDouble";
+    let colorHex8: "color/hex8";
 }

package/lib/enums/transforms.js

@@ -11,7 +11,6 @@ export const transforms = {
   colorHsl: /** @type {'color/hsl'} */ ('color/hsl'),
   colorHsl4: /** @type {'color/hsl-4'} */ ('color/hsl-4'),
   colorHex: /** @type {'color/hex'} */ ('color/hex'),
-  colorHex8: /** @type {'color/hex8'} */ ('color/hex8'),
   colorHex8android: /** @type {'color/hex8android'} */ ('color/hex8android'),
   colorComposeColor: /** @type {'color/composeColor'} */ ('color/composeColor'),
   colorUIColor: /** @type {'color/UIColor'} */ ('color/UIColor'),
@@ -54,4 +53,8 @@ export const transforms = {
   contentFlutterLiteral: /** @type {'content/flutter/literal'} */ ('content/flutter/literal'),
   assetFlutterLiteral: /** @type {'asset/flutter/literal'} */ ('asset/flutter/literal'),
   sizeFlutterRemToDouble: /** @type {'size/flutter/remToDouble'} */ ('size/flutter/remToDouble'),
+  /**
+   * @deprecated use 'color/hex instead
+   */
+  colorHex8: /** @type {'color/hex8'} */ ('color/hex8'),
 };

package/lib/utils/convertToDTCG.js

@@ -25,20 +25,18 @@ function recurse(slice, opts) {
   let types = new Set();
 
   // this slice within the dictionary is a design token
-  if (Object.hasOwn(slice, 'value')) {
+  // Check for $value in case the input is already DTCG syntax
+  if (Object.hasOwn(slice, 'value') || Object.hasOwn(slice, '$value')) {
     const token = /** @type {DesignToken} */ (slice);
-    // convert to $ prefixed properties
     Object.keys(token).forEach((key) => {
-      switch (key) {
-        case 'type':
-          // track the encountered types for this layer
-          types.add(/** @type {string} */ (token[key]));
-        // eslint-disable-next-line no-fallthrough
-        case 'value':
-        case 'description':
-          token[`$${key}`] = token[key];
-          delete token[key];
-        // no-default
+      if (['type', '$type'].includes(key)) {
+        // track the encountered types for this layer
+        types.add(/** @type {string} */ (token[key]));
+      }
+      // convert to $ prefixed properties
+      if (['type', 'description', 'value'].includes(key)) {
+        token[`$${key}`] = token[key];
+        delete token[key];
       }
     });
     return types;

package/lib/utils/preprocess.js

@@ -38,8 +38,9 @@ export async function preprocess(
 
   const preprocessors = Object.entries(preprocessorObj);
   if (preprocessors.length > 0) {
-    for (const [key, preprocessor] of preprocessors) {
-      if (appliedPreprocessors.includes(key)) {
+    for (const key of appliedPreprocessors) {
+      const preprocessor = preprocessorObj[key];
+      if (preprocessor) {
         processedTokens = await preprocessor(processedTokens, options);
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "style-dictionary",
-  "version": "4.3.2",
+  "version": "4.4.0",
   "description": "Style once, use everywhere. A build system for creating cross-platform styles.",
   "keywords": [
     "style dictionary",
@@ -130,8 +130,7 @@
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.4",
-    "@astrojs/starlight": "^0.29.2",
-    "@babel/plugin-proposal-private-property-in-object": "^7.21.11",
+    "@astrojs/starlight": "^0.31.1",
     "@changesets/cli": "^2.27.1",
     "@commitlint/cli": "^18.4.3",
     "@commitlint/config-conventional": "^18.4.3",
@@ -142,16 +141,16 @@
     "@types/chai": "^4.3.9",
     "@types/tinycolor2": "^1.4.6",
     "@types/uuid": "^9.0.8",
-    "@typescript-eslint/parser": "^8.16.0",
+    "@typescript-eslint/parser": "^8.22.0",
     "@web/test-runner": "^0.18.2",
     "@web/test-runner-commands": "^0.9.0",
     "@web/test-runner-playwright": "^0.11.0",
     "acorn": "^8.11.3",
-    "astro": "^4.16.16",
+    "astro": "^5.2.3",
     "chai": "^5.0.0-alpha.2",
-    "eslint": "^9.14.0",
+    "eslint": "^9.19.0",
     "eslint-plugin-mocha": "^10.5.0",
-    "eslint-plugin-react": "^7.37.2",
+    "eslint-plugin-react": "^7.37.4",
     "estree-walker": "^3.0.3",
     "fs-extra": "^10.0.0",
     "hanbi": "^1.0.1",
@@ -169,7 +168,7 @@
     "npm-run-all": "^4.1.5",
     "sass": "^1.69.5",
     "sharp": "^0.32.5",
-    "starlight-links-validator": "^0.13.3",
+    "starlight-links-validator": "^0.14.2 ",
     "stylus": "^0.56.0",
     "typescript": "^5.7.2",
     "unist-util-visit": "^5.0.0",