I’ve been hearing a lot about design tokens lately, and although I’ve never had to work on a project that’s needed them, I think they’re super interesting and worth jotting down a few notes about. As I understand it, the general idea is this: design tokens are an agnostic way to store variables such as typography, color, and spacing so that your design system can be shared across platforms like iOS, Android, and regular ol’ websites.
Design tokens are starting to gain a bit of momentum in the design systems community, but they’re not an entirely new concept. There’s a great talk with Jina Anne and Jon Levine from 2016 where they talk about how design tokens are used in the Lightning Design System at Salesforce. They describe the complexity of the world we’re living in where a single organization that is building multiple web apps and native applications need to feel and look the same whilst not slowing down the development team. Jina also has made an in-depth video course about design tokens and in the preview for that she writes:
With design tokens, you can capture low-level values and then use them to create the styles for your product or app. You can maintain a scalable and consistent visual system for UI development.
Let’s take just one example: you probably have a typographic scale that you want to be identical across a bunch of platforms. Instead of storing the values for that scale in a CSS file and replicating them in every app or website, they can be stored in a JSON file that will then be transformed into the code needed for all those other platforms. Something like this:
{
"global": {
"type": "token",
"category": "typography"
},
"aliases": {
"TYPE_SIZE_SM": {
"value": "14px"
},
"TYPE_SIZE_MD": {
"value": "25px"
},
"TYPE_SIZE_LG": {
"value": "44px"
}
},
You could write your own code to take this JSON file and convert it into all the variables you might need, for example, a Sass file would depend upon these tokens and might consume them as variables to be used elsewhere in a web app. One example of a tool that can do a lot of the hard work for us is Amazon’s Style Dictionary and here’s an example of how that works in practice:
I think this is ridiculously neat stuff. And I can see how it saves a ton of duplicate code and confusion across multiple teams since it serves as a single source of truth as opposed to having several codebases that have the same design requirements and their own stylesheets to maintain. Cristiano Rastelli also wrote about managing design tokens with Style Dictionary a little while ago and goes into a lot more depth on how to get started.
Your source of truth doesn’t even have to be a JSON file! In a post from earlier this year, Pavel Laptev shows us how to make these design tokens in Figma and, by using their API, abstract those values out of design mockups and use them in a codebase.
Pavel broke up his Figma doc into separate pages for his grid, spacers, palette and typography like this:

Right now, it seems like this requires a ton of effort to set up, but I reckon that tools like Sketch and Figma are only going to make stuff like this way easier for us in the near future – they probably want the source of truth to be in their specific design tool instead of some other tool.
The last thing I want to mention is this post by Brent Jackson where he wrote up some thoughts about interoperability when it comes to design systems. Specifically, he argues that there should be a specification for design tokens so that any CSS-in-JS library could consume that code in any format or style:
Design system tokens are meant to be flexible and work cross-platform, which means different teams, different implementations, and different libraries will name things differently. This is where this specification would fit in. A lot of interoperability could be realized, if we all, for example, named our color palette
colors
and named the font sizes we usefontSizes
. What you do beyond that and what data format you use to store these values, is up to you. It’s trivial to convert JSON to ES modules to YAML or even TOML, if that’s your thing. It’s also just a data structure, so transforming between other data structures (e.g. design tools or a GraphQL API) should also be possible. This standard also wouldn’t try to solve the extremely complex problems of how to name the colors themselves.
Brent then went ahead and created a theme specification to solve this very problem. It looks like having a single standard for writing all our variables and settings would help us if we wanted to switch from one CSS-in-JS library to another, or if we wanted to switch to some other system that we haven’t imagined yet.
Anyway, I believe that design tokens are only starting to become mainstream and their popularity is about to increase as these tools, workflows, and standards become better with time — it’s all thoroughly exciting stuff!
What is the advantage of doing it this way rather than having a separate .scss file with the CSS code and just keeping that as a standard part of the SASS you use?
Because the JSON or YAML file is agnostic to a particular language if your system needs to support web and native platforms. You can automate the process to build SCSS/iOS/Android variables. SalesForce also built Theo to do this: https://github.com/salesforce-ux/theo
Sass won’t scale to native iOS or Android. This method scales to these and any other platform you need.
Well, what if sass goes bye bye one day? As I understand it, you’ve got your global style info in a seperate file that can be used elsewhere where sass isn’t available maybe? It’s a pretty cool idea, but it’s just another file to manage in a sea of text files, as the author states, it’s probably something you’d manage with some sort of script automation or something
This is the first time I’ve been able to understand the actual purpose of Design Tokens via text. Thank you, Robin!
After years of losing control of design patterns and brand consistency to not-so-friendly dev teams, I stumbled upon the idea of using design tokens about 2 years ago. I’ve been integrating design tokens into all of my projects since then and it’s a game-changer for designers and maintainers of design systems.
Design tokens provide a way for designers to maintain complete control over the values in their design system. Your tokens are your single source of truth for keeping your design system values in sync with every other project in your organization.
I originally used salesforce’s theo, but quickly found out it’s, complex, inflexible, and honestly overkill. There are a ton of articles about design tokens out there but almost no info about how to actually implement them in projects, which makes adopting this workflow difficult — and it’s actually really, really simple. Check out the basic design token workflow I use in my projects: https://github.com/MindSculpt/design-tokens
Based on the application pulling in your design tokens, you can use different gulp tasks to output the format you need (JSON, CSS, YAML, SCSS, etc) for whatever use cases you have/will have.
Darkest timeline theory of use…
Could these tokens be locked behind a paywall, firewall or encrypted some way? I immediately thought of them as copy-protection for corporations and brands. Locking down brand colors, fonts and even layout schemes.
I can recall a time from the late nineties/early aughts when everyone was copying Apple’s bubble buttons, and even their website’s stark-lined look. You’d see copycat sites pop up that looked terrible, but had these elements that mimicked the site and OS. I can see how these tokens could be used to challenge these types of copycats in the future. If your site or application has a “protected” design element in it and it’s not pulling from a known depository… it could be proof that you’re “stealing” these intellectual properties.
But in the same vein, depositories of open source designs and elements could be built, which would match-up analytical developers with visual designers.
The concept is interesting and I can see the value in these tokens.
Personally I think this concept seems like way more unnecessary complexity in an effort to “keep things simple”. I like the idea of figma storing the version of truth because it does that very well and it’s easy for anyone to pick up and use, but using JSON and css together sounds dangerously strict and what about the maintainability? Maybe for large teams this makes some sense because I know some corporate people are obsessed with “pixel perfection” but I’m not convinced this is a good way for designers to work because it could set unrealistic expectations for the outcome of different applications.
Also, having a specific set of font sizes for multiple platforms seems like a bad idea and is a weird example to represent this concept. In theory, keeping everything consistent sounds practical, but in practice these sizes should be allowed to change based on the context with which the design is based in. Ie. tablet screens, hd screens, phones all will affect how we perceive a 14px font size.
I think developers and corporates like working with absolutes which is why design systems/tokens/ whatever other buzzword there is appeals to so many people. But my 2c as a designer and developer is that I personally prefer working with the actual css and not abstractions of it and we should trust developers more and developers should trust themselves more to make the right decisions. Good front end developers should understand design imo. And that goes both ways if you’re a designer working on the web.
That’s not actually how design tokens work though, Jaclyn. The beauty of tokens is they are also extendable and you can set different form factor contexts when needed. For many, though, you are right in that it may be more effort than what they need. But for some companies, like Salesforce — where they originated — this complexity is crucial to scale across their needs.