“One component set, four themes, five modes: IBM Carbon, Atlassian and the first stable Design Tokens Specification show how theming becomes configuration instead of a second library.
A theme should be configuration, not a second library
A design system that ships a second component library for dark mode has already failed at theming.
The first stable Design Tokens Specification arrived on 28 October 2025, and the production systems that separate token, role and value have been doing it for years without calling it a standard.
What a token is, and why the specification matters
A design token is a named value in a file that design tools and build pipelines can both read. Since 28 October 2025 that file has a standard behind it: the Design Tokens Community Group published the first stable Design Tokens Specification, release 2025.10, with the Format, Color and Resolver modules final.
Portability is the whole point. The implementations listed with the group include Style Dictionary, Tokens Studio, Terrazzo, Figma, Penpot and Sketch, so a value can travel from a design file into a build without a person retyping it. The popular belief that tokens are renamed CSS variables does not survive that requirement; a specification with modules exists precisely because hand-renamed variables stop at the first tool change.
Four systems and the layer model each one publishes
| System | Published structure | Themes or modes | What it demonstrates |
|---|---|---|---|
| IBM Carbon | Token, role and value layers | Four themes: White, Gray 10, Gray 90, Gray 100 | Components stay theme-agnostic while values change |
| Atlassian Design System | Foundation, property, modifier naming | Light, dark, high-contrast, compact density, reduced motion | Density and motion belong to the theme layer |
| Salesforce Lightning Design System | Per-token versioning with GA status | Tokens released individually, such as the accessible brand token in v2.6.0 | A single token can ship without breaking the set |
| Material 3 | Dynamic colour generation | Palettes from a wallpaper or from in-product content | The theme can be produced at runtime from an input |
Three ways the theme layer is organised
Four themes, one component set
IBM Carbon separates token, role and value, and ships four themes: White as the default, then Gray 10, Gray 90 and Gray 100. A component never reads a raw value; it reads a role, and the theme supplies the value behind that role.
The practical consequence is that adding a fifth theme costs a file, not a component revision. It also means the design review can argue about the theme values in one place instead of chasing colours through the library.
Five modes, density and motion included
Atlassian's theme list runs to light, dark, high-contrast, compact density and reduced motion, with a naming convention built from foundation, property and modifier. Read that list as a statement about where the system expects variation to happen.
Density and motion sitting at theme level is the interesting part: a data grid can be compact for one audience and comfortable for another without a forked component, and a user who needs less motion gets a mode rather than a support ticket.
Colour generated from an input the system does not own
Material 3 dynamic colour generates palettes from a user's wallpaper or from in-product content, and multiple colour sources are supported. This is the opposite posture to a fixed brand theme: the system accepts an input it cannot control and still has to return a readable interface.
It suits a consumer product on a platform that already knows the user's preferences, and it is the wrong architecture where a licensed brand colour has to survive untouched.
Dark mode is not an inversion
The belief that a dark theme is the light theme inverted is the most expensive shortcut in this work. Carbon defines four distinct themes and separates role from value; Atlassian publishes separate values for each of its themes. Neither system inverts, because inversion breaks the roles: distance, elevation and state all have to be re-decided, since a shadow that reads as separation on white does not read as separation on black.
The second shortcut is treating theming as component duplication: a mobile component, a dark component, a marketing variant. Carbon and Atlassian keep components theme-agnostic and swap values instead, which is why a system with four themes and five modes can still have exactly one button. Component count and theme count are independent numbers, and a library that conflates them stops being maintainable the moment a second brand appears.
The counts that describe a mature theme layer
4themes
Themes in IBM Carbon: White, Gray 10, Gray 90 and Gray 100
Token, role and value layers keep components theme-agnostic. Carbon Design System, accessed 2026.
5modes
Atlassian themes: light, dark, high-contrast, compact density and reduced motion
Named as foundation, property and modifier. Atlassian Design System, accessed 2026.
3modules
Format, Color and Resolver, final in the first stable Design Tokens Specification
Release 2025.10, published 28 October 2025 by the Design Tokens Community Group.
24pixels
Target size minimum that a compact density must not cross
Success criterion 2.5.8 in WCAG 2.2, W3C, 2023.
How to structure the theme a project actually needs
One semantic layer
One product, one brand, and no white-label requirement on the roadmap yet.
Per-brand value files
Several brands, regions or franchisees share the same components and must not share the same colour values.
Colour generated at runtime
The interface has to adapt to a user's device or to content nobody on the team wrote.
One semantic layer names every value by the role it plays — surface, quiet text, strong border, focus ring — and keeps the raw values underneath. Carbon's separation of token, role and value is the published version of this pattern, and it is the cheapest structure to begin with because it assumes nothing about a second brand. The risk is naming roles after what they look like: a role called grey border cannot become a brand-tinted border in the next theme.
Per-brand value files keep the components theme-agnostic and swap the values: the same button reads differently in two brands with no conditional code and no fork. Atlassian's foundation, property and modifier convention is built for that enumeration, and Salesforce versions each token so a brand-specific addition can ship without destabilising the rest. What you are buying here is a single source of truth; what you are paying for is the discipline of never patching a colour in the component.
Runtime colour derives palettes from an input the team does not control, as Material 3 does with wallpapers and in-product content, supporting multiple colour sources. The engineering bill is real: contrast has to hold for inputs nobody previewed. Choose it when personalisation is a product feature, and avoid it when a licensed identity has to remain identical across every surface.
Density is a token decision, not a habit
Density is where theming stops being a colour conversation. Atlassian publishes compact density as a theme rather than a set of overrides, and accessibility law sets the floor it cannot cross: success criterion 2.5.8 Target Size (Minimum) in WCAG 2.2 requires a target of 24 by 24 CSS pixels, and it entered the recommendation in 2023.
Treating density as a token family is what allows a desktop data grid and a field application to share components. The alternative is a bespoke dense component for one screen, which is component duplication arriving through the back door. A compact theme with a documented minimum is a decision the team can defend; a hand-tightened padding is a preference that will be quietly undone in the next sprint.
Four questions that decide a theming review
Why does a token file need a specification
Because the tooling changes. The Design Tokens Community Group lists implementations across Style Dictionary, Tokens Studio, Terrazzo, Figma, Penpot and Sketch, and the specification's Format, Color and Resolver modules are what keep a token readable when a team swaps one of them.
Without a shared format, every tool change becomes a migration project with a designer in the middle of it.
How do we add a second brand without forking the components
Keep the components theme-agnostic and add a value file. Carbon's four themes share one component set, and Atlassian's naming convention is designed for enumerating themes rather than duplicating elements.
The test is simple: if adding a brand requires editing a component, the theme layer is incomplete.
Where does the dark theme get its values
From a separate set of values chosen for the dark surface, not from an inverted copy. Carbon publishes four distinct themes with role and value separated; Atlassian publishes its own values per theme. Inversion is the reason dark interfaces end up with unreadable borders and glowing shadows.
Decide the dark values in the same review as the light ones, with the same contrast test.
Who owns the tokens after launch
A named owner with a release process. Salesforce's Lightning Design System versions tokens individually and marks the status of each, which is only possible when someone is responsible for the file.
An unowned token file accumulates one-off additions until the theme is decorative again.
One console, several operating modes
A control console is a theme layer with the decoration removed: one set of controls, several modes of use, and labels that have to mean the same thing at every hour of a shift. The two photographs below are operating rooms rather than interfaces, and both make the same demand that a token set has to answer on screen.
What to do with this on Monday
- Version tokens individually, not the library as a whole.Salesforce's Lightning Design System publishes a status per token, so an addition like the accessible brand token in v2.6.0 can ship on its own.
- Name roles before values.Carbon's token, role and value separation is what lets four themes share one set of components, and a role named after a colour cannot survive the second one.
- Put density and motion in the theme layer.Atlassian publishes compact density and reduced motion alongside light and dark, and WCAG 2.2 sets the 24 by 24 pixel target floor.
- Never build a dark theme by inverting a light one.Carbon publishes four distinct themes and Atlassian publishes separate values per theme, because inversion breaks roles rather than re-deciding them.
- Read the specification before buying token tooling.The first stable Design Tokens Specification, release 2025.10, was published on 28 October 2025 with the Format, Color and Resolver modules final.
- Keep the components theme-agnostic.One button across four themes and five modes, with values swapped at the token layer instead of components duplicated.
Sources
- Design Tokens Specification, release 2025.10 — Design Tokens Community Group, 28 October 2025
- Design Tokens Community Group — World Wide Web Consortium, accessed 2026
- Themes overview — IBM Carbon Design System, accessed 2026
- Design tokens — Atlassian Design System, accessed 2026
- Design tokens — Salesforce Lightning Design System, accessed 2026
- Dynamic color — Material Design 3, accessed 2026
- What is new in WCAG 2.2 — World Wide Web Consortium, 2023