• Usage
  • Dark mode
• Creating or updating design tokens
  • Format
  • Transformations
  • Names
  • Groups
  • Values
  • Aliases
  • Type
  • Modes
    • Default design tokens
    • Dark mode design tokens

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:

JavaScript

import { BLUE_500 } from '@gitlab/ui/dist/tokens/js/tokens';

const color = BLUE_500; // #1f75cb

CSS

@import '@gitlab/ui/dist/tokens/css/tokens';

.elem {
  color: var(--blue-500); /* #1f75cb */
}

SCSS

@import '@gitlab/ui/dist/tokens/scss/tokens';

.elem {
  color: $blue-500; /* #1f75cb */
}

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:

JavaScript

import { BLUE_500 } from '@gitlab/ui/dist/tokens/js/tokens.dark';

const color = BLUE_500; // #428fdc

CSS

@import '@gitlab/ui/dist/tokens/css/tokens.dark';

.elem {
  color: var(--blue-500); /* #428fdc */
}

SCSS

@import '@gitlab/ui/dist/tokens/scss/tokens.dark';

.elem {
  color: $blue-500; /* #428fdc */
}

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:

// color.tokens.json
{
  "token name": {
    "$value": "#000",
    "$type": "color"
  }
}

Transformations

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

A parser makes design tokens format properties compatible with style-dictionary design token attributes.

Names

A design token name is a unique and case-sensitive identifier of a value. A name can be used across different modes to generate style overrides.

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.

{
  "group name": {
    "token name": {
      "$value": "#000"
    }
  }
}

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

JavaScript

const GROUP_NAME_TOKEN_NAME = "#000";

CSS

:root {
  --group-name-token-name: #000;
}

SCSS

$group-name-token-name: #000;

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

A design token’s value can be a reference to another token, for example the alias token text-color has the value {color.default}:

{
  "text-color": {
    "$value": "{color.default}"
  }
}

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

CSS

:root {
  --text-color: var(--color-default);
}

SCSS

$text-color: $color-default;

Type

An optional $type property is used for value transformations and grouping tokens together, for example:

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

Results in the output tokens.grouped.json that can be used for documentation or tooling configuration:

{
  "color": {
    "token name": "#000"
  }
}

Modes

Modes are processed on top of default tokens and can be combined with other modes, and inherited separately from stylesheets. Modes are denoted with a .{mode}.token.json filename which is used to filter tokens by file, for example: for dark mode token files, end with .dark.token.json.

Default design tokens

Input

color.tokens.json

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

Output

tokens.grouped.json

{
  "color": {
    "text-color": "#000"
  }
}

tokens.js

export const TEXT_COLOR = "#000";

tokens.scss

$text-color: #000;

tokens.css

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

Dark mode design tokens

Design tokens for different modes are generated separately from default tokens. Using the same name for tokens ensures they will override default values when imported, for example:

Input

color.dark.tokens.json

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

Output

tokens.dark.grouped.json

{
  "color": {
    "text-color": "#fff"
  }
}

tokens.dark.js

export const TEXT_COLOR = "#fff";

tokens.dark.scss

$text-color: #fff;

tokens.dark.css

:root {
  --text: #fff;
}