Skip to content

Design tokens > Token integration

How we define/name design tokens will ultimately impact how we integrate with existing SCSS variable usage in gitlab.com/gitlab-ui/design.gitlab.com etc.

The design token POC implements token aliases as an approach to be compatible with existing SCSS variables, for example:

Tokens:

{
  "gl": {
    "color": {
      "blue": {
        "500": { "value": "#1f75cb", "attributes": { "category": "color" } }
      },
      "link": {
        "_": { "value": "{gl.color.blue.500}" }
      }
    }
  },
  "anchor-color": { "value": "{gl.color.link._}" },
  "blue": {
    "500": { "value": "{gl.color.blue.500}" }
  }
}

Output

:root {
  --gl-color-blue-500: #1f75cb;
  --blue-500: var(--gl-color-blue-500);
  --gl-color-link: var(--gl-color-blue-500);
  --anchor-color: var(--gl-color-link);
}
$gl-color-blue-500: #1f75cb;
$blue-500: $gl-color-blue-500;
$gl-color-link: $gl-color-blue-500;
$anchor-color: $gl-color-link;
  • The base token gl.color.blue.500 compiles to $gl-color-blue-500: #1f75cb
  • The alias token blue.500 references gl.color.blue.500 and compiles to $blue-500: $gl-color-blue-500
  • The design token gl.color.link compiles to $gl-color-link: $gl-color-blue-500
  • The alias token anchor-color references gl.color.link and compiles to $anchor-color: $gl-color-link

Where existing SCSS variable usage is shared across all projects (gitlab.com/gitlab-ui/design.gitlab.com etc.) these aliases are relatively straightforward as a temporary migration/compatibility method.

This becomes more complex when:

  • Variable names differ e.g. $gl-spacing-scale-2 (gitlab.com/gitlab-ui) and $gl-spacing-2 (design.gitlab.com)
  • Variable values differ
  • If we choose to update scales e.g. $gl-spacing-scale-2 becomes $gl-spacing-scale-200 to align with a millennial scale etc.

A strategy for defining and migrating token -> variable aliases would assist with simplifying integration of design tokens within projects.

Base color tokens (excluding data-viz and themes) could be the best first-slice approach as they have consistency of naming and values between all projects.

Outcome

Edited by Jeff Tucker