---
system: carbon
category: foundations
topic: themes
content_type: guidance
status: latest
version_label: "v11"
retrieved: 2026-05-12
source_url: https://carbondesignsystem.com/elements/themes/overview/
tags: [themes, tokens, customization, sass, white, gray-10, gray-90, gray-100]
---

# 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:

```scss
@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:

```scss
@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.js`
- `packages/themes/src/g10.js`
- `packages/themes/src/g90.js`
- `packages/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.