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) (opens in a new tab).

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;
  }
}

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 (--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: -apple-system, BlinkMacSystemFont, San Francisco, Segoe UI,
    Roboto, Helvetica Neue, sans-serif;
  --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);
}

Using tokens with csx

The Csx object represents CSS styles within a typescript object, where the keys represent the css property in camelCase, and the entry - the css-value. One possible value is tokens. Shoreline uses the $ symbol (dollar sign) to trigger a token transformation. A token pattern is defined by:

${token-type}-{token-name}

It is converted to:

var(--sl-{token-type}-{token-name})

Contrived example:

$bg-action-primary-hover

Longer example:

const style = csx({
  bg: '$bg-primary',
  fg: '$fg-primary',
  radii: '$radii-base',
})

Check Transforms and Namespaces to see the available conversions.

References

Introduction Cascade Layers