• Usage
  • Dark mode
• Creating or updating design tokens
  • Format
  • Automation
    • Transforms
    • Transform groups
    • Parser
  • Names
  • Groups
  • Values
  • Aliases
  • Type
• Modes

Design tokens

Design tokens provide a single source-of-truth for values (such as color, spacing, and duration), in different modes (such as default and dark), for different tools (such as Figma and code).

Usage

We manage design tokens in the gitlab-ui repository. This repository is published on npm, and is managed as a dependency with yarn. To upgrade to a new version run yarn upgrade @gitlab/ui.

Design tokens are provided in different modes (default/dark) and file formats for use in CSS (custom properties), JavaScript (ES6 Constants/JSON), and SCSS (variables), for example:

CSS

@import '@gitlab/ui/src/tokens/build/css/tokens';

h1 {
  color: var(--gl-text-color-heading); /* #1f1e24 */
}

SCSS

@import '@gitlab/ui/src/tokens/build/scss/tokens';

h1 {
  color: $gl-text-color-heading; /* #1f1e24 */
}

JavaScript

import { GL_TEXT_COLOR_HEADING } from '@gitlab/ui/src/tokens/build/js/tokens';

const color = GL_TEXT_COLOR_HEADING; // #1f1e24

Dark mode

Where color design tokens are updated for dark mode, their values are provided with the same name in files appended with .dark, for example:

CSS

@import '@gitlab/ui/src/tokens/build/css/tokens.dark';

h1 {
  color: var(--gl-text-color-heading); /* #fff */
}

SCSS

@import '@gitlab/ui/src/tokens/build/scss/tokens.dark';

h1 {
  color: $gl-text-color-heading; /* #fff */
}

JavaScript

import { GL_TEXT_COLOR_HEADING } from '@gitlab/ui/src/tokens/build/js/tokens.dark';

const color = GL_TEXT_COLOR_HEADING; // #fff

Creating or updating design tokens

Format

Our design tokens use the Design Tokens Format Module for defining design tokens that integrate with different tools and are converted to required file formats. It is a community group draft report, published by the Design Tokens Community Group.

The Design Tokens Format Module promotes a *.token.json extension standard for design token files, with a format that includes a name and $value and an explicit $type:

// text.color.tokens.json
{
  "heading": {
    "$value": "#1f1e24",
    "$type": "color"
  }
}

Automation

Our design tokens use style-dictionary to compile design tokens into consumable file formats (CSS/SCSS/JavaScript/JSON).

Transforms

Transforms modify design tokens before being compiled and are used to prefix compiled output, and use mode values when provided.

Transform groups

Transform groups apply transforms to platforms, for example, CSS and JavaScript have different transform groups for casing kebab-case for CSS and SCSS output, CONSTANT_CASE for JavaScript output.

Parser

A parser makes Design Tokens Format Module properties compatible with style-dictionary design token attributes.

Names

A design token name is a unique and case-sensitive identifier of a value.

Names have character restrictions including:

1. Names must not begin with $
2. Names must not contain { or }
3. Names must not contain .

Groups

Groups are arbitrary ways to cluster tokens together in a category. They should not be used to infer the type or purpose of design tokens. For that purpose, use the $type property.

{
  "color": {
    "heading": {
       "$value": "#1f1e24",
       "$type": "color"
    }
  }
}

Groups can also be nested for greater context setting:

{
  "text": {
     "color": {
       "heading": {
          "$value": "#1f1e24",
          "$type": "color"
       }
     }
  }
}

Group names prepend design token names in generated output, for example:

CSS

:root {
  --gl-text-color-heading: #1f1e24;
}

SCSS

$gl-text-color-heading: #1f1e24;

JavaScript

const GL_TEXT_COLOR_HEADING = "#1f1e24";

Values

Name and $value are the minimum required properties of a design token, $value is a reserved word.

{
  "token name": {
    "$value": "16"
  }
}

A design token value can be a string or alias, for example:

Aliases

Aliases allow a design token value to reference to another token, for example the alias token custom-token has the value {text.color.heading}:

{
  "custom-token": {
    "$value": "{text.color.heading}"
  }
}

This allows generated CSS and SCSS that are output by using Output References to use references as variables:

CSS

:root {
  --gl-custom-token: var(--gl-text-color-heading);
}

SCSS

$gl-custom-token: $gl-text-color-heading;

Type

An optional $type property is used for tools to reliably interpret their value.

{
  "token name": {
    "$value": "#000",
    "$type": "color"
  }
}

Modes

Modes allow design tokens to update value for different use cases, for example, light and dark mode colors.

Modes are defined as an object in the $value property:

{
  "text-color": {
    "$value": {
      "default": "#000",
      "dark": "#fff",
    },
    "$type": "color"
  }
}

When defined each mode value is compiled into separate output:

CSS

tokens.css

:root {
  --text-color: #000;
}

tokens.dark.css

:root {
  --text-color: #fff;
}

CSS

tokens.scss

$text-color: #000;

tokens.dark.scss

$text-color: #fff;

JavaScript

tokens.js

export const TEXT_COLOR = "#000";

tokens.dark.js

export const TEXT_COLOR = "#fff";