v4.0.0

For a more comprehensive migration guide from version 3.x.x to version 4.0.0,
visit the migration guide page

Major Changes

• 6cc7f31: BREAKING:

  • usesReference util function is now usesReferences to be consistent plural form like the other reference util functions.

  • getReferences first and second parameters have been swapped to be consistent with resolveReferences, so value first, then the full token object (instead of the entire dictionary instance).

  • getReferences accepts a third options parameter which can be used to set reference Regex options as well as an unfilteredTokens object which can be used as a fallback when references are made to tokens that have been filtered out. There will be warnings logged for this.

  • format.formatter removed old function signature of (dictionary, platform, file) in favor of ({ dictionary, platform, options, file }).

  • Types changes:

    • Style Dictionary is entirely strictly typed now, and there will be .d.ts files published next to every file, this means that if you import from one of Style Dictionary's entrypoints, you automatically get the types implicitly with it. This is a big win for people using TypeScript, as the majority of the codebase now has much better types, with much fewer anys.
    • There is no more hand-written Style Dictionary module index.d.ts anymore that exposes all type interfaces on itself. This means that you can no longer grab types that aren't members of the Style Dictionary class directly from the default export of the main entrypoint. External types such as Parser, Transform, DesignTokens, etc. can be imported from the newly added types entrypoint:

    import type { DesignTokens, Transform, Parser } from 'style-dictionary/types';

    Please raise an issue if you find anything missing or suddenly broken.

    • Matcher, Transformer, Formatter, etc. are still available, although no longer directly but rather as properties on their parents, so Filter['matcher'], Transform['transformer'], Format['formatter']

• dcbe2fb: - The project has been fully converted to ESM format, which is also the format that the browser uses.
  For users, this means you'll have to either use Style Dictionary in ESM JavaScript code, or dynamically import it into your CommonJS code.

  • StyleDictionary.extend() method is now asynchronous, which means it returns Promise<StyleDictionary.Core> instead of StyleDictionary.Core.
  • allProperties / properties was deprecated in v3, and is now removed from StyleDictionary.Core, use allTokens and tokens instead.
  • Templates and the method registerTemplate were deprecated in v3, now removed. Use Formats instead.
  • The package now uses package entrypoints, which means that what is importable from the package is locked down to just the specified entrypoints: style-dictionary & style-dictionary/fs. If more is needed, please raise an issue explaining which file you were importing and why you need it to be public API.

• f2ed88b: BREAKING: File headers, when registered, are put inside the hooks.fileHeaders property now, as opposed to fileHeader.
  Note the change from singular to plural form here.

  Before:

  export default {
    fileHeader: {
      foo: (defaultMessages = []) => ['Ola, planet!', ...defaultMessages, 'Hello, World!'],
    },
  };

  After:

  export default {
    hooks: {
      fileHeaders: {
        foo: (defaultMessages = []) => ['Ola, planet!', ...defaultMessages, 'Hello, World!'],
      },
    },
  };

• 79bb201: BREAKING: Logging has been redesigned a fair bit and is more configurable now.

  Before:

  {
    "log": "error" // 'error' | 'warn'  -> 'warn' is the default value
  }

  After:

  {
    "log": {
      "warnings": "error", // 'error' | 'warn'  -> 'warn' is the default value
      "verbosity": "verbose", // 'default' | 'verbose' | 'silent'  -> 'default' is the default value
      "errors": {
        "brokenReferences": "console" // 'console' | 'throw' -> 'throw' is the default value
      }
    }
  }

  Log is now and object and the old "log" option is now "warnings".

  This configures whether the following five warnings will be thrown as errors instead of being logged as warnings:

  • Token value collisions (in the source)
  • Token name collisions (when exporting)
  • Missing "undo" function for Actions
  • File not created because no tokens found, or all of them filtered out
  • Broken references in file when using outputReferences, but referring to a token that's been filtered out

  Verbosity configures whether the following warnings/errors should display in a verbose manner:

  • Token collisions of both types (value & name)
  • Broken references due to outputReferences & filters
  • Token reference errors

  And it also configures whether success/neutral logs should be logged at all.
  Using "silent" (or --silent in the CLI) means no logs are shown apart from fatal errors.

• f2ed88b: BREAKING: Actions, when registered, are put inside the hooks.actions property now, as opposed to action.
  Note the change from singular to plural form here.

  Before:

  export default {
    action: {
      'copy-assets': {
        do: () => {}
        undo: () => {}
      }
    },
  };

  After:

  export default {
    hooks: {
      actions: {
        'copy-assets': {
          do: () => {}
          undo: () => {}
        }
      },
    },
  };

• a4542f4: BREAKING: StyleDictionaryInstance.properties & .allProperties have been removed. They were deprecated in v3 in favor of .tokens and .allTokens.

• 5e167de: BREAKING: moved formatHelpers away from the StyleDictionary class and export them in 'style-dictionary/utils' entrypoint instead.

  Before

  import StyleDictionary from 'style-dictionary';
  
  const { fileHeader, formattedVariables } = StyleDictionary.formatHelpers;

  After

  import { fileHeader, formattedVariables } from 'style-dictionary/utils';

• f2ed88b: Filters, when registered, are put inside the hooks.filters property now, as opposed to filter.
  Note the change from singular to plural form here.

  Before:

  export default {
    filter: {
      'colors-only': (token) => token.type === 'color,
    },
    platforms: {
      css: {
        files: [{
          format: 'css/variables',
          destination: '_variables.css',
          filter: 'colors-only',
        }],
      },
    },
  };

  After:

  export default {
    hooks: {
      filters: {
        'colors-only': (token) => token.type === 'color,
      },
    },
    platforms: {
      css: {
        files: [{
          format: 'css/variables',
          destination: '_variables.css',
          filter: 'colors-only',
        }],
      },
    },
  };

  In addition, when using registerFilter method, the name of the filter function is now filter instead of matcher.

  Before:

  import StyleDictionary from 'style-dictionary';
  
  StyleDictionary.registerFilter({
    name: 'colors-only',
    matcher: (token) => token.type === 'color',
  });

  After:

  import StyleDictionary from 'style-dictionary';
  
  StyleDictionary.registerFilter({
    name: 'colors-only',
    filter: (token) => token.type === 'color',
  });

  These changes also apply for the filter function (previously matcher) inside transforms.

• f2ed88b: BREAKING: Transform groups, when registered, are put inside the hooks.transformGroups property now, as opposed to transformGroup.

  Before:

  export default {
    // register it inline or by SD.registerTransformGroup
    transformGroup: {
      foo: ['foo-transform'],
    },
  };

  After:

  export default {
    hooks: {
      transformGroups: {
        foo: ['foo-transform'],
      },
    },
  };

• 502dbd1: BREAKING: All of our hooks, parsers, preprocessors, transforms, formats, actions, fileHeaders and filters, support async functions as well now. This means that the formatHelpers -> fileHeader helper method is now asynchronous, to support async fileheader functions.

  import StyleDictionary from 'style-dictionary';
  
  const { fileHeader } = StyleDictionary.formatHelpers;
  
  StyleDictionary.registerFormat({
    name: 'custom/css',
    // this can be async now, usually it is if you use fileHeader format helper, since that now always returns a Promise
    formatter: async function ({ dictionary, file, options }) {
      const { outputReferences } = options;
      return (
        // this helper is now async! because the user-passed file.fileHeader might be an async function
        (await fileHeader({ file })) +
        ':root {\n' +
        formattedVariables({ format: 'css', dictionary, outputReferences }) +
        '\n}\n'
      );
    },
  });

• f2ed88b: BREAKING: Formats, when registered, are put inside the hooks.formats property now, as opposed to format.
  The formatter handler function has been renamed to format for consistency.

  The importable type interfaces have also been renamed, Formatter is now FormatFn and FormatterArguments is now `FormatFnArgument...

v4.0.0-prerelease.39

Patch Changes

• 894f37c: Update glob esm browser fork to latest, resolve unclear licensing issue.
• cb78c3d: Update typeDtcgDelegate utility to remove the $type on token group level between parsing/preprocessing step.

v4.0.0-prerelease.38

Patch Changes

• 5079154: Fix deepExtend util bug with overriding behavior for tokens.

v4.0.0-prerelease.37

Minor Changes

• 8450a45: Some fixes for Expand utility:

  • Array values such as dashArray property of strokeStyle tokens no longer get expanded unintentionally, typeof 'object' check changed to isPlainObject check.
  • Nested object-value tokens (such as style property inside border tokens) will now also be expanded.
  • When references are involved during expansion, the resolved value is used when the property is an object, if not, then we keep the reference as is.
    This is because if the reference is to an object value, the expansion might break the reference.

v4.0.0-prerelease.36

Minor Changes

• 39f0220: Allow not throwing fatal errors on broken token references/aliases, but console.error instead.

  You can also configure this on global/platform log property:

  {
    "log": {
      "errors": {
        "brokenReferences": "console"
      }
    }
  }

  This setting defaults to "error" when not configured.

  resolveReferences and getReferences warnImmediately option is set to true which causes an error to be thrown/warned immediately by default, which can be configured to false if you know those utils are running in the transform/format hooks respectively, where the errors are collected and grouped, then thrown as 1 error/warning instead of multiple.

  Some minor grammatical improvements to some of the error logs were also done.

v4.0.0-prerelease.35

Minor Changes

• c06661d: Re-add and update example basic, fix copySync command in CLI, fix android templates to use $type for DTCG tokens.

v4.0.0-prerelease.34

Patch Changes

• ba03ee9: Fix for expand utility on platform level to adjust the token's path property.

v4.0.0-prerelease.33

Minor Changes

• 261a2cb: Handle transition timingFunction prop in cubicBezier/css transform. Handle typography fontFamily prop in fontFamily/css transform.

Patch Changes

• 261a2cb: Allow border type tokens to be empty, every property is optional.

v4.0.0-prerelease.32

Minor Changes

• af5cc94: Create formatPlatform and formatAllPlatforms methods.
  This will return the outputs and destinations from the format hook for your dictionary, without building these outputs and persisting them to the filesystem.
  Additionally, formats can now return any data type instead of requiring it to be a string and destination property in files is now optional.
  This allows users to create formats intended for only formatting tokens and letting users do stuff with it during runtime rather than writing to files.

Patch Changes

• 2335f13: Allow using registerHook methods to override hooks that are already registered with the same name.
• 6e226aa: Pass the original ref path to the getReferences util result tokens.
• 3f09277: Pass dictionary options to preprocessor functions.

v4.0.0-prerelease.31

Patch Changes

• c708325: Moving the @zip.js/zip.js dependency from a devDependency to a normal dependency.