Introducing Chromatic: A Build Tool for Design Systems

TLDR; Chromatic is a build system for managing cross-platform design systems using design tokens. Unlike similar tools, it supports expressive design tokens and theming.

Design is an essential ingredient to successful software products. But design at scale across many project and many platforms (web, iOS, Android, desktop) is a huge challenge. Smooth communication between the design and development teams is critical. And annotated redlines saved in PDF files don’t cut it.

Designs also need to evolve and change quickly and at a minimal cost.

Over the past few years, teams have started embracing design systems as a way of managing this complexity. Often, design systems use design tokens to record and communicate their design decisions.

Design Tokens

The concept of design tokens was introduced by the Salesforce Design team, and has since spread throughout the industry.

Design tokens are small, atomic, units of design decision: a color, a line thickness, a font scale, a margin.

Design Tokens are design decisions propagated through a system — Nathan Curtis, Eightshapes

They can be composed to form more complex elements, but rather than hardcoding the color for a CTA button, a named design token is used which ensures consistency across the project and makes it much easier to update later without causing major work for the development team.

Design tokens are stored in easy to author platform-neutral files, typically .yaml or .json. A tool is then used to transform them into output files in the necessary formats for specific platforms: .scss or .css for the web, .plist or .json for iOS, .xml for Android, etc… They can even generate a living and always up to date style guide.

There are a few design token tools such as Theo from the Salesforce team, and the Style Dictionary from the AWS Team, but they have some limitations that led me to creating Chromatic.

Chromatic

Chromatic is a NPM module (@ui-js/chromatic) built on Node.js. Chromatic is an open source project available on GitHub at https://github.com/ui-js/chromatic with a MIT license and gladly accept contributions.

Chromatic is available both as a Javascript library and a command line tool, so it can easily be integrated with existing build systems.

It’s a zero-conf tool. The CLI command will try to figure out what you want and guide you along the way.

From a set of token files, which can be written either as .yaml or .json files, Chromatic generates a set of output files in the desired format, including a HTML style guide.

In the process of generating those files, the token values will be transformed to an appropriate format. For example, colors will be transformed in hex values or rgb() functions for the web, and in #AARRGGBB values for Android. Units for spacing and font sizes are transformed from pixels or rem to pt on iOS and sp or dip on Android.

Token files can be broken up in multiple files that can be imported from one another. The organization is up to you. You could have a base token file, and some token files specific to each subproject, or token files for some variants such as compact and cozy layouts. Or you could group all the colors together in one token file, and all the typography in another.

Before anything is generated, Chromatic will read all the token files, merge them together, and let you know if there are any problems. If there’s a problem, such as a misspelling, Chromatic will offer some suggestions to fix it.

Expressive Design Tokens

A token can be bare bone:

Or it can include usage hints that will be incorporated when generating the output files or the style guide:

A design token can also reference another design token:

Unlike some other tools, there is no need to declare separately “aliases” for the values that you want to re-use. The values will be evaluated and replaced as needed.

In fact, design tokens can references to other tokens, or arbitrary expressions that encapsulate a design intent:

There’s a collection of well-chosen functions available. For example contrast() calculates the luminosity of an underlying color and will pick an appropriate contrasting color to ensure proper contrast and legibility:

Theming

Dark mode is a popular UI trend, but not the only example where ‘theming’ can be useful. For example, you may want to have a consistent style between multiple web properties, but each with its own branding colors. Or you may want to support a compact and cozy layouts, perhaps for different devices, or even as a user preference.

Either way, Chromatic can make theming easier. Rather than writing multiple token files, and trying to keep in sync the set of tokens as your design system evolves, you can assign multiple values to a token, one for each theme. Not all tokens have to be themed, and you can use expressive design tokens to further reduce the number of tokens with a different definition for each theme.

Run this command:

And chromatic will generate this file:

Conclusion

I built Chromatic because I needed to manage design tokens for another project I’m working on, and I wasn’t satisfied with the existing tools.

I wanted a tool that would be simple to use and deploy, that would support more expressive design tokens, theming, and beautiful auto-generated style guides.

There’s still more work to do, including support for more formats, and perhaps import and export for some design tools such as Sketch or Adobe XD.

In the meantime, I hope you’ll already find it useful and enjoy using it.

You can find Chromatic on github and on npm (@ui-js/chromatic).