@carbon/themes
Version:
Themes for applying color in the Carbon Design System
190 lines (167 loc) • 19.7 kB
Markdown
# `/themes`
> Sass documentation for `/themes`
## Usage
There are several entrypoints that you can use with `/themes`, including:
| Filename | Description |
| ------------------------------------------- | ------------------------------------------------------ |
| ` '/themes';` | Package entrypoint |
| ` '/themes/scss/config';` | Specify config options for the package |
| ` '/themes/scss/themes';` | Theme definitions for white, g10, g90, and g100 |
| ` '/themes/scss/theme';` | Set the current theme, get token values from the theme |
| ` '/themes/scss/tokens';` | Access theme tokens |
| ` '/themes/scss/compat/themes';` | v10 Theme definitions for white, g10, g90, and g100 |
| ` '/themes/scss/compat/tokens';` | v10 theme tokens |
_Note: the white, g10, g90, and g100 themes are only available in the
`scss/themes` file and are not re-exported in `@carbon/themes`. To learn more,
checkout our [FAQ](#why-are-the-themes-not-exported-in-carbonthemes)._
You can bring in `/themes` by using ``:
```scss
'/themes';
.my-component {
// Use tokens from the theme, this will map to a CSS Custom Property
color: themes.$token-01;
}
:root {
// Emit CSS Custom Properties for the current theme
themes.theme();
}
// Get the value of a specific token
$custom-variable: rgba(themes.get('token-01'), 0.25);
```
You can configure the current theme with the `$theme` option:
```scss
'/themes/scss/themes' as *;
'/themes' with (
$theme: $g100
);
```
You can also extend the theme with your own custom tokens:
```scss
'/themes/scss/themes';
'/themes' with (
$fallback: themes.$g100,
$theme: (
token-01: #000000,
)
);
```
## API
| Import | Export | Description | !default |
| :--------------------------- | :--------------------------- | :------------------------------------------------------------------------------------ | :------- |
| `/themes/scss/themes` | | | |
| | `$white` | | ✅ |
| | `$g10` | | ✅ |
| | `$g90` | | ✅ |
| | `$g100` | | ✅ |
| `/themes` | | The default entrypoint which re-exports values from all other modules in this package | |
| | `$fallback` | | ✅ |
| | `$theme` | | ✅ |
| | `$background` | | ✅ |
| | `$background-active` | | ✅ |
| | `$background-selected` | | ✅ |
| | `$background-selected-hover` | | ✅ |
| | `$background-hover` | | ✅ |
| | `$background-brand` | | ✅ |
| | `$background-inverse` | | ✅ |
| | `$background-inverse-hover` | | ✅ |
| | `$layer-01` | | ✅ |
| | `$layer-active-01` | | ✅ |
| | `$layer-hover-01` | | ✅ |
| | `$layer-selected-01` | | ✅ |
| | `$layer-selected-hover-01` | | ✅ |
| | `$layer-02` | | ✅ |
| | `$layer-active-02` | | ✅ |
| | `$layer-hover-02` | | ✅ |
| | `$layer-selected-02` | | ✅ |
| | `$layer-selected-hover-02` | | ✅ |
| | `$layer-03` | | ✅ |
| | `$layer-active-03` | | ✅ |
| | `$layer-hover-03` | | ✅ |
| | `$layer-selected-03` | | ✅ |
| | `$layer-selected-hover-03` | | ✅ |
| | `$layer-selected-inverse` | | ✅ |
| | `$layer-selected-disabled` | | ✅ |
| | `$layer-accent-01` | | ✅ |
| | `$layer-accent-active-01` | | ✅ |
| | `$layer-accent-hover-01` | | ✅ |
| | `$layer-accent-02` | | ✅ |
| | `$layer-accent-active-02` | | ✅ |
| | `$layer-accent-hover-02` | | ✅ |
| | `$layer-accent-03` | | ✅ |
| | `$layer-accent-active-03` | | ✅ |
| | `$layer-accent-hover-03` | | ✅ |
| | `$field-01` | | ✅ |
| | `$field-hover-01` | | ✅ |
| | `$field-02` | | ✅ |
| | `$field-hover-02` | | ✅ |
| | `$field-03` | | ✅ |
| | `$field-hover-03` | | ✅ |
| | `$interactive` | | ✅ |
| | `$border-subtle-00` | | ✅ |
| | `$border-subtle-01` | | ✅ |
| | `$border-subtle-selected-01` | | ✅ |
| | `$border-subtle-02` | | ✅ |
| | `$border-subtle-selected-02` | | ✅ |
| | `$border-subtle-03` | | ✅ |
| | `$border-subtle-selected-03` | | ✅ |
| | `$border-strong-01` | | ✅ |
| | `$border-strong-02` | | ✅ |
| | `$border-strong-03` | | ✅ |
| | `$border-inverse` | | ✅ |
| | `$border-interactive` | | ✅ |
| | `$border-disabled` | | ✅ |
| | `$text-primary` | | ✅ |
| | `$text-secondary` | | ✅ |
| | `$text-placeholder` | | ✅ |
| | `$text-helper` | | ✅ |
| | `$text-error` | | ✅ |
| | `$text-inverse` | | ✅ |
| | `$text-on-color` | | ✅ |
| | `$text-on-color-disabled` | | ✅ |
| | `$text-disabled` | | ✅ |
| | `$link-primary` | | ✅ |
| | `$link-primary-hover` | | ✅ |
| | `$link-secondary` | | ✅ |
| | `$link-inverse` | | ✅ |
| | `$link-visited` | | ✅ |
| | `$icon-primary` | | ✅ |
| | `$icon-secondary` | | ✅ |
| | `$icon-inverse` | | ✅ |
| | `$icon-on-color` | | ✅ |
| | `$icon-on-color-disabled` | | ✅ |
| | `$icon-disabled` | | ✅ |
| | `$support-error` | | ✅ |
| | `$support-success` | | ✅ |
| | `$support-warning` | | ✅ |
| | `$support-info` | | ✅ |
| | `$support-error-inverse` | | ✅ |
| | `$support-success-inverse` | | ✅ |
| | `$support-warning-inverse` | | ✅ |
| | `$support-info-inverse` | | ✅ |
| | `$support-caution-major` | | ✅ |
| | `$support-caution-minor` | | ✅ |
| | `$support-caution-undefined` | | ✅ |
| | `$highlight` | | ✅ |
| | `$overlay` | | ✅ |
| | `$toggle-off` | | ✅ |
| | `$shadow` | | ✅ |
| | `$focus` | | ✅ |
| | `$focus-inset` | | ✅ |
| | `$focus-inverse` | | ✅ |
| | `$skeleton-background` | | ✅ |
| | `$skeleton-element` | | ✅ |
### Configuration
## FAQ
### Why are the themes not exported in `/themes`?
In order to support ` '/themes' with` in Sass Modules, unfortunately
we cannot re-export the themes available in `scss/modules/themes`. If we
implemented the entrypoint at `/themes` to re-export that module, then
Sass would not compile when doing the following:
```scss
'/themes/scss/modules/themes';
'/themes' with (
$theme: themes.$g100
);
```
This is because the `scss/modules/themes` file will have been initialized twice
which is not allowed in the Sass Module system.