Developing a token naming system for Buttercookies
Earlier this year, Cubyts transitioned from a DesignOps to a Product Observability platform, requiring the development of a new platform and design style, specifically, design tokens. I've enjoyed the challenge of creating an elegant, comprehensible, and scalable token language. In this article, I'll discuss how we defined tokens for both applications.
Why I wanted to write this
During the research phase, I referred to several design systems, particularly their design tokens documentation. Key references included Asana, Lightning (Salesforce), Atlassian, Spectrum (Adobe), and Canvas (Workday). I found it challenging to discern the logic behind a team's choice of token names, which was crucial. This issue was particularly relevant to color tokens, as all other tokens were comparatively straightforward.
What are design tokens?
Design tokens are UI components like colors, fonts, spacing, etc., used for consistent, cross-platform interfaces. They simplify updates, such as changing a common color. Instead of manual updates, a token (e.g., 'primary-500') is assigned and updated as needed, ensuring uniformity and simplicity. Among all aspects, color tokens are typically the most challenging and unique in a token naming system. The tokens for typography, borders, shadows, and spacing were derived from Tailwind.css, with a few alterations. I'll start with the color tokens for Buttercookies, followed by the other token types.
Colour Tokens
Colour tokens in most systems typically have two to three levels. In ButterCookies, we adopted a two-level system - Primitive and Semantic, following the structure of Figma’s variables. These are applied to text, backgrounds, borders, and icons.
ButterCookies V1
Primitive Tokens
We defined the initial palette of colours (primitive tokens) based on brand, use cases in the platform and accessibility.
Semantic Tokens
We then assigned the primitive tokens to semantic tokens based on use cases. We did this by using wireframes to identify all the use cases where colours are used and where contrast is needed. At the time, Figma hadn’t yet come out with variables, so we added the semantic tokens as colour styles and used them in our designs.
Initially, we adopted a structure suggested by Asana, consisting of Sentiment - Usage - Prominence - Interaction. However, this proved too complex and unscalable due to the numerous variables, and our team members struggled to grasp the logic. We also erred in trying to accommodate all possible use cases, regardless of their frequency of use.
We then simplified our approach to focus only on application, selecting suffixes based on their occurrences. This was more straightforward and easier to comprehend. We also decided to employ the 80/20 principle, creating a few tokens to accommodate the most common use cases.
'Default' is the most used color, like grey for icons and black for text. 'Primary' is the main color, for link button text or primary button background. 'Extra-light' is significantly lighter than the default, used in cases like disabled text. 'Inverse' contrasts with the default, such as a dark background instead of a typical light one.
ButterCookies V2
Transitioning to a new platform, we designed for a dark theme but wanted adaptability to light mode. To meet deadlines, we modified existing tokens for the new platform. We created variables with different hex codes and tried adapting Figma's modes to switch between light and dark without separate designs. Old tokens were limiting as their names didn't consider dual modes, creating confusion. For instance, white text in dark mode was "text default" and in light mode was "text-inverse", which was inconsistent when used in a primary button with a purple background and white text in both modes.
Primitive Tokens
Initially, we intended to split token palettes for light and dark modes. However, with Figma variables, we could use the same palette for both, switching the layer style as needed. This led us to merge the light and dark palettes, except for neutrals due to significant hex code variances. Razorpay’s Blade Design System was instrumental in defining these color tokens.
Semantic Tokens
We identified use cases of states such as normal, hover, and disabled for semantic tokens. We also considered general occurrences like muted, bright, and subdued, moving away from terms like light and very light. To cater to the same use case in different modes, we introduced suffixes like 'On Primary' where necessary. Although this resulted in a larger number of tokens, they are now very specific, making it easier for designers to find the right token for their needs.
We also created unique tokens for tags and toast components due to their distinct usage and behavior compared to general tokens. As a result, we have developed a flexible and nearly fully interchangeable token system. This system has a 95% success rate in changing the mode of a component and achieving the desired colors.
Typography Tokens
Our design system incorporates Tailwind.css as the CSS library, and we've adopted its sizing mechanism to maintain consistency. For instance, 'lg' is always 18px, 'base' is 16px, 'sm' is 14px, and so forth.
To accommodate our specific needs, we've used prefixes like 'Heading', 'Label', 'Label-2', and 'Body' for different font applications.
Border-Radius Tokens
We used the scale provided by tailwind.css for border radius. However, there were specific sizes recommended by Tailwind that we didn't use and a few that we had to newly introduce. For example, 20px isn't used in the Tailwind library, so we introduced it as 2.5xl. Notably, 20px falls between 16 and 24px, both of which are recommended by the library.
Spacing Tokens
Spacing tokens were also directly adapted from Tailwind.css library. When needed, we introduced certain custom tokens to fit in the framework.
Resources
Blade Design System - For the way they’ve defined their variables
DBBanks - Multiple references to specific aspects about different design token systems. They also provide references to many existing systems.
Material Design - In depth breakdown of token structures and best practices
Tokens in Design Systems - Helpful guide to understanding the basics of token naming
Takeaways