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
referencesgl.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
referencesgl.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
- Document our approach for connecting token names to SCSS/CSS variables in our architecture design doc (internal)