Style Dictionary: Transforming and Generating Tokens

Style Dictionary (created by Amazon) is a build tool that takes design token definitions in JSON format and outputs them in any target format: CSS custom properties, JavaScript ES modules, Sass variables, iOS Swift constants, Android XML resources, and any custom format you define. One source of truth, many outputs.

Install with npm install --save-dev style-dictionary. Initialize a project structure with npx style-dictionary init, which creates a config.json (or config.js) and a tokens/ directory. The config tells Style Dictionary where to find token files and where to write the outputs.

Style Dictionary uses a nested JSON structure where the leaf nodes have a value property. For example: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. The path to the value (color, primary, 500) becomes the token name after transformation, typically formatted as color-primary-500 or --color-primary-500.

Run npx style-dictionary build --config config.json (or style-dictionary build if configured in package.json scripts). Style Dictionary reads all token files from the configured source, applies transforms, and writes outputs to the configured destinations. Errors in the token format are reported with the file name and path.

The config.json defines platforms: css (outputs a CSS file with custom properties), js (outputs a JS object), scss (outputs Sass variables). Each platform specifies the output directory, file name, format (the template), and transforms (the name and value processing functions) to apply.

Style Dictionary includes built-in transforms: name/cti/kebab converts the nested path to color-primary-500, name/cti/camel produces colorPrimary500, size/rem converts pixel values to rem, color/hex normalizes colors to hex. Transforms are composable and applied in order.

You can register custom transforms with StyleDictionary.registerTransform(). For example, a transform that converts pixel values to iOS points, or one that adds a company-specific prefix to all token names. Custom transforms give you full control over how values are processed before output.

Custom formats define the output file template. StyleDictionary.registerFormat() receives the dictionary of transformed tokens and returns a string — the file content. You can output tokens as TypeScript types, as a React theme object, as a Tailwind config extension, or as any other format your stack requires.

After building, import the CSS output in your global stylesheet: @import './tokens/tokens.css'. Import the JS output in components or the Tailwind config: import tokens from './tokens/tokens.js'. The CSS gives you custom properties for runtime theming; the JS gives you typed constants for Tailwind and JavaScript logic.

Style Dictionary supports token references using curly braces: { "value": "{color.primary.500}" }. This creates semantic token aliases — the semantic token references a primitive token. At build time, Style Dictionary resolves references and outputs the final resolved value (or a CSS variable reference, depending on your format).

Run Style Dictionary as a prebuild npm script so tokens are always regenerated before the application builds. Add "prebuild": "style-dictionary build" to package.json. This ensures that any change to the token JSON files is reflected in the CSS and JS outputs before the React build processes them.

What is the purpose of transforms in Style Dictionary?

Style Dictionary converts token JSON into any output format: CSS variables, JS modules, Sass, iOS, Android. Token JSON uses nested objects with value leaf nodes. Transforms process names and values (camelCase, px-to-rem); formats define the output template. Token references ({color.primary.500}) enable semantic aliasing. Automate with a prebuild script so tokens are always fresh before the React build.