Design tokens to Developers using Figma Tokens plugin (version 88) with Style Dictionary (verson 3.7.0) (2022 article)
When I first heard about design tokens, my first thought was API . The idea of creating something in a format that can be used back and forth across entities is very API-like. The ultimate goal is to have two applications talk to each other. In this case it’s not just two software applications, but two types of departments or people, designers and developers.
For the sake of this article I will stick with getting design tokens to developers using two helpful tools, Figma Tokens Plugin and Style Dictionary CLI tool.
Figma, a popular design application, has a couple plugins available that let you define and export design tokens. One of those plugins is Design Tokens Plugin and the other is the Figma Tokens Plugin. For this article, I use the Figma Tokens Plugin:
Link to plugin to download into Figma:
Link to documentation of Figma Tokens Plugin:
The article Creating design systems with Figma Tokens by Marc Andrew does a good job going into detail about how to use the plugin. One nice feature of Figma Tokens Plugin is that it lets you PUSH AND PULL changes from a Github repo from within Figma, so you can update versions of your tokens file for whoever has pulled from the repo.
Designers can push changes to a Github repo and then developers can pull down the tokens.json file from the repo, use it in their project, and run the Style-dictionary build CLI tool as an NPM package in their code to convert the tokens.json file into a format of their choosing such as CSS format or SCSS format.
THE BASICS:
What are design systems and design tokens?
Right now it seems like design systems and design tokens are all the rage in front-end development and UI/UX design world. I’ve bookmarked over 70 websites on the subject of design systems and design tokens. You can click the link below to view my collection of links:
Agonsi from his article on Medium called Design Systems: The difference between a Style guide and Pattern Library, says:
I’d define a design system as a set of rules, principles, scheme or procedures that consist of visual style guides, pattern libraries, brand guidelines and values, documentation which forms the base of a shared design language that aids in building standard, efficient and consistent products.
It is important to note that design systems are like living things.They constantly evolve and develop alongside the product and at the advent of new technologies.
I like this definition of design systems. I included the line about design systems being living things because I think it’s really important that a design system not only exist but be updated and used on an ongoing basis.
One way to do this is to not only tell people about the design system but make them dependent on it. Being able to export design tokens as a json and convert that json into a style format that developers can use makes a design system a part of the software development lifecycle.
Design tokens are the visual design atoms of a design system defined using a key and a value or a collection of key/value pairs. Danny Banks from Amazon who is the creator of Style Dictionary explains what design tokens are in a youtube video titled Danny Banks and Kelly Harrop — style-dictionary by devtools-fm. I can’t believe there is only 392 views (as of 3/22/2022) of this video. It’s so great you must watch it to learn more about design tokens and style dictionary!
What is the best way to name design tokens?
Naming design tokens is a very important step when creating design tokens. It requires front-development knowledge and understanding of how CSS styles are created. In general you want to name tokens so that they are reusable and clearly state the token’s purpose. Below is a format Salesforce uses.
Unfortunately, I can’t go further into naming design tokens in this article. The article Naming Tokens in Design Systems by Nathan Curtis does an amazing job at showing different ways to name design tokens.
NOW ABOUT THE STYLE DICTIONARY TOOL!
I mentioned the creator of Style Dictionary Danny Banks of Amazon earlier. In the youtube video I referenced, he talks about the origins of Style Dictionary. A few years ago, he wanted to simplify how design tokens were handed off to developers. He was doing a pull request to update tokens manually for each type of developer project — a PR for the android app, a PR for the marketing site, a PR for swift app etc. A PR or pull request is a request to add or update code on Github repository where a website’s code is tracked. If the developer approves the request it becomes part of the code. Danny Banks created Style Dictionary, a CLI build tool available as a NPM package, so design token JSON could be configured and built for projects no matter what language they are coded in. Below is the link to the Style Dictionary website:
Style Dictionary has a basic configuration you can install that will create SCSS files. For the quick start guide, developers or design technologists can go to: https://amzn.github.io/style-dictionary/#/quick_start
Other than a few example configurations, Danny Banks leaves it up to the developer to decide how to transform the JSON token files using Style Dictionary. This requires some coding knowledge.
Here is the part of the youtube video where Banks talks about why he left it up to the developer to write configurations for Style Dictionary:
Watching this will give you a better idea of what Style Dictionary is.
I MADE A THING!
I created a practice project to show how to export design tokens, push them to a git repo and pull them down into my React app project, to transform with Style Dictionary into a CSS or SCSS stylesheet.
Work in Progress:
Ahh! Style Dictionary build tool doesn’t transform aliases!
I came to a stopping point with my project when I realized Style Dictionary was not converting aliases into the correct value. Besides defining the value for a design token with a direct value like a color or pixels, you can define the value of a design token referencing another token this reference value is called an alias. This is one of the purposes of having design token language so that you building off of your system and reusing basic tokens to create more complex tokens.
Design token Figma plugins authors try to remedy this by suggesting NPM packages that transforms alias and math values to raw values for Style Dictionary. Links to these NPM packages are below:
For the Design Tokens Figma plugin:
For Figma Tokens plugin:
Reference to the token-transformer NPM package is in the Figma Tokens plugin documentation in Github instructions near the bottom: https://docs.tokens.studio/sync/github
I wasn’t able to successfully yet use these npm packages to transform design tokens whose value was a math or alias form. I’m close though.
All in all I’m pretty stoked about Figma Tokens plugin and Style Dictionary not just bridging the gap between designer and developers but removing the gap completely.
Design systems are being referred to as the “one source of truth” or a shared “design language”. But that is all hype until one equals one and shared is actually shared in practice.
BONUS MATERIAL
If you are interested a whole platform called Backlight that has front end developers create a design system and then export tokens to the Figma Tokens plugin to import into Figma for the Designers, check out this youtube video by Backlight. Looks pretty exciting!
Matt Strom, a designer for Stripe, writes about creating a “Design API” for design tokens where developers can request design tokens calling an actual API. You can read more about it here: https://matthewstrom.com/writing/design-api-in-practice /
Nicolas Declercq has four articles on using the Figma API to turn design tokens into code. Part 1 starts here: https://medium.com/iadvize-engineering/figma-tokens-automatically-turned-into-code-how-we-kickstarted-our-design-system-51297b7d6b17
