

A well-structured token system does more than store design values. It makes switching between different sets of values predictable and low-effort. That's what modes are for.
If you've ever implemented dark mode by duplicating a stylesheet and manually overriding every color value, you've felt the problem modes solve. If you've ever managed a multi-brand design system where every brand has its own color file with slightly different names, you've felt it too. Modes are the structural answer to both.
This article explains what modes are, when to use them, how they interact with the token hierarchy, and how to avoid the complexity trap that catches most teams eventually.
A mode is a named set of token value overrides that can be applied to an entire token collection in a single switch.
Rather than maintaining separate token files for each variation of your design (one for light, one for dark, one per brand), you maintain one set of token names and multiple sets of values that those names can resolve to. Switching the active mode changes what the tokens resolve to, without changing the tokens themselves or the components that reference them.
A simple example: your color-surface-default token resolves to neutral-50 (a near-white) in light mode and neutral-900 (a near-black) in dark mode. The token name stays the same. The component using it stays the same. Only the mode (and therefore the resolved value) changes.
color-surface-default
→ light mode: neutral-50 (#FAFAFA)
→ dark mode: neutral-900 (#171717)
This is a fundamentally different approach to variation than maintaining parallel token files or duplicating component styles. The variation is encoded in the token system, not in the components. Components stay clean; the token layer carries the complexity.
Modes are useful wherever you need an entire set of token values to change together in response to a context switch. The most common use cases are:
The canonical use case. Light and dark modes swap color values (surfaces, text, borders, shadows, interactive states) while leaving everything else (spacing, typography, radius, motion) unchanged.
Light/dark is a good introduction to modes because the mapping is relatively intuitive: most light-mode colors have a clearly corresponding dark-mode value, and the set of tokens that need to change is well-defined.
When a system serves multiple brands, modes allow different brand identities to be expressed through the same component set. Brand A's primary action color might be deep blue; Brand B's might be forest green. With modes, both are expressed as color-action-primary, and the mode determines which raw value that resolves to.
Brand modes typically affect color and typography (font families, occasionally type scales) and leave structural decisions like spacing and layout unchanged. The shared structure is what makes a multi-brand system efficient; the modes are what make it flexible.
Density modes switch spacing and sizing values to accommodate different use contexts: a compact mode for data-heavy interfaces, a comfortable mode for consumer products, a spacious mode for marketing or documentation surfaces.
Density modes are less common than light/dark, but they're valuable for products that need to serve genuinely different contexts in the same interface: a settings panel that needs to be dense and an onboarding flow that needs breathing room, for example.
High contrast modes increase the contrast ratios of color tokens to meet accessibility requirements beyond the standard WCAG thresholds, or to support users with visual impairments who prefer elevated contrast. Rather than building high-contrast support into components directly, a high-contrast mode swaps color tokens to more extreme values while leaving everything else in place.
Platform modes handle cases where token values need to differ between web, iOS, and Android (different default font sizes, different spacing conventions, different elevation treatments) while the semantic token names stay consistent. As covered in Article 04, platform divergence at the alias tier keeps the global token source clean.
Understanding which tier of your token hierarchy modes operate on is the key to making them work correctly. The rule is straightforward: modes change alias token values, not global token values.
Your global tokens (the raw palette, the full spacing scale, the type scale) don't change between modes. blue-500 is always #3B82F6. space-4 is always 4px. These are facts about your design language, not decisions about how it's applied.
What changes between modes is what your alias tokens resolve to. In light mode, color-surface-default resolves to neutral-50. In dark mode, it resolves to neutral-900. Both neutral-50 and neutral-900 exist in the global palette, and the mode determines which one the semantic alias points to.
Global tier (unchanged by modes)
neutral-50: #FAFAFA
neutral-900: #171717
Alias tier (resolved differently per mode)
color-surface-default
→ light: {neutral-50}
→ dark: {neutral-900}
Component tier (unchanged by modes, references alias)
card-background → {color-surface-default}
This separation is what gives modes their power. Because global values are stable and only aliases switch, you can add a new mode without touching a single component. You're only adding a new set of alias resolutions (a new column in the mode table, if you think of it that way).
It also means that if a component is accidentally referencing a global token directly (card-background: neutral-50) instead of going through the alias layer, it won't respond to mode switching. This is one of the most common causes of mode-related bugs in token systems, and one of the strongest practical arguments for never letting components reference the global tier directly.
In a real system, not every token needs a value defined in every mode. Modes can inherit from a base set of values, with only the tokens that differ in that mode explicitly overridden.
This is the most maintainable approach for most systems. Rather than duplicating the full token set for every mode, you define a base (typically light mode or the default brand) and then define each additional mode as a set of overrides on top of the base.
Base (light mode)
color-surface-default: neutral-50
color-text-primary: neutral-900
color-border-default: neutral-200
color-action-primary: blue-500
Dark mode overrides
color-surface-default: neutral-900 ← overridden
color-text-primary: neutral-50 ← overridden
color-border-default: neutral-700 ← overridden
color-action-primary: blue-400 ← overridden (slightly lighter for contrast)
A token with no dark-mode override falls back to its base value. This keeps mode definitions lean: you only specify what changes, not everything.
Fallback order matters. When a token is not defined in the active mode, the system needs to know where to look next. In most implementations, the fallback chain is: active mode → base mode → error. A well-designed token system documents what the fallback behavior is and tests that unresolved tokens produce a visible error rather than a silent wrong value.
Nested or scoped modes introduce additional inheritance complexity. Some systems allow modes to be applied at different scopes: a dark mode applied to the whole page, but a light mode applied to a specific sidebar component. In this case, the scoped mode takes precedence for components inside its scope, and the page-level mode applies everywhere else. This is useful for things like a persistent light-mode navigation bar in an otherwise dark-mode product, or an embedded widget that maintains its own theme.
This is where most teams eventually run into trouble. Modes are additive. Each new mode multiplies the number of token values that need to be defined, maintained, and tested. The combinatorial growth can become significant quickly.
A simple example: two color modes (light, dark) × two brand modes (Brand A, Brand B) = four mode combinations. Add a density mode (compact, comfortable) and you're at eight. Add high contrast support for each and you're at sixteen. Each combination is a distinct set of token values that needs to be correct and tested.
The growth isn't always linear in practice. Many tokens don't change across all modes, so the number of values you need to explicitly define is smaller than the worst case. But the combinatorial complexity is real, and it has consequences for documentation, testing, and governance.
A few principles for keeping modes manageable:
Separate orthogonal concerns into independent mode axes. Color modes (light/dark) and brand modes should be independent. You shouldn't need a "Brand A dark" mode as a single combined entity if Brand A and dark are separate dimensions. Tools that support mode stacking let you apply both simultaneously without creating a combined mode definition.
Only add a mode when you have a concrete requirement. It's tempting to add density modes or platform modes "just in case." But a mode that isn't actively used is a maintenance burden: values drift out of sync, tests don't get run, documentation falls behind. Modes earn their place by solving a real, present problem.
Be honest about what actually changes. Before adding a new mode, audit which tokens would actually have different values in that mode. If the answer is fewer than a handful, a mode is probably not the right mechanism; a component-level override or a one-time design decision might be simpler.
Define a governance process for modes. Adding a mode should require the same level of review as adding a new token category. Who approves new modes? Who is responsible for maintaining the values? Who tests that every combination works? Without clear answers, modes accumulate and degrade.
A useful frame: modes are powerful because they're systematic. They're also costly because they're systematic. Every token in the system potentially needs a value in every mode. Treat them as a high-leverage tool, not a default response to variation.
Not every design variation needs a mode. It's worth distinguishing between variation that is systematic (applying consistently across all components in a given context) and variation that is localized to a specific component or instance.
Systematic variation across an entire surface or context is a good candidate for a mode. A dark sidebar, a high-contrast focus state, a compact data table: these apply consistently to everything in their scope.
Localized variation at the component level is usually better handled by component tokens or props. A button that needs a different background in a specific context doesn't need a mode. It needs a component-level override point. Reaching for a mode to solve a localized problem adds unnecessary weight to the token system.
Modes are the mechanism. The articles that follow cover how to put them into practice for specific use cases.
Article 07 — Multi-brand, multi-product and white-label token architecture covers how brand modes fit into a layered token system designed to serve multiple visual identities from a single foundation.
Article 08 — Theming with design tokens goes deeper on theme switching — how to structure your alias tier to support multiple themes, how to implement switching in code, and how to scope themes at different levels of the page.
Article 09 — Implementing dark mode with design tokens focuses on dark mode specifically — the common pitfalls, how to structure semantic color tokens for light and dark from day one, and how to handle edge cases like elevation and accessibility.
If you're working in Figma and want to see how modes translate to variable collections and mode switching in that tool specifically, Article 16 — Figma variable modes in depth covers the Figma implementation in full.
