Skip to content

Releases: amzn/style-dictionary

v3.7.2

03 Jan 21:49
@dbanksdesign dbanksdesign
v3.7.2
ebf02c1
Compare
Choose a tag to compare
v3.7.2

What's Changed

New Contributors

Full Changelog: v3.7.1...v3.7.2

Contributors

mattleff, dbanksdesign, and 12 other contributors
Assets 2
Loading

v3.7.1

07 Jun 22:11
@dbanksdesign dbanksdesign
v3.7.1
a12a31f
Compare
Choose a tag to compare
v3.7.1

What's Changed

  • chore(deps): bump prismjs from 1.26.0 to 1.27.0 by @dependabot in #783
  • chore(deps): bump url-parse from 1.5.7 to 1.5.10 in /examples/advanced/create-react-app by @dependabot in #784
  • update docs to reflect where basePxFontSize is included by @spirkolos in #799
  • chore(deps): bump minimist from 1.2.5 to 1.2.6 by @dependabot in #801
  • chore(deps): bump minimist from 1.2.5 to 1.2.6 in /examples/advanced/custom-formats-with-templates by @dependabot in #804
  • chore(deps): bump minimist from 1.2.5 to 1.2.6 in /examples/advanced/create-react-app by @dependabot in #802
  • chore(deps): bump minimist from 1.2.5 to 1.2.6 in /examples/advanced/format-helpers by @dependabot in #805
  • chore(deps): bump minimist from 1.2.5 to 1.2.6 in /examples/advanced/custom-filters by @dependabot in #806
  • Fix documentation bugs (formats) by @oscarb in #790
  • Update formattedVariables example by @joerobot in #800
  • chore(ci): update node versions for testing by @dbanksdesign in #807
  • fix(transforms): transitive transforms now work without .value in refs by @dbanksdesign in #808
  • feat(example): example for building @font-face rules by @jbarreiros in #771
  • chore(deps): bump lodash from 4.17.20 to 4.17.21 in /examples/advanced/font-face-rules by @dependabot in #810
  • chore(deps): bump minimist from 1.2.5 to 1.2.6 in /examples/advanced/font-face-rules by @dependabot in #811
  • chore(deps): bump async from 2.6.3 to 2.6.4 in /examples/advanced/create-react-app by @dependabot in #816
  • fix(references): getReferences now searches the entire object by @dbanksdesign in #812
  • fix(references): Tokens with a number value should be interpolated correctly by @jakobe in #825
  • chore(example): fixing font-face example by @dbanksdesign in #824

New Contributors

  • @spirkolos made their first contribution in #799
  • @oscarb made their first contribution in #790
  • @joerobot made their first contribution in #800

Full Changelog: v3.7.0...v3.7.1

Contributors

dbanksdesign, jbarreiros, and 5 other contributors
Assets 2
Loading

v3.7.0

22 Feb 22:25
@dbanksdesign dbanksdesign
v3.7.0
94fc9f9
Compare
Choose a tag to compare
v3.7.0

What's Changed

  • feat: any swift format by @gabischima in #734
  • fix(examples): complete example style dictionary version to latest by @dbanksdesign in #755
  • chore(deps): update dependencies and fix dependabot issues by @dbanksdesign in #763
  • chore(deps): bump lodash from 4.17.20 to 4.17.21 in /examples/advanced/transitive-transforms by @dependabot in #765
  • chore(deps): bump nanoid from 3.1.23 to 3.2.0 in /examples/advanced/create-react-app by @dependabot in #766
  • chore(deps): bump lodash from 4.17.20 to 4.17.21 in /examples/advanced/yaml-tokens by @dependabot in #767
  • Add support for css variable fallback values when using outputReferences option by @gillennium in #761
  • chore(format-helpers): default args for createPropertyFormatter by @dbanksdesign in #774
  • chore(deps): bump node-sass from 6.0.1 to 7.0.0 in /examples/advanced/create-react-app by @dependabot in #776
  • chore(deps): bump follow-redirects from 1.14.1 to 1.14.8 in /examples/advanced/create-react-app by @dependabot in #778
  • Feat(dictionary) Added new filter removePrivate by @silversonicaxel in #770
  • fix(types): Correct type of Core.format by @jakobe in #780
  • chore(deps): bump url-parse from 1.5.3 to 1.5.7 in /examples/advanced/create-react-app by @dependabot in #782

New Contributors

Full Changelog: v3.1.1...v3.7.0

Contributors

dbanksdesign, gillennium, and 4 other contributors
Assets 2
Loading

v3.1.0

16 Dec 22:25
@dbanksdesign dbanksdesign
v3.1.0
983d9c6
Compare
Choose a tag to compare
v3.1.0

What's Changed

New Contributors

Full Changelog: v3.0.3...v3.1.0

Contributors

TrevorBurnham, dbanksdesign, and 9 other contributors
Assets 2
Loading

v3.0.3

15 Oct 22:12
@dbanksdesign dbanksdesign
v3.0.3
e42d90b
Compare
Choose a tag to compare
v3.0.3

What's Changed

New Contributors

Full Changelog: v3.0.2...v3.0.3

Contributors

yoniholmes, dbanksdesign, and 7 other contributors
Assets 2
Loading

v3.0.2

19 Aug 23:02
@dbanksdesign dbanksdesign
v3.0.2
a482a03
Compare
Choose a tag to compare
v3.0.2

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)
Assets 2
Loading

v3.0.1

08 Jun 04:15
@dbanksdesign dbanksdesign
v3.0.1
904a6ec
Compare
Choose a tag to compare
v3.0.1

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 (#644) (8295b0d)
Assets 2
Loading

v3.0.0

25 May 20:51
@dbanksdesign dbanksdesign
v3.0.0
bd498aa
Compare
Choose a tag to compare
v3.0.0

Version 3.0 is now publicly released! We have been working hard the past few months on a number of features and improvements we wanted to combine into a major release. Though we intend that 3.0 to be backwards compatible, we thought it was a good idea to move to a new major version because we are changing a core part of how Style Dictionary works.

If you are starting a new project, you can install Style Dictionary and it will give you the latest version:

npm install --save-dev style-dictionary

If you have an existing project, you can upgrade to 3.0 by updating the version in your package.json file to "style-dictionary": "^3.0.0" and then run npm install or you can use the latest tag to update both your package.json and package-lock.json files:

npm install --save-dev style-dictionary@latest

If you find any bugs or issues, please file tickets so we can get things fixed. We have tested and reviewed 3.0 extensively, but there may be things we missed. Thanks!

Style Properties → Design Tokens

Style Dictionary is moving to the term "design tokens", both in documentation and in code. This has become the industry standard term for a while and it is time we respect that. Until now, Style Dictionary had called these "style properties" or just "properties", with some parts of the documentation also mentioning "design tokens". We want to be consistent with the direction of the community as well as in our documentation and code. We use the terms properties and allProperties in different APIs in Style Dictionary. To be consistent in documentation as well as code, we will be moving to using tokens and allTokens.

Don't worry! This change is backwards-compatible; you will still be able to use properties and allProperties wherever you currently do in your code. If you want, you can update those to tokens and allTokens and everything will work as expected. Moving forward, all examples and documentation will use the term "design tokens" and "tokens" rather than "style properties" and "properties". We do recommend using tokens and allTokens in new code from here on out!

Transitive transforms

This is the big one that required a big re-architecture of how the Style Dictionary build process works.

Up until now the build process looked like this: https://amzn.github.io/style-dictionary/#/build_process
After merging all of the token files, it would iterate through the merged object and transform tokens it found, but only do value transforms on tokens that did not reference another token. The original intent here was that a value of any reference should be the same for all references of it, so we only need to do a value transform once. Then after all tokens are transformed, resolve all aliases/references.

However, we heard from the community there were a number of reasons why someone might want to transform the value of an aliased token.

The new build process is similar, except that it recursively transforms and resolves aliases, only deferring a transform to the next cycle if the token has an unresolved alias. Each pass might reveal tokens that are ready to be transformed in the next pass. Take this example:

{
  "color": {
    "black": { "value": "#000000" },
    "font": {
      "primary": { "value": "{color.black.value}" },
      "input": { "value": "{color.font.primary.value}" }
    }
  }
}

The first pass will transform the color.black token because it doesn't have a reference. It will defer the transforms of color.font.primary and color.font.input because they do have references. Then it will resolve references to color.black.value because it has been transformed.

The second pass will transform color.font.primary because it no longer has a reference. It will then resolve the reference to color.font.primary.value because it has been transformed.

The final pass will transform color.font.input because it no longer has a reference. Now the build is complete because there are no more deferred transforms left.

Use cases this change opens up:

  • Having variable references in outputs
  • Combining values like using HSL for colors
  • Modifying aliases like making a color lighter or darker

Example: https://github.com/amzn/style-dictionary/tree/main/examples/advanced/transitive-transforms

Thanks @mfal!

Output references

#504

This is another big one. This has been one of the first issues we made back in 2017, issue 17! This adds support for outputting references in exported files. This is a bit hard to explain, so let's look at an example. Say you have this very basic set of design tokens:

// tokens.json
{
  "color": {
    "red": { "value": "#ff0000" },
    "danger": { "value": "{color.red.value}" },
    "error": { "value": "{color.danger.value}" }
  }
}

With this configuration:

// config.json
{
  "source": ["tokens.json"]
  "platforms": {
    "css": {
      "transformGroup": "css",
      "files": [{
        "destination": "variables.css",
        "format": "css/variables",
        "options": {
          // Look here 👇
          "outputReferences": true
        }
      }]
    }
  }
}

This would be the output:

:root {
  --color-red: #ff0000;
  --color-danger: var(--color-red);
  --color-error: var(--color-danger);
}

The css variables file now keeps the references you have in your Style Dictionary! This is useful for outputting themeable and dynamic code.

Without outputReferences: true Style Dictionary would resolve all references and the output would be:

:root {
  --color-red: #ff0000;
  --color-danger: #ff0000;
  --color-error: #ff0000;
}

Not all formats use the outputReferences option because that file format might not support it (like JSON for example). The current list of formats that handle outputReferences:

  • css/variables
  • scss/variables
  • less/variables
  • compose/object
  • android/resources
  • ios-swift/class.swift
  • ios-swift/enum.swift
  • flutter/class.dart

If you have custom formats you can make use of this feature too! The dictionary object that is passed as an argument to the formatter function has 2 new methods on it: usesReference() and getReference() which you can use to get the reference name. Here is an example of that:

StyleDictionary.registerFormat({
  name: `myCustomFormat`,
  formatter: function(dictionary) {
    return dictionary.allProperties.map(token => {
      let value = JSON.stringify(token.value);
      // the `dictionary` object now has `usesReference()` and
      // `getReference()` methods. `usesReference()` will return true if
      // the value has a reference in it. `getReference()` will return
      // the reference to the whole token so that you can access its
      // name or any other attributes.
      if (dictionary.usesReference(token.original.value)) {
        const reference = dictionary.getReference(token.original.value);
        value = reference.name;
      }
      return `export const ${token.name} = ${value};`
    }).join(`\n`)
  }
})

Example: https://github.com/amzn/style-dictionary/tree/main/examples/advanced/variables-in-outputs

Custom parser support

#429

We are pretty excited about this. Until now you could only define your design tokens in either JSON, JSON5, or plain Node modules. The addition of custom parser support allows you to define your tokens in any language you like! The most obvious use-case is to use YAML which has a cleaner and less verbose syntax than JSON. Now, the sky is the limit. Your source of truth can be in any file format you like as long as you can parse it into an object that Style Dictionary can understand. You register a custom parser the same way as you register a custom transform or format. A parser consists of a pattern to match against files, similar to the test attribute in a loader in Webpack, and a parse function which gets the file path and its contents and is expected to return an object.

Adding filePath and isSource entries on tokens

#356

Style Dictionary adds some metadata on each token before any transforms take place in order to give more context for transforming and formatting tokens. For example, this design token:

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

Turns into this:

{
  "color": {
    "red": {
      "value": "#ff0000",
      "name": "red", // adds a default 'name', which is the object key
      "path": ["color","red"], // object path
      "original": {
        "value": "#ff0000"
      } // copies the original object so you always have a clean copy
    }
  }
}

We are adding 2 new pieces of metadata to each token:

  • filePath: A string representing the absolute path of the file that defines the token. This will help with debugging and if you want to output files based on the source files.
  • isSource: A boolean representing if this file was defined as ‘source’ in the configuration as opposed to ‘include’ (or directly setting the ‘properties’ object). This can also help filtering tokens from output files you don't want to include.

Thanks @7studio!

Format helpers

Style Dictionary comes with built-in...

Read more
Assets 2
Loading

v2.10.3

09 Mar 20:47
@dbanksdesign dbanksdesign
v2.10.3
be2fe3b
Compare
Choose a tag to compare
v2.10.3

2.10.3 (2021-03-09)

Bug Fixes

Assets 2
Loading

v2.10.2

08 Oct 17:56
@dbanksdesign dbanksdesign
v2.10.2
ef2dafa
Compare
Choose a tag to compare
v2.10.2

Bug Fixes

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