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 [1] as a way of managing this complexity. Often, design systems use design tokens to record and communicate their design decisions.
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
Tokens in Design Systems, by Nathan Curtis
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 [4] from the Salesforce team, and the Style Dictionary [5] from the AWS Team, but they have some limitations that led me to creating Chromatic.
Chromatic is a NPM module built on Node.js. Chromatic is an open source project available on GitHub [6] with a MIT license and gladly accept contributions.
It 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.
A token can be barebone:
https://gist.github.com/8a146c2f634d4f4430405b6f13ffbc70
Or it can include usage hints that will be incorporated when generating the output files or the style guide:
https://gist.github.com/9182292c609995a75a5d1c18df4c6761
A design token can also reference another design token:
https://gist.github.com/631706ae53f57a0ab4433a4fbb97e6e0
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:
https://gist.github.com/2c36feb8f3490cd00a2ef068a74c08cc
There's a collection of well-chosen functions available. For example contrast() calculates the luminosity of an underlying color and wil pick an appropriate contrasting color to ensure proper contrast and legibility:
https://gist.github.com/3f71d19f33197e39d5746f3eacbeeec1
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.
https://gist.github.com/3688b542fc4736c8553f789149c8d09f
https://gist.github.com/809dc1ac83ce2db90b34a3bde5fc71f5
Run this command:
https://gist.github.com/82356070206ea231c263cc307784c7ef
And chromatic will generate this file:
https://gist.github.com/321e85bcc4265947089694bf88787fee
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.
[1]https://medium.com/salesforce-ux/living-design-system-3ab1f2280ef7
[2] https://www.lightningdesignsystem.com/design-tokens/
[3] https://medium.com/eightshapes-llc/tokens-in-design-systems-25dd82d58421
[4] https://github.com/salesforce-ux/theo
[5] https://aws.amazon.com/blogs/opensource/style-dictionary-trust-design-consistency/