Releases: amzn/style-dictionary
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
Assets 2
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
removePrivateby @silversonicaxel in #770 - fix(types): Correct type of
Core.formatby @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
- @gabischima made their first contribution in #734
- @gillennium made their first contribution in #761
- @jakobe made their first contribution in #780
Full Changelog: v3.1.1...v3.7.0
Contributors
Assets 2
v3.1.0
What's Changed
- Add object handling for typescript/es6-declarations by @RobbyUitbeijerse in #718
- fix(types): adding registerFileHeader type by @silversonicaxel in #722
- feat(formats): Add
outputReferencessupport toscss/map-deepby @notlee in #720 - feat(formats): add support for Microsoft's JSONC format by @TrevorBurnham in #732
- fix(types): fixing transform group types by @dbanksdesign in #729
- fix(examples): Watch correct directory by @chazzmoney in #739
- feat(ios-swift): add transformer for Color class from SwiftUI by @antoniogamizbadger in #733
- chore(deps): bump lodash from 4.17.15 to 4.17.21 in /examples/advanced/custom-parser by @dependabot in #740
- chore(deps): bump lodash from 4.17.20 to 4.17.21 in /examples/advanced/matching-build-files by @dependabot in #741
- fix(types): make FileHeaderArgs.commentStyle optional by @ZeekoZhu in #743
- chore(docs): adddocs reference to playground by @jorenbroekema in #730
- feat(references): ability to reference other tokens without 'value' by @dbanksdesign and @markacianfrani in #746
- fix(cli): fixing unknown commands message by @dbanksdesign in #747
New Contributors
- @RobbyUitbeijerse made their first contribution in #718
- @silversonicaxel made their first contribution in #722
- @notlee made their first contribution in #720
- @TrevorBurnham made their first contribution in #732
- @antoniogamizbadger made their first contribution in #733
- @ZeekoZhu made their first contribution in #743
- @jorenbroekema made their first contribution in #730
- @markacianfrani made their first contribution in #746
Full Changelog: v3.0.3...v3.1.0
Contributors
Assets 2
v3.0.3
What's Changed
- #684: Add
classNameoptional parameter by @alexsurelee in #683 - chore(deps): updating dependencies for dependabot by @dbanksdesign in #689
- fixed typo by @lukasoppermann in #690
- Upgrade to setup-node@v2 action by @josephyi in #706
- docs(templates): fixed doc anchor on template by @CharlyTorregrosa in #699
- fix(types): added
nameto format, and exportNamedby @yoniholmes in #714 - chore(docs): add selector option for css/variables format by @markacianfrani in #707
- [TS] Fix FileHeader input type by @Shimmi in #708
- Add base px font size to platform type definition by @didoo in #715
New Contributors
- @alexsurelee made their first contribution in #683
- @lukasoppermann made their first contribution in #690
- @CharlyTorregrosa made their first contribution in #699
- @markacianfrani made their first contribution in #707
- @Shimmi made their first contribution in #708
Full Changelog: v3.0.2...v3.0.3
Contributors
Assets 2
v3.0.2
v3.0.1
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
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
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.
- Example: https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-parser
- YAML example: https://github.com/amzn/style-dictionary/tree/main/examples/advanced/yaml-tokens
Adding filePath and isSource entries on tokens
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...