style-dictionary 4.0.0 → 4.1.0

package/README.md

@@ -1,12 +1,8 @@
 <pre>
-<a href="https://amzn.github.io/style-dictionary/#/version_3">What's new in Style Dictionary 3.0!</a>
+<a href="https://styledictionary.com/version-4/migration/">What's new in Style Dictionary 4.0!</a>
 </pre>
 
-<pre>
-<a href="https://github.com/amzn/style-dictionary#version-4">What's coming in Style Dictionary 4.0?</a>
-</pre>
-
-<img src="docs/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="100" align="right" />
+<img src="docs/src/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="100" align="right" />
 
 [![npm version](https://img.shields.io/npm/v/style-dictionary.svg?style=flat-square)](https://badge.fury.io/js/style-dictionary)
 ![license](https://img.shields.io/npm/l/style-dictionary.svg?style=flat-square)
@@ -136,7 +132,7 @@ A style dictionary is a collection of design tokens, key/value pairs that descri
 
 ### config.json
 
-This tells the style dictionary build system how and what to build. The default file path is `config.json` or `config.js` in the root of the project, but you can name it whatever you want by passing in the `--config` flag to the [CLI](https://amzn.github.io/style-dictionary/#/using_the_cli).
+This tells the style dictionary build system how and what to build. The default file path is `config.json` or `config.js` in the root of the project, but you can name it whatever you want by passing in the `--config` flag to the [CLI](https://styledictionary.com/getting-started/using_the_cli/).
 
 ```json
 {
@@ -176,7 +172,7 @@ This tells the style dictionary build system how and what to build. The default
 | platform.buildPath                   | String (optional) | Base path to build the files, must end with a trailing slash.                                                                                                                                                                                                                 |
 | platform.files                       | Array (optional)  | Files to be generated for this platform.                                                                                                                                                                                                                                      |
 | platform.file.destination            | String (optional) | Location to build the file, will be appended to the buildPath.                                                                                                                                                                                                                |
-| platform.file.format                 | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://amzn.github.io/style-dictionary/#/formats)                                                                                                                      |
+| platform.file.format                 | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://styledictionary.com/reference/hooks/formats/)                                                                                                                   |
 | platform.file.options                | Object (optional) | A set of extra options associated with the file.                                                                                                                                                                                                                              |
 | platform.file.options.showFileHeader | Boolean           | If the generated file should have a "Do not edit + Timestamp" header (where the format supports it). By default is "true".                                                                                                                                                    |
 
@@ -224,7 +220,7 @@ float const SizeFontBase = 16.00f;
 
 The style dictionary framework comes with some example code to get you started. Install the node module globally, create a directory and `cd` into it.
 
-```
+```bash
 $ npm i -g style-dictionary
 $ mkdir MyStyleDictionary
 $ cd MyStyleDictionary
@@ -232,13 +228,13 @@ $ cd MyStyleDictionary
 
 Now run:
 
-```
+```bash
 $ style-dictionary init basic
 ```
 
 This command will copy over the example files found in [example](examples/) in this repo. Now you have an example project set up. You can make changes to the style dictionary and rebuild the project by running:
 
-```
+```bash
 $ style-dictionary build
 ```
 
@@ -313,7 +309,7 @@ StyleDictionary.registerTransform({
 StyleDictionary.buildAllPlatforms();
 ```
 
-For more information on creating your own transforms and formats, take a look at our [docs](https://amzn.github.io/style-dictionary/).
+For more information on creating your own transforms and formats, take a look at our [docs](https://styledictionary.com).
 
 ## Version 4
 
@@ -340,7 +336,7 @@ We are very open to feedback and collaboration, feel free to reach out to us in
 
 The mascot for Style Dictionary is ["Pascal"](https://github.com/amzn/style-dictionary/issues/97) the chameleon (seen below). You can also find them blending in as the logo throughout the documentation.
 
-<img src="docs/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="240" />
+<img src="docs/src/assets/logo.png" alt="Style Dictionary logo and mascot" title="&quot;Pascal&quot;" width="240" />
 
 ## Contributing
 

package/examples/README.md

@@ -31,12 +31,8 @@ This is a more complete package and should have everything you need to get start
 If you want to look at more advanced examples of possible applications and customizations of Style Dictionary, the [`examples/advanced`](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/) folder on GitHub contains these extra folders:
 
 - [**assets-base64-embed**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/assets-base64-embed) shows how it's possible to embed and distribute assets – like images, icons and fonts – directly as design tokens.
-- [**auto-rebuild-watcher**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/auto-rebuild-watcher) shows how to setup a "watcher" that auto-rebuilds the tokens every time there is a change in the tokens.
-- [**component-cti**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/component-cti) shows how to write component tokens and still use the CTI structure.
 - [**create-react-app**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/create-react-app) shows how to integrate Style Dictionary into a React application.
 - [**create-react-native-app**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/create-react-native-app) shows how to integrate Style Dictionary into a React Native application.
-- [**custom-file-header**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-file-header) shows how to define custom file headers and use them in output files.
-- [**custom-formats-with-templates**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-formats-with-templates) shows how to generate custom output formats using templates, useful when you need to distribute your design tokens into your own pipelines or scripts.
 - [**custom-parser**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-parser) shows how to use custom parsers for token files.
 - [**custom-transforms**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-transforms) shows how to use custom transforms (and transformGroups) to apply custom "transformations" to the design tokens.
 - [**flutter**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/flutter) shows how to integrate with Flutter applications.

package/examples/advanced/assets-base64-embed/package.json

@@ -12,6 +12,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/create-react-app/package.json

@@ -12,7 +12,7 @@
   },
   "devDependencies": {
     "eslint-config-react-app": "^7.0.1",
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   },
   "resolutions": {
     "immer": "8.0.1",

package/examples/advanced/create-react-native-app/package.json

@@ -29,7 +29,7 @@
     "eslint-config-react-app": "^7.0.1",
     "jest": "~25.2.6",
     "react-test-renderer": "~16.13.1",
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   },
   "jest": {
     "preset": "react-native"

package/examples/advanced/custom-parser/package.json

@@ -10,6 +10,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/custom-transforms/README.md

@@ -9,7 +9,7 @@ Transforms are functions that modify a design token (in a non-destructive way).
 The need for custom transforms is that Style Dictionary expects the tokens to be declared according to certain criteria, to use the pre-defined transforms and formats/templates. For example, the _web_ transformGroup consists of the _attribute/cti_, _name/kebab_, _size/px_ and _color/css_ transforms.
 The _size/px_ adds 'px' to the end of the number, and is applied only if `token.attributes.category === 'size'`. This means that your token needs to be expressed without units, and be under the _'size'_ "category. If you need a different logic or you want to organize your tokens differently, probably you can't use the out-of-the-box transformation groups, but you have to declare your custom ones.
 
-If [custom formats](../custom-formats-with-templates/) are the way to allow users to customize the format of the _output_ of Style Dictionary, custom transforms are the way to allow them to customize both the _input_ (the token names/values/attributes) and the _output_ (the actual values expressed in the design tokens). For this reasons, custom transforms are probably one of the **most powerful features** of Style Dictionary: they make it extremely versatile, allowing limitless possibilities of extension and customization of the entire design token pipeline.
+If [custom formats](https://v4.styledictionary.com/reference/hooks/formats/#custom-formats) are the way to allow users to customize the format of the _output_ of Style Dictionary, custom transforms are the way to allow them to customize both the _input_ (the token names/values/attributes) and the _output_ (the actual values expressed in the design tokens). For this reasons, custom transforms are probably one of the **most powerful features** of Style Dictionary: they make it extremely versatile, allowing limitless possibilities of extension and customization of the entire design token pipeline.
 
 #### Running the example
 

package/examples/advanced/custom-transforms/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/font-face-rules/package.json

@@ -9,6 +9,6 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/format-helpers/package.json

@@ -10,6 +10,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/format-helpers/sd.config.js

@@ -3,7 +3,7 @@ import {
   fileHeader,
   formattedVariables,
   sortByReference,
-} from 'style-dictionary';
+} from 'style-dictionary/utils';
 
 export default {
   hooks: {

package/examples/advanced/matching-build-files/package.json

@@ -17,6 +17,6 @@
   "author": "Kelly Harrop <kn.harrop@gmail.com>",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/multi-brand-multi-platform/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/node-modules-as-config-and-properties/package.json

@@ -20,7 +20,7 @@
   },
   "homepage": "https://github.com/dbanksdesign/style-dictionary-node#readme",
   "devDependencies": {
-    "style-dictionary": "4.0.0",
+    "style-dictionary": "^4.1.0",
     "tinycolor2": "^1.4.1"
   }
 }

package/examples/advanced/npm-module/package.json

@@ -17,6 +17,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/referencing_aliasing/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/s3/package.json

@@ -16,6 +16,6 @@
   "devDependencies": {
     "aws-sdk": "^2.7.21",
     "fs-extra": "^1.0.0",
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/tokens-deprecation/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/transitive-transforms/package.json

@@ -11,7 +11,7 @@
   "author": "",
   "license": "ISC",
   "devDependencies": {
-    "chroma-js": "^2.1.0",
-    "style-dictionary": "4.0.0"
+    "colorjs.io": "^0.5.2",
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/transitive-transforms/sd.config.js

@@ -1,10 +1,13 @@
 import StyleDictionary from 'style-dictionary';
 import { usesReferences } from 'style-dictionary/utils';
-import chroma from 'chroma-js';
+import Color from 'colorjs.io';
 
 const colorTransform = (token) => {
   const { value, modify = [] } = token;
-  let color = chroma(value);
+
+  // This assumes "hex" format, if you want to support { h, s, l } format you have to do
+  // `new Color('hsl', [value.h, value.s, value.l]);`
+  const color = new Color(value);
 
   // defer until reference is resolved
   if (typeof modify === 'string' && usesReferences(modify)) {
@@ -18,15 +21,22 @@ const colorTransform = (token) => {
     if (usesReferences(type) || usesReferences(amount)) {
       return undefined;
     }
-    // modifier type must match a method name in chromajs
-    // https://gka.github.io/chroma.js/
-    // chroma methods can be chained, so each time we override the color variable
-    // we can still call other chroma methods, similar to
-    // chroma(value).brighten(1).darken(1).hex();
-    color = color[type](amount);
+
+    switch (type) {
+      case 'lighten': {
+        const lightness = color.hsl.l;
+        const difference = 100 - lightness;
+        const newLightness = Math.min(100, lightness + difference * amount);
+        color.set('hsl.l', newLightness);
+        break;
+      }
+      case 'transparentize':
+        color.alpha = Math.max(0, Math.min(1, Number(amount)));
+        break;
+    }
   });
 
-  return color.hex();
+  return color.to('srgb').toString({ format: 'hex' });
 };
 
 export default {
@@ -36,21 +46,24 @@ export default {
 
   // I am directly defining transforms here
   // This would work if you were to call StyleDictionary.registerTransform() as well
-  transform: {
-    colorTransform: {
-      type: `value`,
-      // only transforms that have transitive: true will be applied to tokens
-      // that alias/reference other tokens
-      transitive: true,
-      filter: (token) => token.attributes.category === 'color' && token.modify,
-      transform: colorTransform,
-    },
+  hooks: {
+    transforms: {
+      colorTransform: {
+        type: `value`,
+        // only transforms that have transitive: true will be applied to tokens
+        // that alias/reference other tokens
+        transitive: true,
+        filter: (token) => token.attributes.category === 'color' && token.modify,
+        transform: colorTransform,
+      },
 
-    // For backwards compatibility, all built-in transforms are not transitive
-    // by default. This will make the 'color/css' transform transitive
-    'color/css': Object.assign({}, StyleDictionary.transform[`color/css`], {
-      transitive: true,
-    }),
+      // For backwards compatibility, all built-in transforms are not transitive
+      // by default. This will make the 'color/css' transform transitive
+      'color/css': {
+        ...StyleDictionary.hooks.transforms[`color/css`],
+        transitive: true,
+      },
+    },
   },
 
   platforms: {

package/examples/advanced/transitive-transforms/tokens/color/core.json5

@@ -6,10 +6,6 @@
 
       red: {
         '100': {
-          // hue, saturation, and lightness are defined in
-          // tokens/hue.json5, tokens/saturation.json5, and tokens/lightness.json5
-          // The {h, s, l} object structure conforms to the input structure for
-          // chromajs: https://gka.github.io/chroma.js/#chroma
           value: { h: '{hue.red}', s: '{saturation.7}', l: '{lightness.7}' },
           type: 'color',
         },

package/examples/advanced/transitive-transforms/tokens/color/font.json5

@@ -1,15 +1,13 @@
 {
   color: {
     font: {
-      primary: { value: '{color.core.black.value}', type: 'color' },
+      primary: { value: '{color.core.black}', type: 'color' },
       secondary: {
-        value: '{color.font.primary.value}',
+        value: '{color.font.primary}',
         modify: [
           {
-            type: 'brighten',
-            // See https://gka.github.io/chroma.js/#color-brighten
-            // for definition of brighten
-            amount: 1,
+            type: 'lighten',
+            amount: 0.2,
           },
         ],
         type: 'color',
@@ -20,10 +18,10 @@
         value: '{color.font.secondary}',
         modify: [
           {
-            // this will brighten the secondary value, which is a brightened version
+            // this will lighten the secondary value, which is a lightened version
             // of primary
-            type: 'brighten',
-            amount: 1,
+            type: 'lighten',
+            amount: 0.2,
           },
         ],
         type: 'color',

package/examples/advanced/transitive-transforms/tokens/color/overlay.json5

@@ -2,10 +2,10 @@
   color: {
     overlay: {
       primary: {
-        value: '{color.core.white.value}',
+        value: '{color.core.white}',
         modify: [
           {
-            type: 'alpha',
+            type: 'transparentize',
             // You can access other parts of your style dictionary in here too:
             amount: '{alpha.1}',
           },
@@ -14,10 +14,10 @@
       },
 
       secondary: {
-        value: '{color.core.white.value}',
+        value: '{color.core.white}',
         modify: [
           {
-            type: 'alpha',
+            type: 'transparentize',
             // You can access other parts of your style dictionary in here too:
             amount: '{alpha.2}',
           },

package/examples/advanced/variables-in-outputs/package.json

@@ -11,6 +11,6 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "style-dictionary": "4.0.0"
+    "style-dictionary": "^4.1.0"
   }
 }

package/examples/advanced/yaml-tokens/package.json

@@ -10,7 +10,7 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "4.0.0",
+    "style-dictionary": "^4.1.0",
     "yaml": "^1.10.0"
   }
 }

package/lib/StyleDictionary.d.ts

@@ -32,10 +32,10 @@ export default class StyleDictionary extends Register {
     get options(): import("../types/Config.ts").Config;
     _options: import("../types/Config.ts").Config | undefined;
     config: string | import("../types/Config.ts").Config;
-    /** @type {Tokens|TransformedTokens|PreprocessedTokens} */
-    tokens: Tokens | TransformedTokens | PreprocessedTokens;
-    /** @type {TransformedToken[]} */
-    allTokens: TransformedToken[];
+    /** @type {PreprocessedTokens} */
+    tokens: PreprocessedTokens;
+    /** @type {PreprocessedTokens[]} */
+    allTokens: PreprocessedTokens[];
     /** @type {boolean | undefined} */
     usesDtcg: boolean | undefined;
     /** @type {LogConfig} */
@@ -64,6 +64,14 @@ export default class StyleDictionary extends Register {
     unfilteredAllTokens: TransformedToken[];
     hasInitialized: Promise<any>;
     hasInitializedResolve: (value: any) => void;
+    /**
+     * Storing the platform specific transformed tokens so we can prevent re-running exportPlatform when we already know the outcome
+     * Same thing for platform specific configs, we don't need to call transformConfig again if we already know the outcome
+     */
+    /** @type {Record<string,Dictionary>} */
+    _dictionaries: Record<string, Dictionary>;
+    /** @type {Record<string,PlatformConfig>} */
+    _platformConfigs: Record<string, PlatformConfig>;
     /**
      * @param {{verbosity?: LogConfig['verbosity'], warnings?: LogConfig['warnings']}} [opts]
      * @returns
@@ -95,20 +103,47 @@ export default class StyleDictionary extends Register {
     shouldRunExpansion(expandCfg?: import("../types/Config.ts").ExpandConfig | undefined): boolean;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
+     */
+    getPlatformConfig(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): import("../types/Config.ts").PlatformConfig;
+    /**
+     * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
+     */
+    getPlatformTokens(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<import("../types/DesignToken.ts").Dictionary>;
+    /**
+     * Public wrapper around _exportPlatform, returns only tokens object
+     * Here for backwards compatibility.
+     * @deprecated use getPlatformTokens instead
+     *
+     * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      * @returns {Promise<TransformedTokens>}
      */
-    exportPlatform(platform: string): Promise<TransformedTokens>;
+    exportPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<TransformedTokens>;
+    /**
+     * @param {string} platform
+     * @returns {Promise<Dictionary>}
+     */
+    _exportPlatform(platform: string): Promise<Dictionary>;
     /**
      * This will get the dictionary / platformConfig for specified platform name
      * Runs transforms, reference resolutions
+     * @deprecated use getPlatformConfig / getPlatformTokens instead
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      * @returns
      */
-    getPlatform(platform: string): Promise<{
-        dictionary: {
-            tokens: import("../types/DesignToken.ts").TransformedTokens;
-            allTokens: import("../types/DesignToken.ts").TransformedToken[];
-        };
+    getPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<{
+        dictionary: import("../types/DesignToken.ts").Dictionary;
         platformConfig: import("../types/Config.ts").PlatformConfig;
     }>;
     /**
@@ -134,24 +169,51 @@ export default class StyleDictionary extends Register {
     }>;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      */
-    formatPlatform(platform: string): Promise<{
+    formatPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<{
         output: unknown;
         destination: string | undefined;
     }[]>;
-    formatAllPlatforms(): Promise<{}>;
+    /**
+     * @param {{ cache?: boolean }} [opts]
+     * @returns
+     */
+    formatAllPlatforms(opts?: {
+        cache?: boolean;
+    } | undefined): Promise<{}>;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
      * @returns
      */
-    buildPlatform(platform: string): Promise<this>;
-    buildAllPlatforms(): Promise<this>;
+    buildPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
+    /**
+     * @param {{ cache?: boolean }} [opts]
+     * @returns
+     */
+    buildAllPlatforms(opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
     /**
      * @param {string} platform
+     * @param {{ cache?: boolean }} [opts]
+     * @returns
+     */
+    cleanPlatform(platform: string, opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
+    /**
+     * @param {{ cache?: boolean }} [opts]
      * @returns
      */
-    cleanPlatform(platform: string): Promise<this>;
-    cleanAllPlatforms(): Promise<this>;
+    cleanAllPlatforms(opts?: {
+        cache?: boolean;
+    } | undefined): Promise<this>;
 }
 export type Volume = import("../types/Volume.ts").Volume;
 export type Config = import("../types/Config.ts").Config;

package/lib/StyleDictionary.js

@@ -78,7 +78,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.0.0';
+  static VERSION = '4.1.0';
 
   /** @returns {Config} */
   get options() {
@@ -110,9 +110,9 @@ export default class StyleDictionary extends Register {
     super();
     this.config = config;
     this.options = {};
-    /** @type {Tokens|TransformedTokens|PreprocessedTokens} */
+    /** @type {PreprocessedTokens} */
     this.tokens = {};
-    /** @type {TransformedToken[]} */
+    /** @type {PreprocessedTokens[]} */
     this.allTokens = [];
     /** @type {boolean | undefined} */
     this.usesDtcg = undefined;
@@ -156,6 +156,15 @@ export default class StyleDictionary extends Register {
       this.hasInitializedResolve = resolve;
     });
 
+    /**
+     * Storing the platform specific transformed tokens so we can prevent re-running exportPlatform when we already know the outcome
+     * Same thing for platform specific configs, we don't need to call transformConfig again if we already know the outcome
+     */
+    /** @type {Record<string,Dictionary>} */
+    this._dictionaries = {};
+    /** @type {Record<string,PlatformConfig>} */
+    this._platformConfigs = {};
+
     // By default, always call async extend function when constructing new SD instance
     // However, for testability and managing error handling,
     // you can call constructor with { init: false }
@@ -331,25 +340,28 @@ export default class StyleDictionary extends Register {
         }
       }
     }
+    this.options = { ...this.options, usesDtcg: this.usesDtcg };
 
     // Merge inline, include, and source tokens
-    /** @type {PreprocessedTokens|Tokens} */
-    let tokens = deepExtend([{}, inlineTokens, includeTokens, sourceTokens]);
+    let preprocessedTokens = /** @type {PreprocessedTokens} */ (
+      deepExtend([{}, inlineTokens, includeTokens, sourceTokens])
+    );
+
+    preprocessedTokens = await preprocess(
+      preprocessedTokens,
+      this.preprocessors,
+      this.hooks.preprocessors,
+      this.options,
+    );
     if (this.usesDtcg) {
       // this is where they go from type Tokens -> Preprocessed tokens because the prop $type is removed
-      tokens = typeDtcgDelegate(tokens);
+      preprocessedTokens = typeDtcgDelegate(preprocessedTokens);
     }
-    let preprocessedTokens = /** @type {PreprocessedTokens} */ (tokens);
     if (this.shouldRunExpansion(this.expand)) {
       preprocessedTokens = expandTokens(preprocessedTokens, this.options);
     }
-    this.options = { ...this.options, usesDtcg: this.usesDtcg };
-    this.tokens = await preprocess(
-      preprocessedTokens,
-      this.preprocessors,
-      this.hooks.preprocessors,
-      this.options,
-    );
+    this.tokens = preprocessedTokens;
+    this.allTokens = flattenTokens(/** @type {PreprocessedTokens} */ (this.tokens), this.usesDtcg);
     this.hasInitializedResolve(null);
 
     // For chaining
@@ -378,27 +390,62 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
-   * @returns {Promise<TransformedTokens>}
+   * @param {{ cache?: boolean }} [opts]
    */
-  async exportPlatform(platform) {
-    await this.hasInitialized;
-
+  getPlatformConfig(platform, opts) {
     if (!platform || !this.platforms?.[platform]) {
-      throw new Error('Please supply a valid platform');
+      throw new Error(`Please supply a valid platform, "${platform}" does not exist`);
+    }
+    if (!this._platformConfigs[platform] || opts?.cache === false) {
+      this._platformConfigs[platform] = transformConfig(this.platforms[platform], this, platform);
     }
+    return this._platformConfigs[platform];
+  }
 
-    // We don't want to mutate the original object
-    const platformConfig = transformConfig(this.platforms[platform], this, platform);
+  /**
+   * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
+   */
+  async getPlatformTokens(platform, opts) {
+    if (!this._dictionaries[platform] || opts?.cache === false) {
+      const dictionary = await this._exportPlatform(platform);
+      this._dictionaries[platform] = dictionary;
+    }
+    return this._dictionaries[platform];
+  }
+
+  /**
+   * Public wrapper around _exportPlatform, returns only tokens object
+   * Here for backwards compatibility.
+   * @deprecated use getPlatformTokens instead
+   *
+   * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
+   * @returns {Promise<TransformedTokens>}
+   */
+  async exportPlatform(platform, opts) {
+    const dictionary = await this.getPlatformTokens(platform, opts);
+    return dictionary.tokens;
+  }
+
+  /**
+   * @param {string} platform
+   * @returns {Promise<Dictionary>}
+   */
+  async _exportPlatform(platform) {
+    await this.hasInitialized;
+    const platformConfig = this.getPlatformConfig(platform);
 
     let platformProcessedTokens = /** @type {PreprocessedTokens} */ (this.tokens);
-    if (this.shouldRunExpansion(platformConfig.expand)) {
-      platformProcessedTokens = expandTokens(platformProcessedTokens, this.options, platformConfig);
-    }
+
     platformProcessedTokens = await preprocess(
       platformProcessedTokens,
       platformConfig.preprocessors,
       this.hooks.preprocessors,
     );
+    if (this.shouldRunExpansion(platformConfig.expand)) {
+      platformProcessedTokens = expandTokens(platformProcessedTokens, this.options, platformConfig);
+    }
 
     let exportableResult = /** @type {PreprocessedTokens|TransformedTokens} */ (
       platformProcessedTokens
@@ -538,35 +585,25 @@ export default class StyleDictionary extends Register {
         console.log(chalk.rgb(255, 140, 0).bold(err));
       }
     }
-
-    return exportableResult;
+    return { tokens: exportableResult, allTokens: flattenTokens(exportableResult, this.usesDtcg) };
   }
 
   /**
    * This will get the dictionary / platformConfig for specified platform name
    * Runs transforms, reference resolutions
+   * @deprecated use getPlatformConfig / getPlatformTokens instead
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    * @returns
    */
-  async getPlatform(platform) {
+  async getPlatform(platform, opts) {
     await this.hasInitialized;
-    if (!this.platforms?.[platform]) {
-      throw new Error(`Platform "${platform}" does not exist`);
-    }
-
-    // We don't want to mutate the original object
-    const platformConfig = transformConfig(this.platforms[platform], this, platform);
-
-    // We need to transform the object before we resolve the
-    // variable names because if a value contains concatenated
-    // values like "1px solid {color.border.base}" we want to
-    // transform the original value (color.border.base) before
-    // replacing that value in the string.
-    const tokens = await this.exportPlatform(platform);
-    this.allTokens = /** @type {TransformedToken[]} */ (flattenTokens(tokens, this.usesDtcg));
-    // This is the dictionary object we pass to the file
-    // building and action methods.
-    return { dictionary: { tokens, allTokens: this.allTokens }, platformConfig };
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
+    return {
+      dictionary,
+      platformConfig,
+    };
   }
 
   /**
@@ -755,10 +792,13 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    */
-  async formatPlatform(platform) {
+  async formatPlatform(platform, opts) {
     await this.hasInitialized;
-    const { dictionary, platformConfig } = await this.getPlatform(platform);
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
+
     if (
       platformConfig.buildPath &&
       platformConfig.buildPath.slice(-1) !== '/' &&
@@ -802,7 +842,11 @@ export default class StyleDictionary extends Register {
     return formattedFiles.map(({ output, destination }) => ({ output, destination }));
   }
 
-  async formatAllPlatforms() {
+  /**
+   * @param {{ cache?: boolean }} [opts]
+   * @returns
+   */
+  async formatAllPlatforms(opts) {
     await this.hasInitialized;
     if (!this.platforms) {
       throw new Error('Cannot format platforms due to missing property "platforms" on config');
@@ -812,7 +856,7 @@ export default class StyleDictionary extends Register {
      * @param {string} platformKey
      */
     const getOutputsForPlatform = async (platformKey) => {
-      const outputs = await this.formatPlatform(platformKey);
+      const outputs = await this.formatPlatform(platformKey, opts);
       return { platform: platformKey, outputs };
     };
 
@@ -830,11 +874,13 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    * @returns
    */
-  async buildPlatform(platform) {
+  async buildPlatform(platform, opts) {
     await this.hasInitialized;
-    const { dictionary, platformConfig } = await this.getPlatform(platform);
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
 
     /**
      * @param {string} destination
@@ -850,7 +896,7 @@ export default class StyleDictionary extends Register {
       return this.volume.promises.writeFile(destination, output);
     };
 
-    const files = await this.formatPlatform(platform);
+    const files = await this.formatPlatform(platform, opts);
     if (files) {
       await Promise.all(
         files.map(({ destination, output }) => {
@@ -876,10 +922,14 @@ export default class StyleDictionary extends Register {
     return this;
   }
 
-  async buildAllPlatforms() {
+  /**
+   * @param {{ cache?: boolean }} [opts]
+   * @returns
+   */
+  async buildAllPlatforms(opts) {
     await this.hasInitialized;
     if (this.platforms) {
-      await Promise.all(Object.keys(this.platforms).map((key) => this.buildPlatform(key)));
+      await Promise.all(Object.keys(this.platforms).map((key) => this.buildPlatform(key, opts)));
     }
     // For chaining
     return this;
@@ -887,10 +937,12 @@ export default class StyleDictionary extends Register {
 
   /**
    * @param {string} platform
+   * @param {{ cache?: boolean }} [opts]
    * @returns
    */
-  async cleanPlatform(platform) {
-    const { dictionary, platformConfig } = await this.getPlatform(platform);
+  async cleanPlatform(platform, opts) {
+    const platformConfig = this.getPlatformConfig(platform, opts);
+    const dictionary = await this.getPlatformTokens(platform, opts);
     // collect logs, cleanFiles happens in parallel but we want to log in sequence
     const logs = await cleanFiles(platformConfig, this.volume);
     if (logs) {
@@ -915,10 +967,14 @@ export default class StyleDictionary extends Register {
     return this;
   }
 
-  async cleanAllPlatforms() {
+  /**
+   * @param {{ cache?: boolean }} [opts]
+   * @returns
+   */
+  async cleanAllPlatforms(opts) {
     await this.hasInitialized;
     if (this.platforms) {
-      await Promise.all(Object.keys(this.platforms).map((key) => this.cleanPlatform(key)));
+      await Promise.all(Object.keys(this.platforms).map((key) => this.cleanPlatform(key, opts)));
     }
     // For chaining
     return this;

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

@@ -1,3 +1,12 @@
+/**
+ * Split a string comment by newlines and
+ * convert to multi-line comment if necessary
+ * @param {string} to_ret_token
+ * @param {string} comment
+ * @param {Formatting} options
+ * @returns {string}
+ */
+export function addComment(to_ret_token: string, comment: string, options: Formatting): string;
 /**
  * Creates a function that can be used to format a token. This can be useful
  * to use as the function on `dictionary.allTokens.map`. The formatting

package/lib/common/formatHelpers/createPropertyFormatter.js

@@ -40,7 +40,7 @@ const defaultFormatting = {
  * @param {Formatting} options
  * @returns {string}
  */
-function addComment(to_ret_token, comment, options) {
+export function addComment(to_ret_token, comment, options) {
   const { commentStyle, indentation } = options;
   let { commentPosition } = options;
 

package/lib/common/formatHelpers/fileHeader.js

@@ -12,6 +12,7 @@
  */
 
 /**
+ *
  * @typedef {import('../../../types/File.ts').File} File
  * @typedef {import('../../../types/File.ts').FileHeader} FileHeader
  * @typedef {import('../../../types/File.ts').FormattingOptions} Formatting

package/lib/common/formats.d.ts

@@ -1,7 +1,7 @@
 export default formats;
 export type Format = import("../../types/Format.ts").Format;
 export type FormatArgs = import("../../types/Format.ts").FormatFnArguments;
-export type FormattingOptions = import("../../types/File").FormattingOptions;
+export type FormattingOverrides = import("../../types/File").FormattingOverrides;
 export type OutputReferences = import("../../types/Format.ts").OutputReferences;
 export type Token = import("../../types/DesignToken.ts").TransformedToken;
 export type Tokens = import("../../types/DesignToken.ts").TransformedTokens;

package/lib/common/formats.js

@@ -49,7 +49,7 @@ import plistTemplate from './templates/ios/plist.template.js';
 /**
  * @typedef {import('../../types/Format.ts').Format} Format
  * @typedef {import('../../types/Format.ts').FormatFnArguments} FormatArgs
- * @typedef {import('../../types/File').FormattingOptions} FormattingOptions
+ * @typedef {import('../../types/File').FormattingOverrides} FormattingOverrides
  * @typedef {import('../../types/Format.ts').OutputReferences} OutputReferences
  * @typedef {import('../../types/DesignToken.ts').TransformedToken} Token
  * @typedef {import('../../types/DesignToken.ts').TransformedTokens} Tokens
@@ -60,11 +60,13 @@ import plistTemplate from './templates/ios/plist.template.js';
  */
 
 /**
- * remove prefix because the prefix option for createPropertyFormatting is not the same as the prefix inside header comment
- * @param {FormattingOptions} [formatting]
+ * Remove prefix because the prefix option for createPropertyFormatter
+ * is not the same as the prefix inside header comment
+ * @param {FormattingOverrides} [formatting]
  */
 function getFormattingCloneWithoutPrefix(formatting) {
   const formattingWithoutPrefix = structuredClone(formatting) ?? {};
+  // @ts-expect-error users are not supposed to pass "prefix" but they might because it used to be supported
   delete formattingWithoutPrefix.prefix;
   return formattingWithoutPrefix;
 }

package/lib/common/templates/scss/map-deep.template.js

@@ -12,6 +12,7 @@
  * @param {number} depth
  */
 function processJsonNode(obj, options, depth = 0) {
+  const indent = options.formatting?.indentation ?? '  ';
   let output = '';
   if (obj === null) {
     output += `''`;
@@ -22,15 +23,18 @@ function processJsonNode(obj, options, depth = 0) {
     output += `$${obj.name}`;
   } else {
     // if we have found a group of tokens, use the Sass group "(...)" syntax and loop -recursively- on the children
-    output += '(\n';
+    output += `(\n`;
     output += Object.keys(obj)
       .map(function (newKey) {
         const newProp = obj[newKey];
-        const indent = '  '.repeat(depth + 1);
-        return `${indent}'${newKey}': ${processJsonNode(newProp, options, depth + 1)}`;
+        return `${indent.repeat(depth + 1)}'${newKey}': ${processJsonNode(
+          newProp,
+          options,
+          depth + 1,
+        )}`;
       })
-      .join(',\n');
-    output += '\n' + '  '.repeat(depth) + ')';
+      .join(`,\n`);
+    output += `\n` + indent.repeat(depth) + ')';
   }
   return output;
 }
@@ -41,6 +45,8 @@ function processJsonNode(obj, options, depth = 0) {
  *   options: Config & LocalOptions
  * }} opts
  */
-export default ({ dictionary, options }) => `
+export default ({ dictionary, options }) => {
+  return `
 $${options.mapName ?? 'tokens'}: ${processJsonNode(dictionary.tokens, options)};
 `;
+};

package/lib/common/templates/scss/map-flat.template.js

@@ -1,3 +1,5 @@
+import { addComment } from '../../formatHelpers/createPropertyFormatter.js';
+
 /**
  * @typedef {import('../../../../types/DesignToken.ts').TransformedToken} TransformedToken
  * @typedef {import('../../../../types/Config.ts').Config} Config
@@ -11,14 +13,24 @@
  *   header: string
  * }} opts
  */
-export default ({ allTokens, options, header }) => `
-${header}$${options.mapName ?? 'tokens'}: (
-${allTokens
-  .map(
-    (token) =>
-      `${token.comment ? `  // ${token.comment}\n` : ''}  '${token.name}': ${
+export default ({ allTokens, options, header }) => {
+  const _f = options.formatting ?? {};
+  const f = {
+    ..._f,
+    indentation: _f.indentation ?? '  ',
+    commentStyle: _f.commentStyle ?? 'short',
+    commentPosition: _f.commentPosition ?? 'above',
+  };
+  return `
+${header}$${options.mapName ?? 'tokens'}: (\n${allTokens
+    .map((token, i, arr) => {
+      const tokenString = `${f.indentation}'${token.name}': ${
         options.usesDtcg ? token.$value : token.value
-      }`,
-  )
-  .join(',\n')}
-);`;
+      }${i !== arr.length - 1 ? ',' : ''}`;
+      if (token.comment && f.commentStyle !== 'none') {
+        return addComment(tokenString, token.comment, f);
+      }
+      return tokenString;
+    })
+    .join(`\n`)}\n);`;
+};

package/lib/common/transforms.js

@@ -832,6 +832,7 @@ export default {
       }
       const parsedVal = parseFloat(nonParsed);
       if (isNaN(parsedVal)) throwSizeError(token.name, nonParsed, 'rem');
+      if (parsedVal === 0) return Number.isInteger(nonParsed) ? 0 : '0';
       return parsedVal + 'rem';
     },
   },

package/lib/fs.d.ts

@@ -3,6 +3,8 @@
  */
 /**
  * Allow to be overridden by setter, set default to memfs for browser env, node:fs for node env
+ * Default CJS export when converted to ESM, messes up the types a bit so we need to
+ * cast the default import to type of Volume by first casting to unknown...
  */
 export let fs: Volume;
 export function setFs(_fs: Volume, isNodeFS?: boolean | undefined): void;

package/lib/fs.js

@@ -6,8 +6,10 @@ import memfs from '@bundled-es-modules/memfs';
 
 /**
  * Allow to be overridden by setter, set default to memfs for browser env, node:fs for node env
+ * Default CJS export when converted to ESM, messes up the types a bit so we need to
+ * cast the default import to type of Volume by first casting to unknown...
  */
-export let fs = /** @type {Volume} */ (memfs);
+export let fs = /** @type {Volume} */ (/** @type {unknown} */ (memfs));
 
 /**
  * since ES modules exports are read-only, use a setter

package/lib/utils/combineJSON.js

@@ -33,7 +33,7 @@ import { detectDtcgSyntax } from './detectDtcgSyntax.js';
 function traverseObj(obj, fn) {
   for (let key in obj) {
     const prop = obj[key];
-    if (prop) {
+    if (prop != null) {
       fn.apply(null, [obj, key, prop]);
       if (typeof prop === 'object') {
         traverseObj(prop, fn);

package/lib/utils/expandObjectTokens.js

@@ -211,7 +211,13 @@ function expandTokensRecurse(slice, original, opts, platform) {
     if (value) {
       // if our token is a ref, we have to resolve it first in order to expand its value
       if (typeof value === 'string' && usesReferences(value)) {
-        value = resolveReferences(value, original, { usesDtcg: uses$ });
+        try {
+          value = resolveReferences(value, original, { usesDtcg: uses$ });
+        } catch (e) {
+          // do nothing, references may be broken but now is not the time to
+          // complain about it, as we're just doing this here so we can expand
+          // tokens that reference object-value tokens that need to be expanded
+        }
       }
 
       if (

package/lib/utils/groupMessages.d.ts

@@ -1,4 +1,4 @@
-export const verbosityInfo: "Use log.verbosity \"verbose\" or use CLI option --verbose for more details.";
+export const verbosityInfo: "Use log.verbosity \"verbose\" or use CLI option --verbose for more details.\nRefer to: https://styledictionary.com/reference/logging/";
 export class GroupMessages {
     /** @type {{[key: string]: string[]}} */
     groupedMessages: {

package/lib/utils/groupMessages.js

@@ -11,7 +11,7 @@
  * and limitations under the License.
  */
 
-export const verbosityInfo = `Use log.verbosity "verbose" or use CLI option --verbose for more details.`;
+export const verbosityInfo = `Use log.verbosity "verbose" or use CLI option --verbose for more details.\nRefer to: https://styledictionary.com/reference/logging/`;
 
 export class GroupMessages {
   constructor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "style-dictionary",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Style once, use everywhere. A build system for creating cross-platform styles.",
   "keywords": [
     "style dictionary",
@@ -59,6 +59,8 @@
     "test:coverage": "cd coverage/lcov-report && npx http-server -o -c-1",
     "test:update-snapshots": "web-test-runner --update-snapshots",
     "test:node": "mocha -r mocha-hooks.mjs './__integration__/**/*.test.js' './__tests__/**/*.test.js' './__node_tests__/**/*.test.js'",
+    "test:perf": "mocha -r mocha-hooks.mjs './__perf_tests__/**/*.test.js'",
+    "test:perf:debug": "web-test-runner --config wtr-perf.config.mjs --watch",
     "install-cli": "npm install -g $(npm pack)",
     "release": "npm run build && changeset publish",
     "prepare": "husky install",
@@ -102,7 +104,7 @@
   "dependencies": {
     "@bundled-es-modules/deepmerge": "^4.3.1",
     "@bundled-es-modules/glob": "^10.4.2",
-    "@bundled-es-modules/memfs": "^4.8.1",
+    "@bundled-es-modules/memfs": "^4.9.4",
     "@zip.js/zip.js": "^2.7.44",
     "chalk": "^5.3.0",
     "change-case": "^5.3.0",
@@ -147,7 +149,6 @@
     "lint-staged": "^12.3.1",
     "lit": "^3.1.2",
     "mdast": "^3.0.0",
-    "memfs": "^4.6.0",
     "mermaid": "^10.9.1",
     "mocha": "^10.2.0",
     "monaco-editor": "^0.47.0",

package/types/Config.d.ts

@@ -1,6 +1,6 @@
 import type { DesignToken, DesignTokens, PreprocessedTokens } from './DesignToken.ts';
 import type { Filter } from './Filter.ts';
-import type { FileHeader, File, FormattingOptions } from './File.ts';
+import type { FileHeader, File, FormattingOverrides } from './File.ts';
 import type { Parser } from './Parser.ts';
 import type { Preprocessor } from './Preprocessor.ts';
 import type { Transform } from './Transform.ts';
@@ -21,7 +21,7 @@ export interface LocalOptions {
     fileHeader?: string | FileHeader;
     outputReferences?: OutputReferences;
     outputReferenceFallbacks?: boolean;
-    formatting?: FormattingOptions;
+    formatting?: FormattingOverrides;
     [key: string]: any;
 }
 export interface RegexOptions {
@@ -80,7 +80,7 @@ export interface Config {
     hooks?: Hooks;
     expand?: ExpandConfig;
     platforms?: Record<string, PlatformConfig>;
-    parsers?: Parser[];
+    parsers?: string[];
     preprocessors?: string[];
     usesDtcg?: boolean;
 }

package/types/File.d.ts

@@ -2,16 +2,18 @@ import type { TransformedToken } from './DesignToken.ts';
 import type { FormatFn } from './Format.ts';
 import type { LocalOptions, Config } from './Config.ts';
 import type { Filter } from './Filter.ts';
-export interface FormattingOptions {
+export interface FormattingOptions extends FormattingOverrides {
     prefix?: string;
     suffix?: string;
     lineSeparator?: string;
-    header?: string;
-    footer?: string;
+    separator?: string;
+}
+export interface FormattingOverrides {
     commentStyle?: 'short' | 'long' | 'none';
     commentPosition?: 'above' | 'inline';
     indentation?: string;
-    separator?: string;
+    header?: string;
+    footer?: string;
     fileHeaderTimestamp?: boolean;
 }
 export type FileHeader = (defaultMessage: string[], options?: Config) => Promise<string[]> | string[];

package/types/Volume.d.ts

@@ -1,4 +1,4 @@
-import type { IFs } from 'memfs';
-export type Volume = (IFs | typeof import('node:fs')) & {
+import type { Volume as _Volume } from '@bundled-es-modules/memfs';
+export type Volume = (InstanceType<typeof _Volume> | typeof import('node:fs')) & {
     __custom_fs__?: boolean;
 };

package/types/typeless-modules/bundled-memfs.d.ts

@@ -1 +0,0 @@
-declare module '@bundled-es-modules/memfs';