Managing Design Tokens Using Storybook

TL;DR: I built a storybook addon generating design token documentation from your stylesheets and asset files.

Check out the demo here: https://storybook-design-token.netlify.com/

As a frontend developer I've built a number of ui component libraries enabling product teams to build software according to the underlying design systems. In doing so, one of my major issues has always been keeping design and development in sync. Translating the design language, in my case most likely delivered in form of various Sketch files, into code is an ongoing process with design changes throughout the entire lifecycle of the design system.

To narrow the gap between design and development, I like to evaluate ways to move as much of the design system documentation into the browser and create a single point of truth for crucial parts of the design system. That means going beyond ui components and looking into the underlying design language. While tools like Sketch and Figma are great for drafting, prototyping and conveying the look-and-feel of your software, they scatter the design system's knowledge, making it harder to find and access these information. Putting them closer to the actual products (i.e. the code) helps to maintain a living documentation that has fewer risks of getting outdated.

Design Tokens

While components provide the building blocks of our products, design tokens define a set of properties we can use to shape our components appearance. Typically they define things like typography, colors, spacings or the iconography of a design system. Have a look at Salesforce's collection of design tokens to get some nice examples. Brad Frost recently put design tokens in context of his atomic design principles.

The neat thing about design tokens from a developer's perspective? In most cases, they can be described as variables (e.g. css custom properties or sass variables) and assets like icon files.

Managing Design Tokens with Storybook

Storybook is a great tool for developing reusable component libraries in an isolated environment, while also creating neat visual and technical documentation for the product teams using your library. I highly recommend you give it a try if you need to build a reusable component library. It works great with all major JavaScript frameworks or just plain HTML and CSS.

Design Tokens as Stories

Storybook uses stories to describe components and their different states. These stories are written by the developer in form of small templates showing example usages of the components. IBM's storybook provides a nice example with a variety of components.

My first attempt getting design tokens into Storybook was by manually writing stories listing our tokens in form of some simple html tables. That got messy very quickly. Instead of syncing the tokens between my component styles and Sketch files, I now had to sync between component styles, Sketch files and my stories. Furthermore, I found myself constantly jumping between the design token stories and my component stories to find the correct tokens I wanted to use in my components. (Storybook only shows you one story at a time.)

Introducing the Storybook Design Token Addon

Luckily, Storybook provides a great API for addon development that you can use to augment your stories. There are some great addons that automatically generate component documentation, provide a11y testing, display source code, and much more.

Struggling with my manually maintained design token stories, I decided to write an addon that would display all our design tokens alongside the component stories while also eliminating the need to manually maintain the design token lists. It does that by parsing css or sass stylesheets and asset files (only SVG files at the moment) to generate design token documentation, complete with rendered examples. Further it allows you to organize the design tokens in groups, using annotations in your stylesheets. This way you can also define how token examples should be rendered (e.g. as a color, border radius, box shadow, …). Below is a small example of annotated tokens in a css stylesheet.

/**
 * @tokens Colors
 * @presenter Color
 */

:root {
  --n0: #fff; /* Optional token description */
  --n100: #fbfbfb;
  --n200: #edeeef;
  --n300: #e4e5e7;
  --primary: var(--n300);  /* --primary will be listed as an alias of --n300 */
}

/**
 * @tokens Border Radius
 * @presenter BorderRadius
 */

:root {
  --border-radius-m: 4px;
  --border-radius-l: 8px;
}

Have a look at the demo to see what it does, or check out the repo for a more complete feature list and usage guide.

I would really love to hear your feedback. Could you make good use of the addon? How do you handle design tokens in your design systems? With its latest beta release, Storybook is introducing more tools to document your design system in the browser. Do you see design deliverables moving away from static design tools and towards the browser?