File structure
The desktop tokens’ system serves our browser's two different ecosystems, the chrome and in-content (about:) pages, since they don't always share the same styling decisions, and consequently, values.
The chrome of the browser is styled to look and feel like it belongs to the user's operating system, and to also support theming. Therefore, typography and color rules are different from the rest of our application features that load within in-content pages.
Token files are stored in the design-system folder within toolkit/themes/shared. In order to support the difference in styles, logic is split between three stylesheets: brand, platform, and shared.
toolkit
└── themes
└── shared
└── design-system
├── design-tokens.json
├── tokens-brand.css
├── tokens-platform.css
└── tokens-shared.css
Folder tree view of where tokens live in firefox
A token's context is the key to understanding the relationship between these stylesheets. If a token isn't set at the shared level, that means that it has different values between brand and platform contexts.
Shared tokens (tokens-shared.css) are imported into brand tokens (tokens-brand.css) and platform tokens (tokens-platform.css).
common-shared.css imports tokens-brand.css so that in-content/about: pages can make use of our brand values, while global-shared.css, which styles the chrome, imports tokens-platform.css so that the chrome can access operating system and themeable values.
design-tokens.json
The JSON file is the source of truth that houses all of our tokens. The data gets transformed into separate CSS token files tokens-brand.css, tokens-platform, and tokens-shared.css due to how the browser is styled (see section above). Learn more about the JSON workflow and how it works in Acorn’s Storybook.
The benefit of storing our design tokens with a platform-agnostic format such as JSON is that it can be converted or translated into other languages or tools beyond just CSS (e.g. Swift, Kotlin, Figma variables).
tokens-brand.css
This file is for token values specific to the brand, such as colors and typographical styles. This stylesheet should be loaded in domains that rely on brand values.
For example, we re-map the accent color token in tokens-brand.css to the value we want to use in brand contexts (in-content/about: pages):
/* tokens-brand.css */
--color-accent-primary: light-dark(var(--color-blue-60), var(--color-cyan-30));
tokens-platform.css
This file is for token values used the browser chrome that come from the user’s operating system, such as colors and fonts.
For example, we re-map the accent color token in tokens-platform.css to the value we want to use in platform contexts (the chrome):
/* tokens-platform.css */
--color-accent-primary: AccentColor;
tokens-shared.css
This file is for tokens that are shared between brand and platform contexts.
For example, both the chrome and in-content pages make use of the same border-radius patterns:
/* tokens-shared.css */
--border-radius-small: 4px;
File organization
Design token files are organized for consumption purposes. Token groups should be listed by alphabetical order: Border, Color, Font Weight...
A comment heading should be added above each token group with its name:
/** Color **/
--color-blue-0: oklch(97% 0.05 260);
--color-blue-10: oklch(90% 0.13 260);
--color-blue-20: oklch(83% 0.17 260);
...
Design tokens should be listed by alphabetical order:
/** Focus outline **/
--focus-outline: var(--focus-outline-width) solid var(--focus-outline-color);
--focus-outline-color: var(--color-accent-primary);
--focus-outline-inset: calc(-1 * var(--focus-outline-width));
--focus-outline-offset: 2px;
--focus-outline-width: 2px;
Scale groups should be listed from the beginning to the end of the scale (i.e. smallest to largest value). Any semantic tokens within a scale, such as the --font-size-root example below, can be listed above it:
/** Font size **/
--font-size-root: 15px;
--font-size-small: 0.867rem; /* 13px */
--font-size-large: 1.133rem; /* 17px */
--font-size-xlarge: 1.467rem; /* 22px */
--font-size-xxlarge: 2.2rem; /* 33px */