Design tokens: what are they and how do they work in Visly?
Keeping code in sync with designs is probably one of the most frustrating and tedious things about design/developer collaboration. The constant interruptions by designers, the lack of priority by developers and the constant back-and-forth between both can be the stuff of nightmares. Design tokens aim to ease those nightmares. More than just a trendy buzzword, design tokens offer a versatile way of sharing design properties from a central location. When combined with Visly, they vastly improve your workflow, productivity and collaboration.
What are design tokens?
Design tokens are one of those things you’ve probably heard about but have no idea what they are. The fact is, a lot of people have been using design tokens without realising it — they are essentially just variables. The Salesforce Lightning design system team, who coined the term design tokens, defines them as the following:
Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.
Let’s put that definition into context. Take a look at this simple button component. There are essentially two different layers, a container layer and text layer.
Applied to those two layers are a number of variables or ‘design tokens’. Here, there are several variables applied to the layers — background-color, border-radius, font-size, padding and so on. Hard-coding all of these variables can lead to some obvious and tedious problems: repetitive code, lack of scalability, difficultly to update quickly...the list could go on. But with design tokens, that list is removed completely. Tokens replace those hardcoded variables with something that is scalable, easily editable and that can used across different platforms.
How do design tokens work in code?
If you’re building an app and don’t have a design system team like Salesforce, the chances are that you are copy pasting hex codes and a bunch of other CSS properties. This leads to a lot of back and forth between design and development due to small mistakes, repetitive code and tedious work.
A more organised way of managing design tokens can be done through a JSON file. Instead of repeating code for every component or platform, you reference the values from this centralised design token file that contains the variables. The file is then translated into the specific code needed for the platform. Say your designer decides to change the app border radius from 4px to 8px; you could update the design token centrally. In turn, it would be updated across all of your components.
Below is an example of some design tokens in JSON format.
{
"colors": {
"primary": "#fdd110",
"secondary": "#ea1c5c",
"tertiary": "#55dde0"
},
"fonts": {
"base": "Inter",
"mono": "Roboto Mono"
},
"padding": {
"xsmall": 4,
"small": 8,
"medium": 16,
"large": 24,
"xlarge": 32,
}
}Problems with JSON files
JSON files provide a neat way of referencing tokens from one place across multiple platforms, but it doesn’t fully improve the workflow for a developer or a designer. They still require managing multiple tools to handle the code translation and don’t remove the back-and-forth between design and development. Those interruptions with Slack messages like, “Hey 👋🏽 can you update that padding-small token from 4px to 5px?” don’t quite go away.
Another issue with working with JSON files is that while the naming of tokens creates a common language, you still don’t get to visually see what you’re working with. Instead of remembering hex codes, you’re remembering token names and still guessing what the end result will look like.
While JSON files act as a ‘single source of truth’, it really depends who you’re talking to. For a designer, their source of truth is a design tool. This is where the design system is created and where they create and edit design tokens, meaning it still requires a developer to implement and update the tokens in their ‘source of truth’ — code.
So while JSON files are a much better solution to repeating code, they don’t solve all the workflow issues around them. There is still a dependency from both designer and developers, no real source of truth and extra management needed. Visly takes care all of these problems (and more).
How do design tokens work in Visly?
Visly is a design tool where developers can rapidly design and build production-ready components. It acts as a tool to manage design systems that today live in code and design files, making Visly a quicker and more powerful way to build React components.
Visly enables you to visually manage and sync design tokens directly with your codebase. No copy-pasting. No exporting. No manual work. Visly supports tokens for colors, icons, fonts, text styles, spacing, size, radius and shadows. A big part of what makes tokens powerful is the collaboration aspect. Whether you’re a developer or designer, Visly makes it quick and easy to make updates to tokens.
In Visly, design tokens can be found in the right-hand sidebar on the home tab and in the editor. This is where you can get a quick overview of all of your tokens. Here you can create, edit and manage your tokens. The best part about this is it’s all visual. You can actually see a realistic preview of your tokens so you know what you’re working with.
Referencing a token in the editor is done via the token button. Sections that support tokens in the editor have an icon button that opens a token picker. Here, you can visually select the tokens you want to reference and save new ones to your library.
There are certain tokens that cannot be edited or deleted; we call these system tokens, and they’re limited to a few icons and fonts. The reason these can’t be deleted is that they’re used as the default tokens when creating new components. While you can’t delete them, you can choose not to use them. If you don’t use them, they won’t be included in the final bundle of your app.
Let’s take a closer look at each token type in Visly.
Colors
Managing color palettes should be visual. Hex codes aren’t. With Visly, you can see the colors you are working with and use them directly in your components and in your codebase. Visly supports Hex, RGB and HSL colors and you can easily switch between them using the color picker.
When you’re building a component, you can use the token picker to visually select a color from your palette. Even if you don’t have any color tokens saved, it’s easy to create new ones directly in the editor. Simply click on the token button and add the hex code to your library.
Icons
If you’re building an app, it’s likely you are adding and editing icons all the time. This can be a pain when you are trying to keep your code in sync with the latest designs. Visly enables you to always have updated icons without the hassle. You can simply drag and drop your PNG or SVG files into the app and use them straightaway in your components. Open the token picker and see a visual grid of all of your icons — forget copy-pasting file names.
Fonts
Adding custom fonts to Visly is easy. Like icons, you can simply drag and drop your .OTF and .TTF files into the app and start using them straightaway. In the tokens sidebar and font pickers, you can visually see the styles you’re working with, so you can easily see the difference between fonts like Inter, Open Sans and Roboto.
Text styles
While text styles are not typically considered design tokens, as they are made up of several smaller tokens, remembering all of those properties to create a text style can cause a headache. In Visly, implementing them is trivial. Forget copying, pasting, and updating multiple text properties. You can preview, edit, and reference a single style.
Using the text style pickers makes it even easier to choose a style to use in your component, as you can see the style and font size. You can forget remembering names of different text styles. Like colors, you can easily save a new token by clicking on the ‘add text style row’ inside the text style picker.
Size tokens
In Visly, size tokens are used for dimensions, spacers, radius and padding. Using size tokens is a great way of making sure all of your components have a consistent style. When you create a size token, you can choose whether to use it in every size section or in specific ones. For example, if you wanted to create a size token for corner radius, simply go to the tokens panel, select ‘radius’, enter a value and choose a name.
Once you go into the editor, select the icon button inside the corner radius input to display the tokens. You’ll notice that the token only appears in the corner radius section. This allows you to create size tokens that fit your system. So, whether you have global sizes for every component, or specific ones, Visly will work for you.
Shadows
Instead of Googling how to create a box-shadow, you can visually create a drop or inner shadow in Visly. Edit the X, Y, blur and spread easily and forget remembering a bunch of CSS properties. Like other tokens, you can save your shadow tokens directly in the editor whilst building components via the token button.
How to use Visly Tokens in code
Visly tokens can be referenced as variables within Visly when building components, as well as imported in code and used outside of Visly components. Using tokens in code works just like importing any other javascript module. If you’re using TypeScript, you will even get autocompletion for all of your tokens.
import { colors, icons, textstyles } from './visly'With the exception of fonts, all other tokens can be imported directly from the generated code module. Fonts should not be referenced directly; instead, they should be referenced through text style tokens.
Colors are imported as an rgba() color string, icons as a relative path (to be set on the src of an image tag), and text styles as an inline style object. You can use these tokens together with components written in code, as well as components built in Visly.
import { colors, icons, textstyles } from './visly'<div style={{background: icons.heart}}/>
<img src={icons.heart}/>
<h1 style={textstyles.heading}/>
Tokens can also be used together with css-in-js frameworks such as styled-components.
import { colors, textstyles } from './visly'
import { styled, css } from 'styled-components'const Link = styled.a({
...textstyles.body,
color: colors.accentDark,
})
Tips for bulletproof tokens
Give token names context
Token names are important. Not only is this how you’ll reference the tokens from within Visly as well as from code, other members of your team will be using them too. Using a naming convention that is contextual makes life easier for everyone. Don’t worry about repeating the same hex code twice. If you use the same base color for text and borders, create a context-specific token for each. Doing so will provide a clear instruction on how to apply the options available. As a designer, you can trust your developer. As a developer, you can build with confidence.
Scales for size
Give yourself a variety of options for different size tokens based on a scale that makes sense. Most design systems use an 8px scale (some with 4px added for flexibility). Doing so will allow you to have a XS, S, M, L, XL type progression, making it easy to make decisions when building components.
Elevate your shadows
Material design describes how UI has different levels of elevation. Shadows help to express the degree of elevation between surfaces so you should create your shadow tokens with this in mind. Components at a higher elevation have a larger shadow, while those at a lower elevation have smaller shadows. Develop a system so that components like tooltips and toasts have different levels of elevation to give your UI depth.
Collaborate
It’s important to work on building out tokens collaboratively as everyone in your team will be using them. Develop a system or methodology with your team so that it works for everyone. Doing so will enable you to build with a common language and with consistency.
If you’re looking to level up your frontend development process, make sure to sign up for Visly. We’re excited to see what you build!
