Design tokens, or “tokens” are basic design selections represented
as information. They’re the foundational constructing blocks of design programs.
Because the launch of the second editor’s
draft of the
design token specification in 2022 and the name for device
makers
to begin implementing and offering suggestions, the panorama of design token
instruments has developed quickly. Instruments like code mills, documentation
programs, and UI design software program are actually higher geared up to assist design
tokens, underscoring their rising significance in trendy UI structure.
On this article, I will clarify what design tokens are, when they’re helpful and learn how to apply
them successfully. We’ll give attention to key architectural selections which can be typically troublesome to alter later, together with:
- Find out how to manage design tokens in layers to steadiness scalability, maintainability and developer expertise.
- Whether or not all tokens ought to be made out there to product groups or only a subset.
- Find out how to automate the distribution strategy of tokens throughout groups.
Position of design tokens
Round 2017, I used to be concerned in a big venture that used the Micro
Frontend
Structure to
scale improvement groups. On this setup, totally different groups have been accountable
for various elements of the person interface, which may very well be even on the identical
web page. Every group might deploy its micro-frontend independently.
There have been varied circumstances the place elements could be displayed on prime of
one another (reminiscent of dialogs or toasts showing on prime of content material areas),
which weren’t a part of the identical micro frontend. Groups used the CSS
property z-index to regulate the stacking order, typically counting on magic
numbers—arbitrary values that weren’t documented or standardized. This strategy
didn’t scale because the venture grew. It led to points that took effort to
repair, as cross-team collaboration was wanted.
The difficulty was finally addressed with design tokens and I feel makes
instance to introduce the idea. The respective token file would possibly
have appeared much like this:
{
"z-index": {
"$sort": "quantity",
"default": {
"$worth": 1
},
"sticky": {
"$worth": 100
},
"navigation": {
"$worth": 200
},
"spinner": {
"$worth": 300
},
"toast": {
"$worth": 400
},
"modal": {
"$worth": 500
}
}
}
The design tokens above symbolize the set of z-index values that may
be used within the utility and the title provides builders a good suggestion of
the place to make use of them. A token file like this may be built-in into the
designers’ workflow and likewise be used to generate code, in a format that
every group requires. For instance, on this case, the token file might need
been used to generate CSS or SCSS variables:
css
:root {
--z-index-default: 1;
--z-index-sticky: 100;
--z-index-navigation: 200;
--z-index-spinner: 300;
--z-index-toast: 400;
--z-index-modal: 500;
}
scss
$z-index-default: 1; $z-index-sticky: 100; $z-index-navigation: 200; $z-index-spinner: 300; $z-index-toast: 400; $z-index-modal: 500;
What are design tokens?
Salesforce initially launched design tokens to streamline design
updates to a number of
platforms.
The Design Tokens Group Group describes design tokens as “a
methodology for expressing design selections in a platform-agnostic method so
that they are often shared throughout totally different disciplines, instruments, and
applied sciences
Let’s break this down:
- Cross-Disciplinary Collaboration: Design tokens act as a typical language
that aligns designers, builders, product managers, and different disciplines. By
providing a single supply of reality for design selections, they be certain that
everybody concerned within the product life cycle is on the identical web page, resulting in extra
environment friendly workflows. - Software integration: Design tokens could be built-in into varied design
and improvement instruments, together with UI design software program, token editors, translation
instruments (code mills), and documentation programs. This permits design updates
to be rapidly mirrored within the code base and are synchronized throughout groups. - Expertise adaptability: Design tokens could be translated into totally different
applied sciences like CSS, SASS, and JavaScript for the online, and even used on native
platforms like Android and iOS. This flexibility permits design consistency
throughout a wide range of platforms and gadgets.
Establishing a single supply of reality
A key advantage of design tokens is their skill to function a single
supply of reality for each design and engineering groups. This ensures that
a number of services or products keep visible and purposeful
consistency.
A translation
device takes one or
extra design token recordsdata as enter and generates platform-specific code as
output. Some translation instruments also can produce documentation for the
design tokens within the type of HTML. On the time of writing, in style
translation instruments embrace Type
Dictionary,
Theo, Diez
or Specify App.
Automated design token distribution
On this part, we’ll discover learn how to automate the distribution of
design tokens to product groups.
Let’s assume our aim is to offer groups with up to date, tech-specific
design tokens instantly after a designer makes a change. To realize
this, we are able to automate the interpretation and distribution course of utilizing a
deployment pipeline for design tokens. In addition to platform-specific code
artifacts (like CSS for the online, XML for Android and so on.), the pipeline would possibly
additionally deploy the documentation for the design tokens.
One essential requirement is conserving design tokens beneath model management.
Fortunately, plugins for in style design instruments like Figma already combine
with Git suppliers like GitHub. It is thought-about greatest apply to make use of the
Git repository as the only supply of reality for design tokens—not the
design device itself. Nevertheless, this requires the plugin to assist syncing
each methods between the repository and the design device, which not all
plugins do. As of now, Tokens Studio is a plugin that gives this
bidirectional syncing. For detailed steering on integrating Tokens Studio
with totally different Git suppliers, please confer with their
documentation.
The device lets you configure a goal department and helps a
trunk-based in addition to a pull-request-based workflow.
As soon as the tokens are beneath model management, we are able to arrange a deployment
pipeline to construct and deploy the artifacts wanted by the product groups,
which embrace platform-specific supply code and documentation. The supply
code is usually packaged as a library and distributed by way of an artifact
registry. This strategy provides product groups management over the improve
cycle. They’ll undertake up to date kinds by merely updating their
dependencies. These updates may additionally be utilized not directly by means of updates of part
libraries that use the token-based kinds.
Determine 2: Automated design token distribution
This general setup has allowed groups at Thoughtworks to roll out
smaller design modifications throughout a number of front-ends and groups in a single
day.
Totally automated pipeline
Essentially the most easy method to design the pipeline could be a
absolutely automated trunk-based workflow. On this setup, all modifications
pushed to the principle department might be instantly deployed so long as they
move the automated high quality gates.
Such a pipeline would possibly encompass the next jobs:
- Test: Validate the design token recordsdata utilizing a design token validator
or a JSON validator. - Construct: Use a translation device like Type
Dictionary to transform design token recordsdata into
platform-specific codecs. This job may also construct the docs utilizing the
translation device or by integrating a devoted documentation device. - Take a look at: This job is very depending on the testing technique. Though
some assessments could be finished utilizing the design token file immediately (like checking the
coloration distinction), a typical strategy is to check the generated code utilizing a
documentation device reminiscent of Storybook. Storybook has wonderful check
assist for visible regression
assessments, accessibility assessments, interplay assessments, and different check sorts. - Publish: Publish up to date tokens to a bundle supervisor (for instance,
npm). The discharge course of and versioning could be absolutely automated with a bundle
publishing device that’s primarily based on Standard
Commits like
semantic-release.
semantic-release additionally permits the deployment of packages to a number of platforms.
The publish job may also deploy documentation for the design tokens. - Notify: Inform groups of the brand new token model by way of e mail or chat, so
that they will replace their dependencies.
Determine 3: Totally automated deployment pipeline
Pipeline together with guide approval
Typically absolutely automated high quality gates will not be ample. If a
guide overview is required earlier than publishing, a typical strategy is to
deploy an up to date model of the documentation with the most recent design
token to a preview atmosphere (a short lived atmosphere).
If a device like Storybook is used, this preview would possibly include not
solely the design tokens but additionally present them built-in with the
elements used within the utility.
An approval course of could be carried out by way of a pull-request workflow.
Or, it may be a guide approval / deployment step within the pipeline.
Determine 4: Deployment pipeline with guide approval
Organizing tokens in layers
As mentioned earlier, design tokens symbolize design selections as information.
Nevertheless, not all selections function on the similar stage of element. As a substitute,
ideally, basic design selections information extra particular ones. Organizing
tokens (or design selections) into layers permits designers to make
selections on the proper stage of abstraction, supporting consistency and
scalability.
As an illustration, making particular person coloration decisions for each new part isn’t sensible.
As a substitute, it’s extra environment friendly to outline a foundational coloration palette after which
determine how and the place these colours are utilized. This strategy reduces the
variety of selections whereas sustaining a constant appear and feel.
There are three key kinds of design selections for which design tokens
are used. They construct on prime of each other:
- What design choices can be found to make use of?
- How are these kinds utilized throughout the person interface?
- The place precisely are these kinds utilized (by which elements)?
There are numerous names for these three kinds of tokens (as normal,
naming is the arduous half). On this article, we’ll use the phrases proposed
by Samantha
Gordashko:
choice tokens, choice tokens and part tokens.
Let’s use our coloration instance as an instance how design tokens can
reply the three questions above.
Choice tokens: defining what design choices are offered
Choice tokens (additionally referred to as primitive tokens, base tokens, core
tokens, basis tokens or reference tokens) outline what
kinds can be utilized within the utility. They outline issues like coloration
palettes, spacing/sizing scales or font households. Not all of them are
essentially used within the utility, however they current affordable
choices.
Utilizing our instance, let’s assume we’ve got a coloration palette with 9 shades for every coloration,
starting from very mild to extremely saturated. Under, we outline the blue tones and gray tones as option-tokens:
{
"coloration": {
"$sort": "coloration",
"choices": {
"blue-100": {"$worth": "#e0f2ff"},
"blue-200": {"$worth": "#cae8ff"},
"blue-300": {"$worth": "#b5deff"},
"blue-400": {"$worth": "#96cefd"},
"blue-500": {"$worth": "#78bbfa"},
"blue-600": {"$worth": "#59a7f6"},
"blue-700": {"$worth": "#3892f3"},
"blue-800": {"$worth": "#147af3"},
"blue-900": {"$worth": "#0265dc"},
"grey-100": {"$worth": "#f8f8f8"},
"grey-200": {"$worth": "#e6e6e6"},
"grey-300": {"$worth": "#d5d5d5"},
"grey-400": {"$worth": "#b1b1b1"},
"grey-500": {"$worth": "#909090"},
"grey-600": {"$worth": "#6d6d6d"},
"grey-700": {"$worth": "#464646"},
"grey-800": {"$worth": "#222222"},
"grey-900": {"$worth": "#000000"},
"white": {"$worth": "#ffffff"}
}
}
}
Though it’s extremely helpful to have affordable choices, choice tokens fall brief
of being ample for guiding builders on how and the place to use them.
Resolution tokens: defining how kinds are utilized
Resolution tokens (additionally referred to as semantic tokens or system tokens)
specify how these fashion choices ought to be utilized contextually throughout
the UI.
Within the context of our coloration instance, they may embrace selections like the next:
- grey-100 is used as a floor coloration.
- grey-200 is used for the background of disabled components.
- grey-400 is used for the textual content of disabled components.
- grey-900 is used as a default coloration for textual content.
- blue-900 is used as an accent coloration.
- white is used for textual content on accent coloration backgrounds.
The corresponding choice token file would appear to be this:
{
"coloration": {
"$sort": "coloration",
"selections": {
"floor": {
"$worth": "{coloration.choices.grey-100}",
"description": "Used as a floor coloration."
},
"background-disabled": {
"$worth": "{coloration.choices.grey-200}",
"description":"Used for the background of disabled components."
},
"text-disabled": {
"$worth": "{coloration.choices.grey-400}",
"description": "Used for the textual content of disabled components."
},
"textual content": {
"$worth": "{coloration.choices.grey-900}",
"description": "Used as default textual content coloration."
},
"accent": {
"$worth": "{coloration.choices.blue-900}",
"description": "Used as an accent coloration."
},
"text-on-accent": {
"$worth": "{coloration.choices.white}",
"description": "Used for textual content on accent coloration backgrounds."
}
}
}
}
As a developer, I might largely have an interest within the selections, not the
choices. For instance, coloration tokens sometimes include an extended listing of choices (a
coloration palette), whereas only a few of these choices are literally utilized in
the applying. The tokens which can be really related when deciding which
kinds to use, could be often the choice tokens.
Resolution tokens use
references to the
choice tokens. I consider organizing tokens this fashion as a layered
structure. In different articles, I’ve typically seen the time period tier being
used, however I feel layer is the higher phrase, as there is no such thing as a bodily
separation implied. The diagram beneath visualizes the 2 layers we talked
about to date:
Determine 5: 2-layer sample
Part tokens: defining the place kinds are utilized
Part tokens (or component-specific tokens) map the choice
tokens to particular elements of the UI. They present the place kinds are
utilized.
The time period part within the context of design tokens doesn’t all the time
map to the technical time period part. For instance, a button could be
carried out as a UI part in some functions, whereas different
functions simply use the button HTML ingredient as a substitute. Part
tokens may very well be utilized in each circumstances.
Part tokens could be organised in a group referencing a number of choice tokens. In our instance, this references
would possibly embrace text- and background-colors for various variants of the button (main, secondary) in addition to disabled buttons.
They could additionally embrace references to tokens of different sorts (spacing/sizing, borders and so on.) which I will omit within the
following instance:
{
"button": {
"main": {
"background": {
"$worth": "{coloration.selections.accent}"
},
"textual content": {
"$worth": "{coloration.selections.text-on-accent}"
}
},
"secondary": {
"background": {
"$worth": "{coloration.selections.floor}"
},
"textual content": {
"$worth": "{coloration.selections.textual content}"
}
},
"background-disabled": {
"$worth": "{coloration.selections.background-disabled}"
},
"text-disabled": {
"$worth": "{coloration.selections.text-disabled}"
}
}
}
To a point, part tokens are merely the results of making use of
selections to particular elements. Nevertheless, as this
instance reveals, this course of isn’t all the time easy—particularly for
builders with out design expertise. Whereas choice tokens can provide a
basic sense of which kinds to make use of in a given context, part tokens
present extra readability.
Determine 6: 3-layer sample
Word: there could also be “snowflake” conditions the place layers are skipped.
For instance, it won’t be attainable to outline a basic choice for
each single part token, or these selections won’t have been made
but (for instance at the start of a venture).
Token scope
I already talked about that whereas choice tokens are very useful to
designers, they won’t be related for utility builders utilizing the
platform-specific code artifacts. Utility builders will sometimes be
extra within the choice/part tokens.
Though token scope is just not but included within the design token
spec, some design
programs already separate tokens into personal (additionally referred to as inner) and
public (additionally referred to as international) tokens. For instance, the Salesforce Lightning
Design System launched a flag for every
token. There are
varied the reason why this may be a good suggestion:
- it guides builders on which tokens to make use of
- fewer choices present a greater developer expertise
- it reduces the file measurement as not all tokens should be included
- personal/inner tokens could be modified or eliminated with out breaking
modifications
A draw back of creating choice tokens personal is that builders would rely
on designers to all the time make these kinds out there as choice or part
tokens. This might turn into a problem in case of restricted availability of the
designers or if not all selections can be found, for instance at the beginning of
a venture.
Sadly, there is no such thing as a standardized answer but for implementing
scope for design tokens. So the strategy is dependent upon the tool-chain of the
venture and can probably want some customized code.
File-based scope
Utilizing Type Dictionary, we are able to use a
filter to
expose solely public tokens. Essentially the most easy strategy could be to
filter on the file ending. If we use totally different file endings for part,
choice and choice tokens, we are able to use a filter on the file path, for
instance, to make the choice tokens layer personal.
Type Dictionary config
const styleDictionary = new StyleDictionary({
"supply": ["color.options.json", "color.decisions.json"],
"platforms": {
"css": {
"transformGroup": "css",
"recordsdata": [
{
"destination": "variables.css",
"filter": token => !token.filePath.endsWith('options.json'),
"format": "css/variables"
}
]
}
}
});
The ensuing CSS variables would include
solely these choice tokens, and never the choice tokens.
Generated CSS variables
:root {
--color-decisions-surface: #f8f8f8;
--color-decisions-background-disabled: #e6e6e6;
--color-decisions-text-disabled: #b1b1b1;
--color-decisions-text: #000000;
--color-decisions-accent: #0265dc;
--color-decisions-text-on-accent: #ffffff;
}
A extra versatile strategy
If extra flexibility is required, it could be preferable so as to add a scope
flag to every token and to filter primarily based on this flag:
Type Dictionary config
const styleDictionary = new StyleDictionary({
"supply": ["color.options.json", "color.decisions.json"],
"platforms": {
"css": {
"transformGroup": "css",
"recordsdata": [
{
"destination": "variables.css",
"filter": {
"public": true
},
"format": "css/variables"
}
]
}
}
});
If we then add the flag to the choice tokens, the ensuing CSS would
be the identical as above:
Tokens with scope flag
{
"coloration": {
"$sort": "coloration",
"selections": {
"floor": {
"$worth": "{coloration.choices.grey-100}",
"description": "Used as a floor coloration.",
"public": true
},
"background-disabled": {
"$worth": "{coloration.choices.grey-200}",
"description":"Used for the background of disabled components.",
"public": true
},
"text-disabled": {
"$worth": "{coloration.choices.grey-400}",
"description": "Used for the textual content of disabled components.",
"public": true
},
"textual content": {
"$worth": "{coloration.choices.grey-900}",
"description": "Used as default textual content coloration.",
"public": true
},
"accent": {
"$worth": "{coloration.choices.blue-900}",
"description": "Used as an accent coloration.",
"public": true
},
"text-on-accent": {
"$worth": "{coloration.choices.white}",
"description": "Used for textual content on accent coloration backgrounds.",
"public": true
}
}
}
}
Generated CSS variables
:root {
--color-decisions-surface: #f8f8f8;
--color-decisions-background-disabled: #e6e6e6;
--color-decisions-text-disabled: #b1b1b1;
--color-decisions-text: #000000;
--color-decisions-accent: #0265dc;
--color-decisions-text-on-accent: #ffffff;
}
Such flags can now even be set by means of the Figma
UI
(if utilizing Figma variables as a supply of reality for design tokens). It’s
out there as
hiddenFromPublishing
flag by way of the Plugins API.
Ought to I exploit design tokens?
Design tokens provide vital advantages for contemporary UI structure,
however they will not be the best match for each venture.
Advantages embrace:
- Improved lead time for design modifications
- Constant design language and UI structure throughout platforms and
applied sciences - Design tokens being comparatively light-weight from an implementation level of
view
Drawbacks embrace:
- Preliminary effort for automation
- Designers might need to (to a point) work together with Git
- Standardization remains to be in progress
Take into account the next when deciding whether or not to undertake design
tokens:
When to make use of design tokens
- Multi-Platform or Multi-Utility Environments: When working throughout
a number of platforms (net, iOS, Android…) or sustaining a number of functions or
frontends, design tokens guarantee a constant design language throughout all of
them. - Frequent Design Adjustments: For environments with common design
updates, design tokens present a structured method to handle and propagate modifications
effectively. - Giant Groups: For groups with many designers and builders, design
tokens facilitate collaboration. - Automated Workflows: Should you’re conversant in CI/CD pipelines, the
effort so as to add a design token pipeline is comparatively low. There are additionally
business choices.
When design tokens won’t be mandatory
- Small initiatives: For smaller initiatives with restricted scope and minimal
design complexity, the overhead of managing design tokens won’t be well worth the
effort. - No challenge with design modifications: If the velocity of design modifications,
consistency and collaboration between design and engineering will not be a problem,
then you may additionally not want design tokens.