- 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 addconvertTokenData
utility that allows to seemlessly convert between Map, Object or Array of tokens, and deprecate theflattenTokens
utility in favor of that one.
- 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 returntrue
for tokens which original values were not strings. - 7a661bb: Fix font-style and font-weight logic for fonts.css.template.js
- 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 usingoptions.stripMeta
, which if set totrue
will strip Style Dictionary meta props. You can specifykeep
/strip
(allow/blocklist) for granular control about which properties to keep or strip.
- 5e3a5af: Update .d.ts/js files type imports to use correct extensions rather than extensionless. This fixes some incompatibilities with latest TypeScript "NodeNext" moduleResolution.
- 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.
- 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.
- 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.
- 5db3521: Add
iosSwiftEnumOpts.className
andiosSwiftAnyOpts.className
formats property documentation - 23f8a25: Use cp and rmdir commands for
copy_assets
do and undo methods, since they affect directories, not files.
-
ccf27b7: Prevent duplicate redundant calls to StyleDictionary class methods by caching platform specific config & tokens results.
Added reusable methods:
getPlatformTokens()
-> grabs thetokens
/allTokens
(new!exportPlatform
does not return this) for a specific platform, after running platform specific preprocessors and transforms. This replaces the oldexportPlatform
method which is now deprecated and will be removed in v5.getPlatformConfig()
-> grabs the processed/transformedPlatformConfig
for a specific platform, replaces the now deprecatedgetPlatform
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 tofalse
, 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.
-
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 ofFormattingOptions
. These contain the formatting options that can be overridden by users, whereas the full version is meant for the format helper utilities such ascreatePropertyFormatter
/formattedVariables
.
- 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.
For a more comprehensive migration guide from version 3.x.x to version 4.0.0, visit the migration guide page
-
6cc7f31: BREAKING:
-
usesReference
util function is nowusesReferences
to be consistent plural form like the other reference util functions. -
getReferences
first and second parameters have been swapped to be consistent withresolveReferences
, 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 fewerany
s. - 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 asParser
,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, soFilter['matcher']
,Transform['transformer']
,Format['formatter']
- Style Dictionary is entirely strictly typed now, and there will be
-
-
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 returnsPromise<StyleDictionary.Core>
instead ofStyleDictionary.Core
.allProperties
/properties
was deprecated in v3, and is now removed fromStyleDictionary.Core
, useallTokens
andtokens
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 tofileHeader
. 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 toaction
. 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 tofilter
. 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 nowfilter
instead ofmatcher
.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 (previouslymatcher
) insidetransforms
. -
f2ed88b: BREAKING: Transform groups, when registered, are put inside the
hooks.transformGroups
property now, as opposed totransformGroup
.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 toformat
. Theformatter
handler function has been renamed toformat
for consistency.The importable type interfaces have also been renamed,
Formatter
is nowFormatFn
andFormatterArguments
is nowFormatFnArguments
. Note that you can also useFormat['format']
instead ofFormatFn
, orParameters<Format['format']>
instead ofFormatFnArguments
, 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 calledhooks
.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
andresourceMap
options for a bunch of built-in formats have been moved fromfile
to go inside thefile.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 totransform
. Thematcher
property has been renamed tofilter
(to align with the Filter hook change), and thetransformer
handler function has been renamed totransform
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
foroutputReferences
, conditionally outputting a ref or not per token. Also exposesoutputReferencesFilter
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 insideurl("")
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 toparsers
.parsers
property has been repurposed: you will now also need to explicitly apply registered parsers by name in theparsers
property, they no longer apply by default. When registering a parser, you must also supply aname
property just like with all other hooks, and theparse
function has been renamed toparser
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 justname/casing
.name/ti/camel
andname/ti/constant
have been removed. For examplename/cti/kebab
transform is nowname/kebab
. - Transform
content/icon
has been renamed tohtml/icon
since it targets HTML entity strings, not just any icon content. font/objC/literal
,font/swift/literal
andfont/flutter/literal
have been removed in favor offont/objC/literal
,font/swift/literal
andfont/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" } } }
- 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
-
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 settingfile.formatting.fileHeaderTimestamp
totrue
. 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 } });
-
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
andgetReferences
warnImmediately
option is set totrue
which causes an error to be thrown/warned immediately by default, which can be configured tofalse
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 ofstrokeStyle
tokens no longer get expanded unintentionally,typeof 'object'
check changed toisPlainObject
check. - Nested object-value tokens (such as
style
property insideborder
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.
- Array values such as
-
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 totypeDtcgDelegate
, 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
andless
transformGroups:fontFamily/css
-> wraps font names with spaces in'
quotescubicBezier/css
-> array value, put insidecubic-bezier()
CSS functionstrokeStyle/css/shorthand
-> object value, transform to CSS shorthandborder/css/shorthand
-> object value, transform to CSS shorthandtypography/css/shorthand
-> object value, transform to CSS shorthandtransition/css/shorthand
-> object value, transform to CSS shorthandshadow/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
-
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
andformatAllPlatforms
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 astring
anddestination
property infiles
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.
-
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
orformattedVariables
helpers now respect thefile.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 takevalue
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)
3.9.1 (2023-12-07)
- allow falsy token values for outputReferences, e.g. 0 (83a9934)
- types for FormatHelpers.LineFormatting to add commentPosition (fcce1d4)
3.9.0 (2023-10-23)
- allow overriding formatting, add commentStyle long-above, short-above (b627ff1)
- 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)
- 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)
- 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)
- 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)
- 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)
- filter: Added new filter
removePrivate
(#770) (3217ba3), closes #704 - formats: any swift format (#734) (9859a8d)
- 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)
3.1.0 (2021-12-16)
- formats: Add
outputReferences
support toscss/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)
- cli: fixing unknown commands message (#747) (8a5f047)
- examples: Watch correct directory (#739) (56574a4), closes #705
- types: adding registerFileHeader type (#722) (54332b3), closes #665
- types: fixing transform group types (#729) (ad7f6ea)
- types: make FileHeaderArgs.commentStyle optional (#743) (401d93b)
3.0.3 (2021-10-15)
- types:
className
optional parameter (#683) (639d7da), closes /github.com/amzn/style-dictionary/blob/main/examples/basic/config.json#L100 - types: added
name
to format, and exportNamed
(#714) (9ca0f6f)
3.0.2 (2021-08-19)
- 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)
- 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)
- formats: add typescript declarations formats (#557) (f517bcf), closes #425
- types: cleaning up our type definitions (#632) (db6269b)
- 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)
3.0.0-rc.9 (2021-05-04)
- 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)
- formats: add an optional selector to css/variables format (#582) (34922a8)
- formats: output references handles interpoloated references (#590) (cc595ca), closes #589
- 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)
3.0.0-rc.6 (2021-03-09)
3.0.0-rc.5 (2021-02-27)
3.0.0-rc.4 (2021-02-16)
3.0.0-rc.3 (2021-02-06)
- 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)
- 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)
- format: adding android/resources format (e43aafd)
- transforms: add 'px to rem' transform (#491) (75f0ba3)
- 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)
- 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
- 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)
2.10.2 (2020-10-08)
- 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)
- 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)
- adding color/hsl and color/hsl-4 transforms (#383) (b777cfb)
- flutter support (#320) (8a5f645), closes #255 #288
2.9.0 (2020-04-21)
- 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
2.8.3 (2019-10-30)
- format: minor css format output fix (#323) (adb94e1), closes #322
- utils: handle 0 values (#325) (189d61b), closes #324
2.8.2 (2019-09-04)
- format: issue #295 (c654648)
- format: issue #295 (#316) (030175e)
- formats: change less and scss comments to short version (#306) (4f13f57), closes #305
- transform: increase uicolor to 3 decimals to retain 8bit precision (#314) (a3bde96)
2.8.1 (2019-07-02)
- 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)
- 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)
- 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)