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 .
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);
}
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.
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:
Edit the token in tokens/themes/<theme>/theme.tokens.json (or the relevant
<component>.tokens.json file for component tokens) for every theme
Run yarn build in this package to regenerate all outputs
Run yarn test --testPathPatterns=packages/themes from the repo root to
confirm nothing regressed
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!
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.