@carbon/themes

Themes for applying color in the Carbon Design System

Getting started

To install @carbon/themes in your project, you will need to run the following command using npm:

npm install -S @carbon/themes

If you prefer Yarn, use the following command instead:

yarn add @carbon/themes

Usage

You can use @carbon/themes in JavaScript or Sass by including this package in your project. By default, @carbon/themes provides a set of color tokens that are pre-defined for a specific theme. Currently, we offer the following color themes: white, gray 10, gray 90, gray 100 .

You can preview all of the token values for this on the Carbon Design System website.

Sass

If your project is using Sass, you can include this package and the corresponding default theme by writing the following in your Sass file:

@use '@carbon/themes/scss/themes';

By default, the white theme will be initialized. If you would like to include another theme, you can do so by setting the global theme variable in the import. For example:

@use '@carbon/themes/scss/themes' as *;
@use '@carbon/themes' with (
  $theme: $g100
);

Inline theming can be done by using the mixin. For example:

@use '@carbon/themes/scss/themes';
@use '@carbon/themes/scss/theme';

// Uses the default white theme here

.my-dark-theme {
  @include theme.theme(themes.$g90);
}

.my-darker-theme {
  @include theme.theme(themes.$g100);
}

JavaScript

If you're looking to use these themes in JavaScript, we export a variety of bindings for you to use, including:

import {
  // An object of all themes
  themes,

  // Direct theme values
  white,
  g10,
  g90,
  g100,

  // Specific token values
  background,
  interactive,
  textPrimary,
} from '@carbon/themes';

Component tokens

The DTCG migration introduced per-component token sets. They are exported as named objects:

Breaking change (11.78.0): Prior to 11.78.0 these objects were double-nested (e.g. buttonTokens.buttonTokens). The repeated property is now undefined — drop it to get the flat object directly.

import {
  buttonTokens,
  tagTokens,
  notificationTokens,
  statusTokens,
  contentSwitcherTokens,
} from '@carbon/themes';

Each object contains the token values for all four themes. The corresponding Sass output is available via @use '@carbon/themes/scss/component-tokens'.

Modifying token values

Token values are defined in tokens/themes/ using the DTCG 2025.10 token format. Each theme has a folder with a theme.tokens.json file (theme tokens) and one <component>.tokens.json file per component (component tokens). These are the single source of truth — do not edit generated files directly. See tokens/README.md for the format.

To add or update a token:

1. Edit the token in tokens/themes/<theme>/theme.tokens.json (or the relevant <component>.tokens.json file for component tokens) for every theme
2. Run yarn build in this package to regenerate all outputs
3. Run yarn test --testPathPatterns=packages/themes from the repo root to confirm nothing regressed

📖 API Documentation

If you're looking for @carbon/themes API documentation, check out:

• Sass

📚 Examples

If you're looking for more examples on how to use @carbon/themes, we have some examples that you can check out:

• preview
• sass-modules

🙌 Contributing

We're always looking for contributors to help us fix bugs, build new features, or help us improve the project documentation. If you're interested, definitely check out our Contributing Guide! 👀

📝 License

Licensed under the Apache 2.0 License.

IBM Telemetry

This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing this package as a dependency you are agreeing to telemetry collection. To opt out, see Opting out of IBM Telemetry data collection. For more information on the data being collected, please see the IBM Telemetry documentation.