Taxonomy
Design tokens' variable names follow a taxonomy with distinct classification levels and sublevels, forming a prescriptive vocabulary of descriptive terms.
|
Ecosystem |
|---|
|
Domain |
|
Object |
|
|
|---|---|---|
|
Pattern Component Element |
|
|
|
Category |
|
|
|---|---|---|
|
Type Concept Property |
|
|
|
Modifier |
|
|
|---|---|---|
|
Variant State Scale |
|
|
The goal of design tokens naming is modularity and legibility.
|
Type |
Concept |
Variant |
|---|---|---|
|
color |
accent |
primary |
Meanings and the relationship between meanings can be complex, therefore taxonomy levels are chained to provide clarity. (see example above).
Not all levels are required when naming a token. A name just needs enough levels to imply the token's use and define its meaning. Different combinations of different levels helps us arrive at meaningful names.
Names shouldn't be redundant and should be kept simple. They should only include enough levels to describe and communicate the token's intent and purpose.
Ecosystem
The ecosystem level helps describe the context that a token is scoped to.
Domain
A token is only prefixed with a domain when there is a need to specify its context.
For example, if a token is specific to a certain feature, you can use the domain level to specify the name of the feature that it belongs to. Don't forget to keep domain-specific tokens within the feature's CSS so that they can only be reused within its domain.
|
Domain |
Component |
Property |
|---|---|---|
|
shopping |
header |
font-size |
Object
The object level helps define the object (or objects) that the token applies to.
Pattern
A design pattern that is composed of, or represents, multiple related components.
|
Pattern |
Type |
Property |
|---|---|---|
|
input |
text |
min-height |
Component
The component name.
|
Component |
Property |
|---|---|
|
toggle |
background-color |
Element
Any element that may be nested within a component (e.g. an icon).
|
Component |
Element |
Property |
|---|---|---|
|
message-bar |
icon |
color |
Category
The category level helps define the visual style that apply to the token.
Type
The type of style category a design token belongs to.
|
Type |
Variant |
Scale |
|---|---|---|
|
color |
blue |
50 |
Concept
A concept further describes user interface styles. They are either industry-wide patterns, or they are terms determined by our team based on specific user interface style needs. For example, "accent" is a common design industry term used for delineating a brand's or product's accent color(s) that we happen to use for our color tokens.
|
Type |
Concept |
Variant |
|---|---|---|
|
color |
accent |
primary |
To further illustrate this taxonomy level, here are detailed explanations and definitions of existing concepts:
Accent
We use the "accent" color concept for referring to our brand and the operating system (platform) accent colors. The brand and platform accent colors are used as the primary color for accentuating and characterizing several Firefox UI elements' (e.g. buttons, focus outlines, links, icons, and more).
Interactive
We use the "interactive" concept to describe design tokens that pertain to interactive elements. For example, --border-color-interactive is used on moz-toggle since interactive elements such as toggles, radios, and checkboxes share the same border color pattern that is different from our default border color.
/* moz-toggle.css */
--toggle-border-color: var(--border-color-interactive);
Item
We use the "item" concept as a modifier on top of the "size" type tokens group to refer to different interface items, or elements, that often rely on the same standard width and height dimensions.
The word item should imply that this is a small sizing scale dedicated for dimensions that get applied to smaller UI pieces such as icons, logos, and avatars, as opposed to large compositions or areas such as the width set for onboarding illustrations, or the width of a sidebar or main column within a page's template.
/* tokens-shared.css */
--size-item-small: 16px;
--size-item-large: 32px;
Property
A property (e.g. size, width, color, fill) further describes a design tokens' style and tend to correspond to the name of a CSS property.
Although this is not to be confused with the categorical type of token mentioned above, although they often use similar terms.
Note that sometimes properties are double-worded, and that's totally fine (e.g. min-width, background-color, border-radius)
|
Property |
Variant |
|---|---|
|
border-radius |
circle |
Modifier
The modifier level helps further classify a design token's characteristic with further specification.
Variant
A variant specifies a token from a group of tokens related by a common meaning, but that have varying purpose.
|
Component |
Property |
Variant |
|---|---|---|
|
icon |
color |
success |
|
icon |
color |
critical |
State
A state defines possible interactive states of a design token. (e.g. hover, active, focus, disabled)
|
Component |
Property |
State |
|---|---|---|
|
button |
background-color |
hover |
Scale
A scale defines a collection of tokens that relate to one another's but vary by their type, such as a collection of size units, or any other relationship that requires differentiating tokens by a determined scale.
|
Property |
Scale |
|---|---|
|
font-size |
small |
Today we have scales based off a sequence of numbers or t-shirt sizing. We use a sequence numbers for collections that have attributes that change as the number goes up, such as colors getting darker.
Number-based scale grows by 10:
- 10
- 20
- 30
- 40
- and so on...
For collections that do have sizing relationships, we use t-shirt sizing names:
- xsmall
- small
- medium
- large
- xlarge
- xxlarge
- and so on...
These are some of our font sizes as an example:
/* tokens-brand.css */
--font-size-root: 15px;
--font-size-small: 0.867rem; /* 13px */
--font-size-large: 1.133rem; /* 17px */
--font-size-xlarge: 1.467rem; /* 22px */
You will see that the font size scale is missing what would be a logical "medium" size in between "small" and "large", and that it has a --font-size-root within it too; that's because we use more specific words within scales that contain tokens that serve a specific purpose within that scale.
The --font-size-root token was created for specific use under the document's :root in order to set the default font size for our relative typography scale. We label our default font size token as root in order to be specific and intentional.
It's okay to include intentional terms within scales that better represent the meaning of a value and when to use it. For example, our border radius collection, which uses t-shirt sizing, also mixes the 'circle' option within its scale in order to describe a border radius that will create a circular effect: