Definition
Design tokens are language-agnostic, and can be translated to any environment. On Firefox for desktop, variables are represented in CSS.
As an example, the toggle uses several design tokens. Here are a few component-level toggle tokens and the tokens they map to and what raw values they ultimately point to:
|
Component token |
Application token |
Base token |
Raw value |
|---|---|---|---|
|
--toggle-width |
n/a |
--size-item-large |
32px |
|
--toggle-background-color-pressed |
--color-accent-primary |
--color-blue-60 |
oklch(55% 0.24 260) |
|
--toggle-border-radius |
n/a |
--border-radius-circle |
9999px |
Although the design tokens methodology is industry-wide, there is no one-size-fits-all approach.
Therefore, our design tokens are defined and implemented for the purposes of serving Firefox UI. This document should capture everything you need to know about our design system's design tokens.
The goal is for all of us who work on Firefox to share a common and maintainable system for how we refer to and consume UI styles, and for Firefox UI to be styled consistently.
Tiers
Base
Base design tokens represent the most basic, or foundational, groups of design tokens that point to the actual hard-coded values of the design system. They can be referenced to create more meaningful tokens.
/* tokens-shared.css */
--color-blue-50: oklch(62% 0.24 260);
--color-blue-60: oklch(55% 0.24 260);
--color-blue-70: oklch(48% 0.2 260);
Application
Application design tokens represent the more semantic groups of design tokens that give meaning to base values based on their purpose or how/where they are applied.
/* tokens-brand.css */
--color-accent-primary: light-dark(var(--color-blue-60),var(--color-cyan-30));
Component
Component design tokens represent design tokens scoped to a specific component or element. While the "Application" tier can handle most if not all styling use cases, tier 3 helps encapsulate style decisions at the component level.
Although some component-specific tokens for basic HTML elements (e.g. button) live in tokens-shared.css today, component-specific tokens should live at the component-level file (e.g. moz-toggle.css) so that they can't be used outside that specific component's domain.
/* moz-toggle.css */
--toggle-background-color-pressed: var(--color-accent-primary);
Modes
Light and dark
All application-level and component-level tokens have dark mode counterparts. We rely on the light-dark() CSS function to set light and dark mode colors at the token assignment level.
// tokens-shared.css
--icon-color: light-dark(var(--color-gray-70), var(--color-gray-05));
High contrast
We rely on two queries for assigning HCM counterpart variables, @media (prefers-contrast) and @media (forced-colors). They are found at the bottom of tokens-shared.css. To learn more about these HCM media queries, please consult these accessibility docs.
Note that certain components will need styles that only apply to high contrast mode (e.g., HCM relies on borders that do not exist in non-HCM). In such instances, tokens are only added under the high contrast mode media query rules. On the other hand, if something, such as a color, does not apply to HCM contexts, then these tokens are added under a @media not (prefers-contrast) query.
// tokens-shared.css
@layer tokens-prefers-contrast {
@media (prefers-contrast) {
:root,
:host(.anonymous-content-host) {
--icon-color: light-dark(var(--color-gray-70), var(--color-gray-05));
}
}
}