Themes
Carbon Design System — Themes
Overview
Themes are used to customize component styles to fit a specific visual aesthetic. By using Carbon's token system, all component colors update together when a theme changes — there is no need to modify individual components.
Core Concepts
| Term | Definition |
|---|---|
| Theme | A collection of visual attributes assigned to tokens to create a specific aesthetic |
| Token | A role-based identifier that assigns a value to a theme. Tokens are universal and never change across themes |
| Role | The systematic usage of a token. Roles cannot be changed between themes |
| Value | The actual style (hex code) assigned to a token |
The Four Built-in Themes
Carbon ships four themes out of the box:
| Theme | Mode | Background | Notes |
|---|---|---|---|
| White | Light | #ffffff | Default; installed as the default theme in @carbon/react |
| Gray 10 | Light | #f4f4f4 | Alternative light theme |
| Gray 90 | Dark | #262626 | Dark alternative |
| Gray 100 | Dark | #161616 | Darkest; highest contrast dark theme |
Comparison: the same token resolves to different values in each theme:
| Token | Role | White value | Gray 100 value |
|---|---|---|---|
$text-secondary | Label color | Gray 70 | Gray 30 |
$text-primary | Primary text | Gray 100 | Gray 10 |
$border-strong | Border bottom | Gray 50 | Gray 60 |
$icon-primary | Primary icon | Gray 100 | Gray 10 |
$field-01 | Field background | Gray 10 | Gray 90 |
$background | Page background | White | Gray 100 |
Switching the Default Theme
When @carbon/react is installed, the White theme is active by default. To switch:
@use '@carbon/react/scss/themes';
@use '@carbon/react/scss/theme' with (
$theme: themes.$g100
);
Available theme variables: themes.$white, themes.$g10, themes.$g90, themes.$g100.
Custom Theme
To create a brand-customized theme, override any token values from the default:
@use '@carbon/react/scss/theme' with (
$theme: (
background: #e2e2e2,
text-primary: #ffffff,
custom-token-01: #000000,
)
);
You can:
- Override any subset of default token values
- Add new custom tokens for brand-specific patterns
- Mix brand values with unchanged default tokens
Token Categories
Tokens are organized into four categories that span all themes:
| Category | Purpose |
|---|---|
| Color | Universal color variables for backgrounds, text, icons, borders, support states |
| Spacing | Spacing scale for component and layout use |
| Typography | Type styles (font size, weight, line-height, letter-spacing) |
| Global | Component-level variables like layer usage or border width |
All token definitions for each theme are available in the @carbon/themes package source:
packages/themes/src/white.jspackages/themes/src/g10.jspackages/themes/src/g90.jspackages/themes/src/g100.js
Token Prefix
Carbon's Sass tokens use the $ prefix (e.g. $layer-01, $text-primary, $interactive). Tokens can be nested — for example, $interactive internally references the IBM color palette token $blue-60 in the White theme.
For CSS custom property usage, tokens are exposed as --cds-* variables when the Carbon stylesheet is included.