Design Tokens Generator: design-tokens.dev Design Tokens Generator Main Concepts

Read this article on Medium

Design Token Generator Main Concepts

Design Tokens Generator (the App) respects and meets several important requirements for design and web-development.

We all want to execute project development faster while maintaining visual consistency and adding that special touch to make it shine. But it’s equally important for design and frontend code to be scalable and maintainable.

This is where design tokens come in. With the Design Token Generator, you can create more than just a theme; you can establish a comprehensive and systematic design layer with a clear naming convention. It provides a robust scaffolding that allows for seamless expansion and adaptability in your projects.

Now, you might be thinking that this all sounds a bit overwhelming. But fear not! The primary aim of the App is to make design tokens more approachable and user-friendly for designers and web developers. We understand that generic open-source solutions can often be overly complex and impractical for your specific needs.

Simplicity and rationale is our motto, let it be your motto as well!

Design Tokens in a Nutshell

Design Tokens were introduced a while ago and have quickly gained prominence in the modern design ecosystem, especially for complex projects spanning multiple platforms and brands. In simple terms, a “design token” refers to a platform-agnostic design value that serves as an atomic part of a design language. For example, the brand color or body font-size would have the same values across design, frontend, and mobile app development code. Any updates made to these values would be automatically reflected in all environments. The establishment of a source of truth and a robust pipeline for managing these tokens is an important consideration for you and your team.

However, it’s not enough to have a few variables in place. A systematic approach to naming these tokens is essential. This becomes particularly critical for design system creators and maintainers, whether they are internal or part of an open-source project. The level of specificity and proprietary naming conventions may vary depending on whether it’s an internal UI kit or a generic public UI library.

The Design Token Generator provides an organized framework for the hierarchy and naming of design tokens, with a focus on small- to mid-scale web and app development projects. It offers an opinionated yet practical approach to naming conventions, drawing from practical experience and accumulated knowledge. The learning curve is natural and intuitive, allowing you to quickly adapt and utilize the generated tokens in your projects without the hassle of extensive scaffolding.

Terminology

The organization of the Design Token Generator is straightforward and easy to grasp. Design tokens are grouped into compact sets known as… Sets. These Sets are then combined into larger groups called Collections.

We have organized the Design Token Generator into five Collections based on design domain principles. Each Collection may consist of one or more Sets. This simple and intuitive structure allows for efficient management and customization of your design tokens.

Now, let’s delve into the details and explore the powerful capabilities of each Collection.

The Five Emojis

Before we dive into the details of each Collection, let’s take a moment to appreciate the DTG logo from both perspectives.

Design Tokens Generator - Logo Front Design Tokens Generator - Logo Back

The five icons or emojis showcased here represent the four cornerstones of the design tokens organization, all revolving around one core element.

Cog ⚙️ represents the most Generic properties, which may not necessarily be design-specific or applicable to mobile app development (i.e. root-size).

Crown 👑 represents the Content, known for its regal prominence. In the context, it encompasses typography and text visualization.

Palette 🎨 naturally embodies Colors, one of the most impactful and extensive Collections.

Alien 👽 signifies Space and Dimension. For simplicity, we haven’t made a distinction between these design terms, and this generalized approach has proven effective thus far.

And lastly, the Devil 😈 personifies the Details. This Collection adds that extra touch to your visual language, injecting personality and flair.

Now that you are familiar with these concepts, let’s dive into the practical aspects of each Collection and explore the Sets they contain.

Collections and Sets (as they appear in the App)

Palette Collection 🎨

As mentioned earlier, the Palette Collection is the largest in terms of both Sets included and the overall number of tokens. When it comes to organizing colors, there are tons of approaches out there, each with its own pros and cons. We’ve carefully curated the most commonly used color groups and categorized them as follows:

Brand colors consist of the Primary, Secondary, and Accent color Sets. In most project scenarios, these Sets provide ample representation of a brand, especially in the era of minimalism and brutalism.

Util colors encompass the Safe, Alert, Info, and Warning color Sets. This category is designed for elements such as loading indicators, error messages, notifications etc. The naming convention here is slightly more generic to cater to a wider range of use cases.

Foundation colors include the Gamma, Base, and Contrast color Sets. Gamma is a comprehensive array of 20 progressively changing shades of a fundamental color (typically black or white, but it can also be the darkest or lightest color in your project).

Base and Contrast Sets inherit values from the Gamma Set and often represent the background and content colors, respectively. When used together, such as a dark text on a light background or vice versa, these combinations ensure high contrast and improved accessibility. The same principle applies to setting the contrast colors for the Brand colors. These values are calculated automatically, preventing low contrast issues.

Text colors constitute a standalone Set. Similar to Base and Contrast, Text colors (mostly) rely on the Gamma array to define their composition.


Let’s take a closer look at the structure of a color Set (aside the Foundation colors for now). The color Set is comprised of the following values:

  • base: the lead color itself
  • contrast: the color that provides sufficient contrast to the base color (values are inherited from the Gamma Set)
  • tint: a brighter and more intense variation of the base color
  • shade: a darker and less vibrant variation of the base color
  • tone: a mixture of the base color with a neutral gray

Within the App’s controls, you have the ability to set the lead color, and the other values are calculated automatically. For the Gamma Set, you can also define the lead color, although the options are more limited due to the natural contrast restrictions of the palette.

Additionally, you can adjust the gamma progression control. In most cases, using the shades or tints options will suffice. However, in certain situations, experimenting with tones can help achieve a lighter, low-contrast gamma for the base colors.

Text colors are defined by the following tokens:

  • regular: the most commonly used color for text in your project
  • strong: an emphasized version of the regular color
  • subtle: a diminished version of the regular color
  • accent: an accentuated text color based on the selected color tone

Depending on your primary theme, you may also need to switch (or invert) the Text colors. By default, they will use the tail end of the Gamma Set to meet the contrast requirements. Feel free to experiment with the Gamma and Text settings to achieve the most suitable result for your specific setup.

Content Collection 👑

The Content Collection focuses on three essential Sets: Font Size, Line Height, and Icon Size. While some systems may omit Icon Sizes, it is more common to have icons proportionally larger than text characters, typically by a certain factor (e.g., 25%).

Both Font Size and Icon Size Sets share similar naming and settings options. The naming convention follows a “t-shirt” approach, with tokens ranging from xs to xxl. The base n value is set to 1rem (16px) by default as the reference point. All other values are then calculated based on the chosen scale setting, which determines the progression of the tokens.

Each scale option represents a multiplier that builds upon the previous value. For example, with a major third scale, if n equals 1rem, l would be 1.25rem, xl would be 1.25 * 1.25 = 1.563rem, and so on.

In general, higher scale values result in more distinct differences between the tokens, while lower values offer more subtle variations. For blog and e-commerce websites, selecting a minor third or major third scale is often suitable. For landing pages and marketing projects, a perfect fourth scale or higher may be preferred.

It’s worth noting that Font Size and Icon Size Sets can have separate scale controls. This can be useful when you need to visually emphasize icons. However, in most cases, the progression factor for both sets remains the same.


The Line Height Set is composed and controlled slightly differently due to the specific nature of this property. Typically, fewer values are needed for line heights. The tokens in this Set include:

  • regular: equal to the base value, which can be selected separately
  • tight: a lower value usually applied to headings and condensed text sections
  • loose: a greater value that can be applied to more spacious content elements

Similar to Font Size and Icon Size Sets, you can adjust the progression factor for Line Height. The principle remains the same, although the differences in scales may not be as noticeable. It’s important to find the right balance for your project. In most cases, a perfect fourth scale provides satisfactory results.

Space Collection 👽

Get ready for a space jump and a precise landing!

The Space Collection consists of two groups of tokens: the main Set and the auxiliary Set. The auxiliary Set exposes some proprietary values while inheriting others from the main Set.

The Spacing Set offers a range of spacing tokens, distinguished by a numeric-style naming convention. These tokens cover sizes, measurements, offsets, dimensions, and more. Here’s a sample of the tokens in the set:

...
space-075
space-100
space-125
...

In this Set, space-100 serves as the base token, and all other values are calculated based on a progression factor. The numeric part of the token name represents the progression factor. For example, space-075 is equal to 75% of the value of space-100. You don’t need to memorize every value in the array; knowing just one token is sufficient, as the rest are relative and easy to derive. This approach is more practical and intuitive compared to abstract names like size-a or offset-3.

You may have noticed that the progression of the Spacing Set scale is (almost) linear, unlike the typography generation style. This opinionated but popular approach originated from design principles. In most cases, you can rely on a standard grid with 2 or 4-pixel increments, which doesn’t require complex offset setups and is easy to maintain.

Of course, there may be situations where the scale doesn’t satisfy specific measurements. In such cases, there’s no need to include them in the scale unless they are frequently used alongside the rest. If you occasionally require a value like 3.5rem, you can calculate it on the spot, such as in CSS: calc(var(--awsm-space-100) * 3.5). It’s advisable to use the base space-100 value in such cases for better code maintainability.

Additionally, you have the option to add custom spacing tokens. It’s recommended to name them based on their use cases for better association. While projects may initially be similar, over time they can generate various patterns that are worth tokenizing.

This covers the rationale behind the Local spacing Set, which includes specific pattern-like tokens that are useful in web and mobile app development. Feel free to experiment with these tokens according to the needs of your project.

Details Collection 😈

Details are the “spices” of the design system. While an app can sure be functional without them, adding details can elevate the user experience. However, too many details can make the app overwhelming.

Sets in Details Collection are not directly related. The only similarity is that they can inherit Color and Spacing values from the other Sets. Same can be said about their settings and controls - due to varied nature of the tokens there are no common rules.

Let’s explore each Set separately:

Radius: This Set includes tokens for defining the radii of elements. The tokens include standard values like small, medium, and large, as well as auxiliary tokens like round and pill that refer to the shape of the element. The progression scale for radii is partial, providing flexibility in defining the roundness of elements.

Shadow: This Set includes custom, natural-looking shadow tokens along with the tint color. The shadow tokens are named small, medium, and large for consistency. The tint color can be modified based on the design needs of the project. Typically, the tint color is based on black or very dark shades of gray. However, if your project involves light and colorful backgrounds (like the App itself), you may need to revise this approach to achieve a more natural look and feel.

Duration: This Set includes a progression of tokens for controlling transitions and animations in the application. There are five tokens available: instant, short, regular, long, and extra. These tokens allow for granular control over the matters of time and their names highlight that.

When selecting a base value and scale for the timing tokens, consider that the duration of transitions should be proportional to the size of the element. Larger elements generally require longer transitions, while smaller elements benefit from shorter and more responsive animations.

Progression scale can help to tweak the look and feel of the application. For example, if you need to emphasize the virtual weight of some elements (i.e. Drawer or Modal) and make small elements (Icons and Buttons) even lighter and responsive, try higher values of the scale (i.e. perfect fifth). For more neutral or strict look and feel choose lower base value and lower scale.

Selection: This Set enables you to control the colors for content selection in your project. While often overlooked, customizing the selection colors can add an individual touch to the overall design. In CSS, you can implement the selection colors using the ::selection pseudo-element, as shown in the example:

::selection {
  background-color: var(--awsm-selection-background);
  color: var(--awsm-selection-color);
  text-shadow: none;
}

Each Set in the Details Collection has its own specific nature and settings, allowing you to add fine-grained details and customization to your application.

Core Collection ⚙️

The Core Collection consists of a single Set with an extremely important token that allows you to globally control the scale of your application. The token in this collection is called root-size, and it represents the font-size value that can be applied to the root element (usually html in web projects). By default, in most modern browsers, the root font size is set to 16px.

Utilizing rem units with the root-size token enables you to achieve a consistent visual style for your application regardless of the resolution and rendering medium. It also helps ensure accessibility compliance when it comes to zooming in or out.

You can use the root-size token in calculations for relative values. For example:

html {
  font-size: var(--awsm-root-size);
}

@media (min-width: 1200px) {
  html {
    font-size: calc(1.25 * var(--awsm-root-size));
  }
}

You can also introduce additional proprietary tokens to enhance the responsiveness of your interface, especially when dealing with fluid typography. Here’s an example:

html {
  font-size: var(--awsm-root-size);
}

@media screen and (min-width: 1200px) {
  html {
    font-size: clamp(var(--awsm-root-size), 0.5vw + 0.5rem, var(--awsm-root-size-max));
  }
}

In this case, the font-size of the root element is set using the clamp() function, which allows for a range of values based on the viewport width. The minimum value is var(--awsm-root-size), the maximum value is var(--awsm-root-size-max), and there’s also a fluid component based on 0.5vw + 0.5rem.

By controlling the root-size token, you can achieve a consistent and responsive typography system throughout your application.

App Interface

Workspace area

The Workspace area of the Design Tokens Generator displays all the Collections and Sets, along with their respective tokens. It also provides common controls and settings for each Set.

Let’s go through the Set interface:

Design Tokens Generator - Tokens Set

The Set interface includes the following common controls:

  • Prefix editor: It allows you to modify the prefix for the Set. When you change the prefix, all related tokens that use the current tokens as aliases will be updated in real time.
  • Toggle control: This control allows you to include or exclude the current Set from the final output. By default, the Set is included in the output.

It’s important to note that the Preview area will always visualize all token values, regardless of whether the respective Set is toggled on or off.

In addition to these common controls, there is one particular setting that deserves special mention:

  • Format: This setting, located on the far right, allows you to change the unit format for color, spacing, or duration values. In most cases, it’s a matter of preference. However, for the Spacing, the format is directly related to the selected root-size and whether you will be using rem responsive capabilities or not.

All other settings in the Workspace area are accompanied by informational tooltips, which can be helpful for a quick understanding (TL;DR) of their purpose.

Preview area

The Preview area of the Design Tokens Generator allows you to visualize the majority of token values in real time. It serves as a test area and in a real-life project you wouldn’t have such a mix of everything on a single page.

This is of course done on purpose, to help you examine different standard and edge cases and make adjustments as needed. In some situations, you may already have a design prepared and simply need to input the values into the App. In other cases, it’s easier to start designing in the browser and make adjustments afterward.

It’s important to note that the Preview area cannot anticipate and visualize all possible scenarios for your design. The tokens have a specific way in which they are used, and applying them differently in another project will produce different results.

The Preview area is designed to be streamlined and includes only a few controls:

Design Tokens Generator - Preview Controls

In addition to the opening/expanding and closing buttons, there are a couple of auxiliary actions:

  • Theme toggle: This control allows you to preview the visualization of tokens in light or dark mode. It achieves this by inverting the Gamma Set. However, it’s important to note that this is a simple method used for quick demonstration purposes. In a real project, you would likely choose a more precise way of applying a secondary theme.
  • Roundness selector: This control provides three options to switch between: square, round, and “squircle” (a combination of square and round). This control affects elements with rounded corners, allowing you to quickly adjust the preview according to your design needs. However, please note that pill and fully round elements will always remain the same regardless of the roundness selector.

Export and Other controls

The Design Tokens Generator Header provides a minimalist tool belt that puts everything you need just a click (or two) away.

Design Tokens Generator - Header

In the central area of the Header, you’ll find a global prefix editor. This editor allows you to set a prefix that will be applied to all tokens generated by the App.

Global prefixes are commonly used in UI libraries and design systems to prevent variable clashes and accidental overrides. They also make it easier to distinguish between custom and inherited tokens in your codebase.

Other controls in the header include:

  • Reset button: This button allows you to revert the App and all tokens back to their initial state. It’s designed with a safeguard to prevent accidental data loss, so you can experiment with confidence.
  • Copy button: This control allows to copy all tokens in the CSS variables format. You can then paste them directly into your code or design files.
  • Export button: Hitting this button will open a dropdown menu with several export options. Each option allows you to save the tokens in a specific file format, making it easy to integrate them into your project.

It’s important to note that the App automatically saves all your changes. However, the storage is local to your browser and may be reset if you clear your browser data. The app strives to preserve your data, but depending on the complexity of updates and data changes, there may be cases where everything is reset. Therefore, it’s recommended to save your work externally to ensure its safety.

Wrapping Up

More information

We highly encourage you to visit the About section of the Design Tokens Generator. This section provides additional information about the App and its development. It is particularly valuable if you are interested in collaboration or have any feedback to share. We appreciate your support and involvement!

Further resources to explore