Design Tokens

Design tokens abstract and organize design-related values, such as colors, typography, spacing, and other styles, exporting them as reusable variables. They serve as the single source of truth for design properties in a design system. By defining design tokens, designers and developers can ensure consistency across various platforms, applications, and devices.

They are a common language for designers and developers, facilitating seamless collaboration and maintaining a cohesive visual identity throughout a project or organization. By making changes to design tokens, designers can update the entire design system, ensuring a consistent look and feel across all products and interfaces.

Understanding tokens

Vendor and Prefix

The vendor is a company or organization that ships a design token specification, in the case of Shoreline, VTEX. The prefix is assigned to avoid conflicts with other tools of libraries that the application can be using. In Shoreline, we adopt the prefix sl. This means that every className or design token exported by Shoreline starts with sl.

Token type

A classification is applied to the value of a token. For example:

color
radii
font-size

Token name

A label assigned to a design decision. For example:

space-1
color-blue-100
border-container

Token value

A context-specific value is assigned to a design token name.

1rem
rgb(142, 142, 142)
1px solid black

Variable

Describes the most common way (but not the only way) a design token is formatted and used in code. It can be a CSS custom property, javascript variable, etc. In Shoreline, we rely on CSS custom properties (aka CSS variables).

CSS variables are declared using the pattern:

--{vendor}-{token-type}-{token-name}

And are reused (called) using the pattern:

var({css-variable})

So, an example of declaration and usage is:

We cover @layer in detail on the Cascade Layers page.

@layer sl-tokens {
  :root {
    --sl-color-blue-100: #b0d7ff;
  }
}

.my-component {
  background-color: 'var(--sl-color-blue-100)',
}

<div
  style={{
    backgroundColor: 'var(--sl-color-blue-100)',
  }}
/>

Token alias

Aliases are token values that reference another token. In this example, we alias a color shade of the palette as a semantic background:

:root {
  --sl-color-blue-100: #b0d7ff;
  --sl-bg-primary: var(--sl-color-blue-100);
}

Composite tokens

Composite design tokens contain values that represent more than one design decision. One example is a border, composed of color, width, and style:

:root {
  --sl-color-blue-100: #b0d7ff;
  --sl-border-size-1: 0.0625rem;
  --sl-border-1: var(--sl-border-size-1) solid var(--sl-color-blue-100);
}

Another classic example of composite tokens is typography. In the following example, the token $text-body is composed of font size, weight, family, and line-height:

:root {
  --sl-font-family: system-ui;
  --sl-font-size: 1rem;
  --sl-line-height: 1.5;
  --sl-font-weight: 400;
 
  --sl-text-body: var(--sl-font-weight) var(--sl-font-size) / var(
      --sl-line-height
    )
    var(--sl-font-family);
}

References

Styling API Cascade Layers