DEV Community

Cover image for Design Tokens: what are they?
tom hermans
tom hermans

Posted on

Design Tokens: what are they?

The Benefits of Design Tokens: Enhancing Collaboration and Consistency

Design tokens are powerful tools that facilitate collaboration between designers and developers while ensuring a consistent and cohesive look and feel throughout a project. In this blog post, we'll explore the advantages of design tokens in layman's terms, by means of a restaurant analogy. So, let's dive in and discover how design tokens work and why they are crucial in modern design and development workflows.

Design Tokens: A Savory Recipe for Consistency

Imagine you are a chef in a renowned restaurant, responsible for creating mouthwatering dishes that customers love. To achieve this, you use different ingredients like spices, vegetables, and meat. Each ingredient contributes to the unique taste and presentation of your dishes.

Similarly, in the realm of design, designers use various design elements like colours, typography, spacing, and more to create a visually appealing and consistent look for websites and apps. However, keeping everything uniform can be challenging, especially when multiple designers and developers are involved. This is where design tokens come into play.

Design Tokens: Your Special Ingredients

Design tokens can be likened to ingredients for your special recipes you create for your kitchen. Instead of using individual ingredients every time you cook a dish, you craft specific combinations of spices, vegetables, and meat that represent a particular taste and style. These "design tokens" (or recipe ingredients) make it easy for all the chefs in the kitchen to cook dishes that taste and look the same, regardless of who is doing the cooking.

In the design world, design tokens are pre-defined values for colors, typography, spacing, and other design properties. Designers use these tokens when creating the visual elements of a website or app, just like chefs use their special recipes to create delectable meals.

In our restaurant analogy, imagine that you, as the chef, have written down all your special recipes in a cookbook. This cookbook is like a guidebook for all the other chefs who work with you. They refer to this cookbook whenever they need to cook a dish and use the exact combination of ingredients and cooking instructions to ensure consistency.

In the world of design tokens, developers have access to a similar guidebook, often referred to as a "design guide." This design guide should contain all the design tokens and guidelines that designers and developers follow when building the website or app. The design tokens in the system act as a common language, allowing both designers and developers to communicate effectively and work together seamlessly. It creates a common languages, highlights necessary information that's needed for all parties.

Day to day workflow between a designer and a developer in an agile context.

On a regular workday, the designer and developer collaborate to implement the client's design requirements efficiently. The day usually starts with a project meeting, where the client provides feedback or requests specific design changes. For instance, they might ask for more subtle shades of grey in the design. The designer takes note of the client's feedback and uses design tools like Figma to create new design concepts. They pick appropriate shades of grey from the design tokens library, ensuring consistency with the overall design system. Once the design is finalized, the designer shares it with the developer by updating the file and exporting the tokens to the shared JSON repository. The developer imports the design tokens from the external JSON repository and updates the CSS variables or custom properties in the codebase to incorporate the new greys. The developer might also notice some issues with the usage of tokens now the actual website or app is being updated with these (e.g. color contrast, e.g. font or viewport issues etc ..) and can conversely also edit the tokens and upload these changes to the repository. The designer is being informed and can easily sync his Figma file again with the tokens repository. The designer and developer collaborate closely to resolve any implementation challenges and ensure the new design elements are correctly integrated and pass the necessary tests. This streamlined collaboration process, powered by design tokens, allows them to efficiently work together, resulting in a cohesive and visually appealing user interface that aligns with the user’s needs.

The Benefits of Design Tokens

Let's explore the benefits of design tokens in detail:

  • Consistency: Design tokens ensure that the entire website or app has a consistent look and feel because designers and developers use the same set of values.

  • Efficiency: By using pre-defined design tokens, designers can speed up the design process, eliminating the need to come up with new styles from scratch.

  • Scalability: Design tokens facilitate easy scaling of websites or apps without compromising on consistency, just like opening new branches of your restaurant while maintaining the same delectable taste.

  • Easy Updates: Designers can update design tokens to reflect changes or improvements, and developers can use these updated tokens without breaking existing components.

  • Collaboration: Design tokens foster collaboration between designers and developers by providing a common language for discussing design elements.

  • Adaptability: With design tokens, designers and developers can apply popular styles or colors consistently wherever needed, adapting to changing trends and user preferences.

Using External JSON Repository for Design Tokens

To further enhance the benefits of design tokens, an external JSON repository can be utilized to store and manage these tokens effectively. Here's how the process can be implemented:

  1. Create a Design Token Specification: Define a clear specification for your design tokens, including their names, types, and values.

  2. Set Up an External JSON Repository: Choose an external JSON repository to store the design tokens, making it easily accessible to designers and developers.

  3. Organize JSON Files: Create separate JSON files for different categories of design tokens, maintaining a modular and organized structure.

  4. Host the Design System Platform: To streamline access and usage of design tokens, host a design system platform or tool that manages the tokens efficiently.

  5. Import Design Tokens in the Codebase: Import the design tokens from the external JSON repository into the codebase, using appropriate technologies like CSS variables or custom properties.

  6. Collaboration and Updates: Collaborate using the design system platform to make updates or additions to the design tokens, ensuring a synchronized workflow.

  7. Version Control: Utilize the version control capabilities of the external JSON repository to track changes and manage updates seamlessly.

By employing an external JSON repository and a design system platform, designers and developers can collaborate effectively, reducing inconsistencies and ensuring a cohesive user experience across projects.

Now how does a token look like ?

Usually we have value, a type and sometimes a description too when it’s not obvious.

    "tokenname": {
        "$value": "token value",
        "$type": "color",
        "$description": "Description of this token"
Enter fullscreen mode Exit fullscreen mode

A real life example would look like

    "colors": {
        "$type": "color",
        "accent": {
            "base": {
                "$value": "#F8C307",
                "$description": "Primary color of our brand"
Enter fullscreen mode Exit fullscreen mode

Here, you can see that tokens can be nested in groups and that a type can apply to a group and an individual token.

You may also have variants for this token, or state dependent values, e.g. for hover or active states, or for dark or light mode, or viewport size for instance.

It may make sense to group in this order: variants -> states -> parts -> etc., but this is not a trivial choice to make; it can be tricky representing a multi-dimensional matrix of variations into a JSON object.

For a button element, this might look something like this:

  "button": {
    "variants": {
      "base": {
        "bg": { "$value": "{colors.primary}" },
        "color": { "$value": "{colors.text.light}" },
        "border": {
          "radius": { "$value": "{}" }
        "padding": {
          "vertical": { "$value": "{spacing.s3}" },
          "horizontal": { "$value": "{spacing.s4}" }
      "secondary": {
        "bg": { "$value": "{colors.secondary}" },
        "color": { "$value": "{colors.text.light}" },
        "$extends": "{button.variants.base}"
Enter fullscreen mode Exit fullscreen mode

See how we reference tokens themselves in this. Colors and Spacing are a set of tokens themselves, and can be applied to the button styling. Say, in this way, you want to change all the colors of the button component, you don’t need to go in there, but you can also change the token set where they get their information.

Also: note that usually tokens are colors, spacing, typography scales and these are the easiest to explain and why I used ‘em in this article, but you can think beyond that. Box-shadows come to mind, border-radii, border-widths, opacity, ..


Design tokens are the secret recipes that bring consistency and efficiency to design and development workflows. Like a well-organized kitchen with special recipes, design tokens empower designers and developers to create beautiful and cohesive interfaces with ease. Leveraging an external JSON repository and a design system platform enhances collaboration, makes handoff so much easier and less error-prone, streamlines updates, and fosters a delightful user experience for everyone involved in the creative process. So, embrace the power of design tokens, and you'll be serving up visually appealing digital experiences that leave your users craving for more

Some extra resources I’ve read and made me inform myself on the topic over the years:

Top comments (0)