Style Dictionary

Style Dictionary is the build tool that turns your single source of truth token file into usable code for every platform your team supports. You create a set of JSON files that capture every design decision from primitive color scales to semantic roles to component specific overrides. The tool reads those files resolves all the references between them applies platform specific transforms and outputs everything from CSS custom properties to Swift constants to Android color resources. Amazon created it in 2017 to solve their own internal chaos of mismatched buttons between retail website and mobile apps. It quickly became the standard for any team serious about design systems at scale. Shopify Polaris IBM Carbon and GitHub Primer all run variations of it in their pipelines. The entire point is to stop the week long find and replace marathons when marketing decides blue is now green.

Style Dictionary is not a tool for designers to use daily inside Figma. It has no interface no color picker and no collaboration features. It is a command line tool that runs during builds. It is not Tokens Studio for Figma which is the popular plugin that lets you create and manage tokens visually inside your design files and export them as JSON. Style Dictionary consumes that JSON. The two tools work together but they are not the same thing. It is not an automatic solution that will fix your inconsistent naming or poorly thought out semantic roles. Garbage in still gets you garbage out. It will not generate your initial token set based on your Figma file. You or your team must do that thinking first. It also is not a full design system. It handles the token part. The components the documentation and the usage guidelines still need separate work.

Take the concrete example of how IBM Carbon implemented their 2022 color update. They started with a massive primitives file containing every gray from 10 to 100 every support color for error warning and success and every interactive state. Their semantic layer mapped roles like background primary to specific primitives with aliases. Component tokens for things like their data table or modal overrode the defaults where necessary. The style-dictionary config file defined transforms that converted their proprietary naming to standard CSS variables with the exact prefix their team preferred. When they ran the build command it generated not only the CSS and SCSS files but also Objective C headers for their iOS framework and Kotlin files for Android. One particular win came with their dark mode support. By having a separate theme JSON that remapped the semantic tokens to different primitives they could generate all four themes from the same core set. A designer changes the value for interactive primary in the light theme JSON runs npm run tokens and every product built on Carbon gets the update. No developer had to hunt through code for hard coded hex values. GitHub Primer uses it in a similar way but exposes their functional tokens publicly on primer.style. Their config includes special formats that also generate a JSON schema for validation in other tools. Shopify took it even further by integrating it with their React component library so that component props can reference token values directly and get type checking for free. Their tokens.json follows the exact primitive semantic component tiers. One primitive change to color.blue.500 cascades through every semantic alias and lands in the final button.background.default output for web iOS and Android simultaneously.

This kind of setup solves the exact problem described in real design systems. Remember the opening example of hard coding #0EA5E9 in fourteen Figma components. With Style Dictionary that hex lives in one primitive token. The semantic token color-interactive-primary references it. Every component uses the semantic token. The build tool makes sure the reference is valid and generates the final values. When dark mode arrived at Shopify they added a new set of primitive values for dark and updated the semantic mappings. The components did not change. The build did the work.

Reach for Style Dictionary when your team ships to multiple platforms and the cost of inconsistency has become obvious. Five designers working on web iOS and Android will thank you the first time a brand refresh happens. It is the right choice when you are building an enterprise design system like Carbon where nested layers and complex states require hundreds of tokens. Use it after you have stabilized your naming convention and have at least one production product using the tokens. Pair it with Tokens Studio for Figma released in 2021 to create a smooth handoff from design to code. The combination has become the default pipeline for most mature design teams in 2024 and 2025.

Leave it alone when you are a small team of one to three people shipping a single web product on a tight deadline. The configuration and maintenance overhead will slow you down when you should be iterating on product instead. A marketing site with no plans for mobile apps or theming does not need the complexity. Skip it during the first three months of a startup while you are still discovering product market fit and changing the entire interface weekly. Introducing Style Dictionary too early leads to abandoned JSON files and frustrated engineers. If your team lacks JavaScript experience to maintain the config and custom transforms you will spend more time debugging the tool than benefiting from it.

Style Dictionary makes one JSON file the single source of truth that actually works in production.