Skip to content

Design tokens

Design tokens are an essential part of any design system, ensuring a consistent and cohesive user experience across your website. Simply put, design tokens are values that represent all the different aspects of your design, such as color, spacing, typography, object styles, animations, and more. They are stored as data with human-readable names and are used in place of hard-coded values to ensure flexibility, maintainability, and unity across your website.

Different types of design tokens

link Different types of design tokens

Design tokens come in different types, from the most generic to the most specific.

Global design tokens

link Global design tokens

The first type is the global design tokens, which are the primitive values in the design system represented by context-agnostic names. OxyProps color palettes, animations, typography, and sizes values are all recorded as global design tokens. These tokens are very useful to store complex data and make it available in an easy way.

In this example, the hsl() function with the parameters defining the base indigo color is stored in a human readable css custom property as a global design token.

Global design token
html {
--o-indigo-500: hsl(239deg, 84%, 67%);

Design tokens are very handy to store complex data and make it available in an easy way:

The --o-shadow-6 global design token
html {
--o-shadow-6: 0 -1px 2px 0 hsl(var(--o-shadow-color) / calc(var(--o-shadow-strength) + 2%)), 0 3px 2px -2px hsl(var(--o-shadow-color) / calc(var(--o-shadow-strength) + 3%)),
0 7px 5px -2px hsl(var(--o-shadow-color) / calc(var(--o-shadow-strength) + 3%)), 0 12px 10px -2px hsl(var(--o-shadow-color) / calc(var(--o-shadow-strength) + 4%)),
0 22px 18px -2px hsl(var(--o-shadow-color) / calc(var(--o-shadow-strength) + 5%)), 0 41px 33px -2px hsl(var(--o-shadow-color) / calc(var(--o-shadow-strength) + 6%)),
0 100px 80px -2px hsl(var(--o-shadow-color) / calc(var(--o-shadow-strength) + 7%));

Alias design tokens

link Alias design tokens

The second type is the alias design tokens, which relate to a specific context. These tokens are created to communicate the intended purpose of a token and are effective when a value with a single intent will appear in multiple places. In the OxyProps color system, logical colors are good examples of alias design tokens. The developer can use the alias design token to set the background color, and the prop value, the actual color, will adjust automatically based on the user preference for light or dark mode.

In this example, --o-surface-1 intent is to define the background color of an element with the lowest elevation. The page background for example.

Alias design token
html {
--o-surface-1: var(--o-slate-015);
@media (prefers-color-scheme: dark) {
html {
--o-surface-1: var(--o-slate-900);

The developer can use the prop --o-surface-1 for setting the background color. The prop value, the actual color, will adjust automatically based on the user preference for light or dark mode.

Component-specific design tokens

link Component-specific design tokens

The third type is the component-specific design tokens, which are an exhaustive representation of every value associated with a component. They often inherit from alias tokens but are named in a way that allows developers to be as specific as possible in applying design tokens in a component. In the example, the --o-btn-border-color is a component-specific design token, set to the --o-links alias design token, which can be set to a global token like --o-lime-3 depending on the context.

Component-specific design token
html {
--o-btn-border-color: var(--o-links);

In conclusion, design tokens are a vital part of any design system, and understanding them is crucial to building a cohesive user experience. By using design tokens, you can ensure consistency, maintainability, and flexibility across your website.