v4.0.0-prerelease.10

Patch Changes

• 0c1a36f: Fix small issue in type w3c delegate utility type tracking.
• 0c1a36f: Expose typeW3CDelegate utility. Don't take "value" into account anymore to determine that it's a design token, use $value.

v4.0.0-prerelease.9

Minor Changes

• 294fd0e: Support W3C Draft specification for Design Tokens, by adding support for $value, $type and $description properties.

Patch Changes

• 3138313: Allow transitive transforms to return undefined, by doing this the transformer can mark itself as "deferred" for that specific token. This is useful when references in properties other than "value" need to be resolved first.

v4.0.0-prerelease.8

Patch Changes

• 59f3eb0: Expose flattenTokens utility.
• 39547fb: Fix parsers async support, use resolved filePath instead of raw.

v4.0.0-prerelease.7

Minor Changes

• 0410295: Improve and test the error handling of standalone usage of reference utilities.

v4.0.0-prerelease.6

Patch Changes

• 1dd828c: Fix issue in browser-bundled glob, bump.

v4.0.0-prerelease.5

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']

Patch Changes

• e859036: Fix Windows support by using a Linux/Windows + Node/Browser compatible path utility. Upgrade to latest Glob version. Apply posix: true to prevent breaking change glob update.

v4.0.0-prerelease.4

Minor Changes

• 122c8f6: Expose a new utility called resolveReferences which takes a value containing references, the dictionary object, and resolves the value's references for you.

  import StyleDictionary from 'style-dictionary';
  import { resolveReferences } from 'style-dictionary/utils';
  
  const sd = new StyleDictionary({
    tokens: {
      foo: { value: 'foo' },
      bar: { value: '{foo}' },
      qux: { value: '{bar}' },
    },
  });
  
  console.log(resolveReferences(sd.tokens.qux.value, sd.tokens)); // 'foo'

• 122c8f6: BREAKING: expose getReferences and usesReference utilities as standalone utils rather than requiring them to be bound to dictionary object. This makes it easier to use.

Patch Changes

• 044123c: Patch StyleDictionary main type file to export default instead of "export =" which does not work in ESM.

v4.0.0-prerelease.3

Patch Changes

• 8d2f6d8: Make sure fs-node.js file is published to NPM.

v4.0.0-prerelease.2

Major Changes

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

• a4542f4: BREAKING: StyleDictionary to be initialized with a new API and have async methods. Use:

  import StyleDictionary from 'style-dictionary';
  
  /**
   * old:
   *   const sd = StyleDictionary.extend({ source: ['tokens.json'], platforms: {} });
   *   sd.buildAllPlatforms();
   */
  const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
  await sd.buildAllPlatforms();

  You can still extend a dictionary instance with an extended config, but .extend() is only used for this, it is no longer used to initialize the first instance:

  import StyleDictionary from 'style-dictionary';
  
  const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
  const extended = await sd.extend({
    fileHeader: {
      myFileHeader: (defaultMessage) => {
        return [...defaultMessage, 'hello, world!'];
      },
    },
  });

  To ensure your initialized StyleDictionary instance is fully ready and has imported all your tokens, you can await hasInitialized:

  import StyleDictionary from 'style-dictionary';
  
  const sd = new StyleDictionary({ source: ['tokens.json'], platforms: {} });
  await sd.hasInitialized;
  console.log(sd.allTokens);

  For error handling and testing purposes, you can also manually initialize the style-dictionary config:

  import StyleDictionary from 'style-dictionary';
  
  const sd = new StyleDictionary({ source: ['tokens.js'], platforms: {} }, { init: false });
  try {
    await sd.init();
  } catch (e) {
    // handle error, e.g. when tokens.js file has syntax errors and cannot be imported
  }
  console.log(sd.allTokens);

  The main reason for an initialize step after class instantiation is that async constructors are not a thing in JavaScript, and if you return a promise from a constructor to "hack it", TypeScript will eventually trip over it.

  Due to being able to dynamically (asynchronously) import ES Modules rather than synchronously require CommonJS modules, we had to make the APIs asynchronous, so the following methods are now async:

  • extend
  • exportPlatform
  • buildAllPlatforms & buildPlatform
  • cleanAllPlatforms & cleanPlatform

  In a future release, most other methods will be made async or support async as well, such as parsers, transforms, formats etc.

Minor Changes

• cedf8a0: Preprocessors are a new feature added to style-dictionary, which allows you to do any type of processing of the token dictionary after parsing, before resolving and transforming.
  See preprocessor docs for more information.
• a4542f4: options.log to be respected in all error logging, including platform specific logs.

v4.0.0-prerelease.1

Patch Changes

• c1dd5ec: Allow overriding CSS formatting with commentStyle and commentPosition props.
  For commentStyle, options are 'short' or 'long'.
  For commentPosition, options are 'above' or 'inline'.

  We also ensure that the right defaults are picked for CSS, SASS/SCSS, Stylus and Less.

  This also contains a fix for ensuring that multi-line comments are automatically put "above" rather than "inline".

• 6fb81ad: Allow falsy token values for outputReferences, e.g. 0.

• 24d41c3: Allow outputReferences to work on non-string values.