Skip to content

Latest commit

 

History

History
1387 lines (1046 loc) · 74.7 KB

CHANGELOG.md

File metadata and controls

1387 lines (1046 loc) · 74.7 KB
Raw

Changelog

4.3.0

Minor Changes

  • 302b466: Introduce a new entrypoint: style-dictionary/enums for most of the library's hard-coded string values. Most of these are built-in hooks names. This provides better type-safety for consumers as well as various maintainability related benefits for this library. See documentation for more info.
  • 5aad797: Add tailwind preset example, remove unused .editorconfig file
  • bd8be17: Add support for native .TS token & config file processing.
  • 209085d: Add tokenMap properties to Dictionary, which is a JavaScript Map structure of the tokens, which makes it easy to iterate as well as access tokens. Also add convertTokenData utility that allows to seemlessly convert between Map, Object or Array of tokens, and deprecate the flattenTokens utility in favor of that one.

Patch Changes

  • 2966cfd: handle DTCG-format tokens in typescript/es6-declarations formatter
  • 4a7bca7: add accessControl field to Android Compose template
  • f694f67: Fix Prettier imports, see https://prettier.io/docs/en/api#custom-parser-api-removed for more info.
  • fd8cdb4: handle DTCG-format tokens in javascript/es6 formatter
  • 6a6a409: Move prettier to dependencies since style-dictionary isn't really a prettier plugin and a direct dependency seems more accurate here.
  • 8a9cfa0: Fix outputReferencesTransformed util, would return true for tokens which original values were not strings.
  • 7a661bb: Fix font-style and font-weight logic for fonts.css.template.js

4.2.0

Minor Changes

  • 0fcf229: Add a new built-in format javascript/esm that outputs an ES module JS default export.
  • d7b5836: Mark javascript/esm as nested, use Prettier on all JavaScript/TypeScript formats, use 3.x.x peerDependency so the user's installation is used when possible.
  • 4bf68a3: Apply stripMeta from "json" format to the new "javascript/esm" as well.
  • 8f1b4f0: Add new utility in style-dictionary/utils -> stripMeta for stripping metadata from tokens. This utility is used now as an opt-in for the built-in 'json' format by using options.stripMeta, which if set to true will strip Style Dictionary meta props. You can specify keep/strip (allow/blocklist) for granular control about which properties to keep or strip.

Patch Changes

  • 5e3a5af: Update .d.ts/js files type imports to use correct extensions rather than extensionless. This fixes some incompatibilities with latest TypeScript "NodeNext" moduleResolution.

4.1.4

Patch Changes

  • a67ed31: Pass PlatformConfig as options param to platform-applied preprocessors.
  • 19aee32: Fix convertToBase64 util to support converting binary files such as fonts, for both Browser and NodeJS.

4.1.3

Patch Changes

  • 9376247: Make defaultMessage param in FileHeader type optional.
  • 43ccb42: (#1305): fix reference sorting in sortByReference function for DTCG token format, ensuring token references are declared after their targets
  • 26728b9: Fix filterTokens utility to deal with random metadata properties throughout token groups, without throwing errors.

4.1.2

Patch Changes

  • e9cce6a: Reuse static hooks in the constructor to set instance hooks prop, to avoid discarding built-in hooks overwrites by consumers.
  • b48d0e9: Add missing type interfaces, most notably the ExpandConfig types.

4.1.1

Patch Changes

  • 5db3521: Add iosSwiftEnumOpts.className and iosSwiftAnyOpts.className formats property documentation
  • 23f8a25: Use cp and rmdir commands for copy_assets do and undo methods, since they affect directories, not files.

4.1.0

Minor Changes

  • ccf27b7: Prevent duplicate redundant calls to StyleDictionary class methods by caching platform specific config & tokens results.

    Added reusable methods:

    • getPlatformTokens() -> grabs the tokens/allTokens(new! exportPlatform does not return this) for a specific platform, after running platform specific preprocessors and transforms. This replaces the old exportPlatform method which is now deprecated and will be removed in v5.
    • getPlatformConfig() -> grabs the processed/transformed PlatformConfig for a specific platform, replaces the now deprecated getPlatform method which will be removed in v5.

    The reasons for deprecating those methods and replacing them with new ones is to reduce method ambiguity and make them more pure.

    Add new options object to methods:

    • getPlatformTokens
    • getPlatformConfig
    • exportPlatform (deprecated, see above)
    • getPlatform (deprecated, see above)
    • formatPlatform
    • formatAllPlatforms
    • buildPlatform
    • buildAllPlatforms
    • cleanPlatform
    • cleanAllPlatforms

    with property cache, which if set to false, will disable this caching of generating the platform specific config / tokens, e.g.:

    await sd.exportPlatform('css', { cache: false });
await sd.buildAllPlatforms('css', { cache: false });

    Expectation is that this is usually not useful for majority of users, unless for example you're testing multiple runs of StyleDictionary while changing tokens or platform configs in between those runs.

Patch Changes

  • 2ec9a44: size/rem transform to leave 0 (string or number) values as is, since 0 doesn't need a unit.

  • f317430: Added link to logging documentation inside all of the warnings and errors that refer to verbosity.

  • 6275983: Respect formatting options in scss map-deep/map-flat formats, those that make sense:

    • commentPosition
    • commentStyle
    • indentation

    Also export a new type interface FormattingOverrides, which is a limited version of FormattingOptions. These contain the formatting options that can be overridden by users, whereas the full version is meant for the format helper utilities such as createPropertyFormatter/formattedVariables.

4.0.1

Patch Changes

  • e6cbf73: Fix type information for Config.parser
  • e8aea2f: Fix transitive color transform advanced example, migrate chroma-js to colorjs.io
  • 7afcffd: Fix bugs with expand tokens where they would run before instead of after user-configured preprocessors, and would fatally error on broken references. Broken refs should be tolerated at the expand stage, and errors will be thrown after preprocessor lifecycle if the refs are still broken at that point.
  • 922b6aa: Update memfs esm-fork dependency to allow named import Volume.
  • 61b6984: Fix 'filePath' missing from falsy token values
  • 3ae67e3: Upgrade memfs esm fork to publish types and bumping stream to fix unclear licensing issue with transitive dependency.

4.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 FormatFnArguments. Note that you can also use Format['format'] instead of FormatFn, or Parameters<Format['format']> instead of FormatFnArguments, so these renames may not matter.

    Before:

    import StyleDictionary from 'style-dictionary';
import type { Formatter, FormatterArguments } from 'style-dictionary/types';

// register it with register method
StyleDictionary.registerFormat({
  name: 'custom/json',
  formatter: ({ dictionary }) => JSON.stringify(dictionary, null, 2),
});

export default {
  // OR define it inline
  format: {
    'custom/json': ({ dictionary }) => JSON.stringify(dictionary, null, 2),
  },
  platforms: {
    json: {
      files: [
        {
          destination: 'output.json',
          format: 'custom/json',
        },
      ],
    },
  },
};

    After:

    import StyleDictionary from 'style-dictionary';
import type { FormatFn, FormatFnArguments } from 'style-dictionary/types';

// register it with register method
StyleDictionary.registerFormat({
  name: 'custom/json',
  format: ({ dictionary }) => JSON.stringify(dictionary, null, 2),
});

export default {
  // OR define it inline
  hooks: {
    formats: {
      'custom/json': ({ dictionary }) => JSON.stringify(dictionary, null, 2),
    },
  },
  platforms: {
    json: {
      files: [
        {
          destination: 'output.json',
          format: 'custom/json',
        },
      ],
    },
  },
};

  • e83886c: BREAKING: preprocessors must now also be explicitly applied on global or platform level, rather than only registering it. This is more consistent with how the other hooks work and allows applying it on a platform level rather than only on the global level.

    preprocessors property that contains the registered preprocessors has been moved under a wrapping property called hooks.

    Before:

    export default {
  // register it inline or by SD.registerPreprocessor
  // applies automatically, globally
  preprocessors: {
    foo: (dictionary) => {
      // preprocess it
      return dictionary;
    },
  },
};

    After:

    export default {
  // register it inline or by SD.registerPreprocessor
  hooks: {
    preprocessors: {
      foo: (dictionary) => {
        // preprocess it
        return dictionary;
      },
    },
  },
  // apply it globally
  preprocessors: ['foo'],
  platforms: {
    css: {
      // or apply is per platform
      preprocessors: ['foo'],
    },
  },
};

  • 2f80da2: BREAKING: className, packageName, mapName, type, name, resourceType and resourceMap options for a bunch of built-in formats have been moved from file to go inside the file.options object, for API consistency reasons.

    Before:

    {
  "files": [
    {
      "destination": "tokenmap.scss",
      "format": "scss/map-deep",
      "mapName": "tokens"
    }
  ]
}

    After:

    {
  "files": [
    {
      "destination": "tokenmap.scss",
      "format": "scss/map-deep",
      "options": {
        "mapName": "tokens"
      }
    }
  ]
}

  • f2ed88b: BREAKING: Transforms, when registered, are put inside the hooks.transforms property now, as opposed to transform. The matcher property has been renamed to filter (to align with the Filter hook change), and the transformer handler function has been renamed to transform for consistency.

    Before:

    export default {
  // register it inline or by SD.registerTransform
  transform: {
    'color-transform': {
      type: 'value',
      matcher: (token) => token.type === 'color',
      transformer: (token) => token.value,
    },
  },
  platforms: {
    css: {
      // apply it per platform
      transforms: ['color-transform'],
    },
  },
};

    After

    export default {
  // register it inline or by SD.registerTransform
  hooks: {
    transforms: {
      'color-transform': {
        type: 'value',
        filter: (token) => token.type === 'color',
        transform: (token) => token.value,
      },
    },
  },
  platforms: {
    css: {
      // apply it per platform
      transforms: ['color-transform'],
    },
  },
};

  • 90095a6: BREAKING: Allow specifying a function for outputReferences, conditionally outputting a ref or not per token. Also exposes outputReferencesFilter utility function which will determine whether a token should be outputting refs based on whether those referenced tokens were filtered out or not.

    If you are maintaining a custom format that allows outputReferences option, you'll need to take into account that it can be a function, and pass the correct options to it.

    Before:

    StyleDictionary.registerFormat({
  name: 'custom/es6',
  formatter: async (dictionary) => {
    const { allTokens, options, file } = dictionary;
    const { usesDtcg } = options;

    const compileTokenValue = (token) => {
      let value = usesDtcg ? token.$value : token.value;
      const originalValue = usesDtcg ? token.original.$value : token.original.value;

      // Look here 👇
      const shouldOutputRefs = outputReferences && usesReferences(originalValue);

      if (shouldOutputRefs) {
        // ... your code for putting back the reference in the output
        value = ...
      }
      return value;
    }
    return `${allTokens.reduce((acc, token) => `${acc}export const ${token.name} = ${compileTokenValue(token)};\n`, '')}`;
  },
});

    After

    StyleDictionary.registerFormat({
  name: 'custom/es6',
  formatter: async (dictionary) => {
    const { allTokens, options, file } = dictionary;
    const { usesDtcg } = options;

    const compileTokenValue = (token) => {
      let value = usesDtcg ? token.$value : token.value;
      const originalValue = usesDtcg ? token.original.$value : token.original.value;

      // Look here 👇
      const shouldOutputRefs =
        usesReferences(original) &&
        (typeof options.outputReferences === 'function'
          ? outputReferences(token, { dictionary, usesDtcg })
          : options.outputReferences);

      if (shouldOutputRefs) {
        // ... your code for putting back the reference in the output
        value = ...
      }
      return value;
    }
    return `${allTokens.reduce((acc, token) => `${acc}export const ${token.name} = ${compileTokenValue(token)};\n`, '')}`;
  },
});

  • 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.

  • 0b81a08: BREAKING: no longer wraps tokens of type asset in double quotes. Rather, we added a transform asset/url that will wrap such tokens inside url("") statements, this transform is applied to transformGroups scss, css and less.

  • 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.

  • f2ed88b: BREAKING: Parsers, when registered, are put inside the hooks.parsers property now, as opposed to parsers. parsers property has been repurposed: you will now also need to explicitly apply registered parsers by name in the parsers property, they no longer apply by default. When registering a parser, you must also supply a name property just like with all other hooks, and the parse function has been renamed to parser for consistency.

    Before:

    export default {
  // register it inline or by SD.registerPreprocessor
  parsers: [
    {
      pattern: /\.json5$/,
      parse: ({ contents, filePath }) => {
        return JSON5.parse(contents);
      },
    },
  ],
};

    After:

    export default {
  hooks: {
    parsers: {
      name: 'json5-parser',
      pattern: /\.json5$/,
      parser: ({ contents, filePath }) => {
        return JSON5.parse(contents);
      },
    },
  },
  // apply it globally by name reference
  parsers: ['json5-parser'],
};

  • bcb5ef3: Remove reliance on CTI token structure across transforms, actions and formats.

    Breaking changes:

    • Token type will now be determined by "type" (or "$type") property on the token, rather than by checking its CTI attributes. This change has been reflected in all of the format templates as well as transform "matcher" functions that were previously checking attributes.category as the token type indicator.
    • Types are mostly aligned with DTCG spec types, although a few additional ones have been added for compatibility reasons:
      • asset -> string type tokens where the value is a filepath to an asset
      • icon -> content type string tokens where the content resembles an icon, e.g. for icon fonts like Microsoft codicons
      • html -> HTML entity strings for unicode characters
      • content -> regular string content e.g. text content which sometimes needs to be wrapped in quotes
    • Built-in name transforms are now reliant only on the token path, and are renamed from name/cti/casing to just name/casing. name/ti/camel and name/ti/constant have been removed. For example name/cti/kebab transform is now name/kebab.
    • Transform content/icon has been renamed to html/icon since it targets HTML entity strings, not just any icon content.
    • font/objC/literal, font/swift/literal and font/flutter/literal have been removed in favor of font/objC/literal, font/swift/literal and font/flutter/literal, as they do he exact same transformations.
    • typescript/module-declarations format to be updated with current DesignToken type interface.

    Before:

    {
  "color": {
    "red": {
      "value": "#FF0000"
    }
  }
}

    After:

    {
  "color": {
    // <-- this no longer needs to be "color" in order for the tokens inside this group to be considered of type "color"
    "red": {
      "value": "#FF0000",
      "type": "color"
    }
  }
}

  • 7b82150: BREAKING: For formats using the fileHeader formatHelpers utility, it will no longer display a timestamp in the fileHeader output by default. This is now an opt-in by setting file.formatting.fileHeaderTimestamp to true. The reason for making this opt-in now is that using Style Dictionary in the context of a CI (continuous integration) pipeline is a common use-case, and when running on pull request event, output files always show a diff in git due to the timestamp changing, which often just means that the diff is bloated by redundancy.

    New:

    {
  "platforms": {
    "css": {
      "files": [
        {
          "destination": "variables.css",
          "format": "css/variables",
          "options": {
            "formatting": {
              "fileHeaderTimestamp": true
            }
          }
        }
      ]
    }
  }
}

    or:

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

const headerContent = await fileHeader({ formatting: { fileHeaderTimestamp: true } });

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.

  • 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.

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

  • dcbe2fb: FileSystem that is used by Style Dictionary can now be customized:

    import { setFs } from 'style-dictionary/fs';
setFs(myFileSystemShim);

    By default, it uses an in-memory filesystem shim @bundled-es-modules/memfs in browser context, node:fs built-in module in Node context.

  • 3485467: Fix some inconsistencies in some of the templates, usually with regards to spaces/newlines

  • 606af51: Rename typeW3CDelegate utility function to typeDtcgDelegate, as using "W3C" is highly discouraged when the standard isn't a W3C standard yet.

  • 4225d78: Added the following transforms for CSS, and added them to the scss, css and less transformGroups:

    • fontFamily/css -> wraps font names with spaces in ' quotes
    • cubicBezier/css -> array value, put inside cubic-bezier() CSS function
    • strokeStyle/css/shorthand -> object value, transform to CSS shorthand
    • border/css/shorthand -> object value, transform to CSS shorthand
    • typography/css/shorthand -> object value, transform to CSS shorthand
    • transition/css/shorthand -> object value, transform to CSS shorthand
    • shadow/css/shorthand -> object value (or array of objects), transform to CSS shorthand

    The main intention here is to ensure that Style Dictionary is compliant with DTCG draft specification out of the box with regards to exporting to CSS, where object-value tokens are not supported without transforming them to shorthands (or expanding them, which is a different feature that was added in 4.0.0-prerelease.27).

  • 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.

  • cb94554: 'size/rem' transform to not transform tokens that already have a unit, such as "4px", this should not be transformed to "4rem".

  • a4542f4: options.log to be respected in all error logging, including platform specific logs.

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

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

  • 8b6fff3: Fixes some noisy warnings still being outputted even when verbosity is set to default.

    We also added log.warning "disabled" option for turning off warnings altogether, meaning you only get success logs and fatal errors. This option can be used from the CLI as well using the --no-warn flag.

  • 2da5130: Added outputReferencesTransformed utility function to pass into outputReferences option, which will not output references for values that have been transitively transformed.

  • 606af51: Support the use of "value"/"type"/"description" as token names or token group names, at the sacrifice of now no longer being able to combine non-DTCG and DTCG syntax within the same token dictionary.

  • 7418c97: Add a couple of utilities for converting a regular Style Dictionary tokens object/file(s) to DTCG formatted tokens:

    • convertToDTCG
    • convertJSONToDTCG
    • convertZIPToDTCG

    Documentation of these utilities

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

  • aff6646: Allow passing a custom FileSystem Volume to your Style Dictionary instances, to ensure input/output files are read/written from/to that specific volume. Useful in case you want multiple Style Dictionary instances that are isolated from one another in terms of inputs/outputs.

    import { Volume } from 'memfs';
// You will need a bundler for memfs in browser...
// Or use as a prebundled fork:
import memfs from '@bundled-es-modules/memfs';
const { Volume } = memfs;

const vol = new Volume();

const sd = new StyleDictionary(
  {
    tokens: {
      colors: {
        red: {
          value: '#FF0000',
          type: 'color',
        },
      },
    },
    platforms: {
      css: {
        transformGroup: 'css',
        files: [
          {
            destination: 'variables.css',
            format: 'css/variables',
          },
        ],
      },
    },
  },
  { volume: vol },
);

await sd.buildAllPlatforms();

vol.readFileSync('/variables.css');
/**
 * :root {
 *   --colors-red: #FF0000;
 * }
 */

    This also works when using extend:

    const extendedSd = await sd.extend(cfg, { volume: vol });

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

  • e83886c: Allow expanding tokens on a global or platform-specific level. Supports conditionally expanding per token type, or using a function to determine this per individual token.

  • 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.

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

  • 4556712: Make css transforms for strokeStyle, cubicBezier and fontFamily transitive, to deal with the use case where they are used within border, transition and typography tokens and those tokens have other properties that contain references.

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.

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

  • 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".

  • 2f80da2: All formats using createPropertyFormatter or formattedVariables helpers now respect the file.options.formatting option passed by users to customize formatting.

    Example:

    {
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath,
      files: [
        {
          destination: 'variables.css',
          format: 'css/variables',
          options: {
            formatting: { indentation: '    ' },
          },
        },
      ]
    }
  }
}

  • 24584b4: Conditionally only run dev scripts when CWD is style-dictionary, so our consumers don't run it by accident

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

  • cb94554: Fix typeDtcgDelegate util $type property position to be allowed anywhere in the object, not just at the top.

  • 8e297d6: Fix outputReferences for DTCG spec tokens, by using token.original.$value instead of token.original.value.

  • 59f3eb0: Expose flattenTokens utility.

  • 72f020d: Pass outputReferenceFallbacks option to the relevant utilities, so the option actually works.

  • 39547fb: Fix parsers async support, use resolved filePath instead of raw.

  • 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.

  • cd9f484: Escape double quotes for ts outputStringLiterals

  • 0c1a36f: Fix small issue in type DTCG delegate utility type tracking.

  • d008c67: Fix a couple of spots where DTCG option wasn't properly taken into account, more tests added.

  • 6cfce97: Fix logging to be ordered by platform when building or cleaning platforms. This now happens in parallel, resulting in the logs being ordered randomly which was a small regression to the logging experience.

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

  • 0972b26: Pass SD options to fileheaders and filters, to make it easier to use and adjust according to config or options like usesDTCG.

  • 2335f13: Allow using registerHook methods to override hooks that are already registered with the same name.

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

  • 0c1a36f: Expose typeDtcgDelegate utility. Don't take value into account anymore to determine that it's a design token, use $value.

  • 061c67e: Hotfix to address outputReferencesTransformed util not handling object-value tokens properly.

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

  • 738686b: Allow transformGroup to be combined with transforms, where standalone transforms will be added after the group's transforms.

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

  • cd48aac: Only run postinstall scripts when NODE_ENV isn't production (e.g. npm install --production or --omit=dev). To avoid errors running husky/patch-package.

  • a5bafac: Colors that are not recognized by tinycolor2 as valid color formats (e.g. linear-gradient(...)) are now ignored by the builtin color transforms filter functions.

  • 4ec34fd: Pass options to all of the filter functions in our built-in transforms, to check for usesDTCG and $type property.

  • daa78e1: fix(types): Added missing type exports

  • 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.

  • 6e226aa: Pass the original ref path to the getReferences util result tokens.

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

  • 3f09277: Pass dictionary options to preprocessor functions.

  • c2cbd1b: Publish the postinstall-dev script to NPM.

  • 0972b26: Add unfilteredAllTokens property in dictionary object for formats, which is an unfiltered version of allTokens property, or a flattened version of the unfilteredTokens property.

  • 47face0: Token merging behavior changed so that upon token collisions, metadata props aren't accidentally merged together.

  • f8c40f7: fix(types): add missing type keyword for type export from index.d.ts

  • 77ae35f: Fix scenario of passing absolute paths in Node env, do not remove leading slash in absolute paths.

  • 63681a6: Fix a couple of type imports issues in .d.ts files

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

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

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

3.9.2 (2024-01-17)

Bug Fixes

  • regression, glob to return posix style paths (#1085) (473ca82)

3.9.1 (2023-12-07)

Bug Fixes

  • allow falsy token values for outputReferences, e.g. 0 (83a9934)
  • types for FormatHelpers.LineFormatting to add commentPosition (fcce1d4)

3.9.0 (2023-10-23)

Features

  • allow overriding formatting, add commentStyle long-above, short-above (b627ff1)

Bug Fixes

  • account for multi-line comments in tokens, improve comment style (b5d4cc2)
  • allow outputReferences to work on non-string values (8021ec0)
  • outputReferences to use original.value when possible (#1002) (bd73b62)

3.8.0 (2023-04-25)

Features

  • formats: add options.outputStringLiterals to typescript/es6-declarations (#857) (0c31718), closes #905
  • formats: compose object imports (#874) (8373721)
  • types: loosening the Platform type to allow for extension (#926) (c43263b)

Bug Fixes

  • formats: added missing EOL before EOF for some formats (#963) (dd60479)
  • types: add correct return types for sortByReference (#919) (2eff17d), closes #918

3.7.2 (2023-01-03)

Bug Fixes

  • docs: Correct custom-file-header example link (#869) (4e156b1)
  • docs: removed the duplicate wording (#870) (dbb89e5)
  • formats: scss/map-deep type error when values are strings or null (#838) (d338633), closes #837
  • references: getReferences now searches the entire object (#812) (884b1b8)
  • references: tokens with a number value should be interpolated correctly (#825) (a2f7784)
  • transforms: transitive transforms now work without .value in refs (#808) (41bc893)
  • types: add matcher type to export (#878) (2617a0d), closes #875
  • types: added packageName as optional property on interface File (#829) (0996cc4)
  • types: adding missing format helpers (#834) (a6f4b34)
  • types: fix filter config key expected matcher value (#883) (c77c3db)
  • types: fixing transform group property type of Config (#833) (0f0ad10)

3.7.1 (2022-06-07)

Bug Fixes

  • references: getReferences now searches the entire object (#812) (884b1b8)
  • references: tokens with a number value should be interpolated correctly (#825) (a2f7784)
  • transforms: transitive transforms now work without .value in refs (#808) (41bc893)

3.7.0 (2022-02-22)

Features

Bug Fixes

  • examples: complete example style dictionary version to latest (#755) (c3aae93)
  • types: Correct type of Core.format (#780) (9868b7e), closes #779

3.1.1 (2021-12-17)

Bug Fixes

  • deps: adding jsonc-parser to regular dependencies (#750) (43ff607)

3.1.0 (2021-12-16)

Features

  • formats: Add outputReferences support to scss/map-deep (#720) (65453e0), closes #712
  • formats: add support for Microsoft's JSONC format (#732) (cfa83cb), closes #698
  • formats: object handling for typescript/es6-declarations (#718) (4e3905a)
  • references: ability to reference other tokens without 'value' (#746) (c6f482e)
  • transforms: add transformer for Color class from SwiftUI (#733) (439e474)

Bug Fixes

3.0.3 (2021-10-15)

Bug Fixes

3.0.2 (2021-08-19)

Bug Fixes

  • format: 'typescript/es6-declarations' return type (#681) (0cf6c52)
  • lib: fix createFormatArgs positional args (#655) (29e511d), closes #652
  • references: check if object value is a string before replacement (#682) (bfc204c)
  • types: format config expects formatter function (#650) (b12c4b1)

3.0.1 (2021-06-07)

Bug Fixes

  • swift: add missing space after UIColor's alpha property (#648) (7c65733)
  • types: directly export Named type to avoid ambiguity with TS --isolatedModules option (8295b0d)
  • types: directly export Named type to avoid ambiguity with TS --isolatedModules option (3ed31be)

3.0.0 (2021-05-25)

3.0.0-rc.10 (2021-05-24)

Features

  • formats: add typescript declarations formats (#557) (f517bcf), closes #425
  • types: cleaning up our type definitions (#632) (db6269b)

Bug Fixes

  • references: value object references now work (#623) (23de306), closes #615
  • template: remove blank lines in scss/map-deep and scss/map-flat templates (#588) (a88e622)

2.10.3 (2021-03-09)

Bug Fixes

3.0.0-rc.9 (2021-05-04)

Features

Bug Fixes

  • formats: bringing mapName back to scss formats (#611) (7a28f40)
  • formats: fixing formatting options in fileHeader (#614) (3f7fe96), closes #612
  • references: fixing circular reference errors (#607) (9af17f4), closes #608
  • references: flushing the filtered reference warnings (#598) (d3b5135)

3.0.0-rc.8 (2021-04-05)

Features

  • formats: add an optional selector to css/variables format (#582) (34922a8)
  • formats: output references handles interpoloated references (#590) (cc595ca), closes #589

Bug Fixes

  • combine: filePath was missing for falsey values (#583) (8c405e6)
  • formats: update output references in formats to handle nested references (#587) (9ce0311)

3.0.0-rc.7 (2021-03-24)

Features

Bug Fixes

  • references: use unfiltered dictionary for reference resolution in formats (#553) (62c8fb8)

3.0.0-rc.6 (2021-03-09)

Bug Fixes

3.0.0-rc.5 (2021-02-27)

Bug Fixes

  • types: introduce parser, update config, optional transform options (#546) (0042354), closes #545

3.0.0-rc.4 (2021-02-16)

Features

3.0.0-rc.3 (2021-02-06)

Features

  • build-file: do not generate file if properties is empty (#494) (8945c46)
  • format: output references (#504) (7e7889a)
  • format: use named parameters in formatter functions (#533) (32bd40d)
  • react-native support (#512) (bd61cd2)

Bug Fixes

  • examples: little typo (#518) (33271b6)
  • export platform: fixing infinite loop when there are reference errors (#531) (6078c80)
  • property setup: original property being mutated if the value is an object (#534) (0b13ae2)
  • types: add transitive to value transform type (#536) (695eed6)
  • types: Change transforms to transform in Core (#530) (40a2601)

3.0.0-rc.2 (2021-01-12)

Features

  • format: adding android/resources format (e43aafd)
  • transforms: add 'px to rem' transform (#491) (75f0ba3)

Bug Fixes

  • extend: use given file path for token data (#499) (0b23c9d)
  • parsers: fixed an error where parsers weren't running (#511) (b0077c3)
  • types: fix transform options type #502 (32787f8)

3.0.0-rc.1 (2020-12-04)

3.0.0-rc.0 (2020-12-03)

Features

  • examples: add custom filters example (c9bfcbc)
  • examples: add custom filters example (f95c420)
  • examples: add matching build files example (#481) (5a80ef6), closes #251
  • add support for !default in SCSS variables format (#359) (fa82002), closes #307
  • add TypeScript typings (#410) (a8bb832)
  • core: add new entries on property object (#356) (fd254a5)
  • formats: add file object to formatter method (#439) (1481c46)
  • formats: javascript/module-flat format (#457) (37b06e8)
  • parser: adding custom parser support (#429) (887a837)
  • transforms: Make transitive transforms & resolves possible (#371) (3edbb17), closes #208

Bug Fixes

  • cli: update clean config path logic (#454) (dc3cfa5)
  • formats: fix max call stack issue on json/nested format (#465) (67fb361)
  • transforms: fix transitive transforms (#476) (ac0c515)

2.10.3 (2021-03-09)

Bug Fixes

2.10.2 (2020-10-08)

Bug Fixes

  • cli: update clean config path logic (#454) (3cc3d4e)
  • formats: fix max call stack issue on json/nested format (#465) (4064e6a)

2.10.1 (2020-07-09)

Bug Fixes

  • filter: fix conditional to ensure we catch properties with a falsy value (#423) (1ec4e74), closes #406
  • formats: align scss/map-* with scss/variables on asset category (9d867ef)

2.10.0 (2020-05-05)

Features

2.9.0 (2020-04-21)

Bug Fixes

  • transforms: add NaN check to all size transforms (#413) (d353795)
  • transforms: add specificity so color for hex values is correct (#412) (01cc11c), closes #407
  • clean require cache before loading file content (#405) (18a50d0), closes #404
  • parseFloat() has only one argument (#417) (16c3040), closes #416

Features

  • attribute/cti: attribute/cti should respect manually set attributes (#415) (fb3e393), closes #414

2.8.3 (2019-10-30)

Bug Fixes

2.8.2 (2019-09-04)

Bug Fixes

2.8.1 (2019-07-02)

Bug Fixes

  • format: adding configurable name to sass map name (#291) (cfa2422), closes #290
  • sketch: fix sketch palette format to use new filters (#287) (374012c), closes #285

2.8.0 (2019-05-28)

Bug Fixes

  • cleanfile: add file check and log for non-existent file (#277) (6375133)
  • docs/examples: 404 errors and typos (#269) (da369da)
  • error-messaging: add better error messaging when a transform or transformGroup does not exist (#264) (d5c0583)
  • extend: multiple extensions properly deep merge (#276) (f1d6bb0), closes #274
  • accidentally generating test output in root directory (4994553)

Features

  • config: use config.js if config.json is not found (#249) (09fc43f), closes #238 #238 #247
  • add automatic changelog generation (#225) (b062008)
  • docs: adding PR and download badges; fixing code coverage badge (#270) (2307a44), closes #265
  • ios-swift: adding common transforms for Swift in iOS (#255) (749db69), closes #161
  • transforms: Add UIColor transform for swift (#250) (a62d880), closes #161
  • warning: catch property name collisions during file output (#273) (9a40407)