// scss-docs-start root-theme-tokens
// Generate semantic theme colors
-@each $color-name, $color-map in $new-theme-colors {
+@each $color-name, $color-map in $theme-colors {
@each $key, $value in $color-map {
$root-tokens: map.set($root-tokens, --#{$color-name}-#{$key}, $value);
}
@function theme-color-values($key) {
$result: ();
- @each $color-name, $color-map in $new-theme-colors {
+ @each $color-name, $color-map in $theme-colors {
@if map.has-key($color-map, $key) {
$result: map.merge($result, ($color-name: map.get($color-map, $key)));
}
// Generate theme classes dynamically based on the keys in each theme color map
@mixin generate-theme-classes() {
- @each $color-name, $color-map in $new-theme-colors {
+ @each $color-name, $color-map in $theme-colors {
.theme-#{$color-name} {
@each $key, $value in $color-map {
--theme-#{$key}: var(--#{$color-name}-#{$key});
}
// scss-docs-start theme-colors
-$new-theme-colors: (
+$theme-colors: (
"primary": (
"base": var(--blue-500),
"text": light-dark(var(--blue-600), var(--blue-400)),
<Code containerClass="bd-example-snippet" lang="js" filePath={getDocsRelativePath('/static/docs/[version]/assets/js/color-modes.js')} />
-## Adding theme colors
-
-Adding a new color in `$theme-colors` is not enough for some of our components like [alerts]([[docsref:/components/alerts]]) and [list groups]([[docsref:/components/list-group]]). New colors must also be defined in `$theme-colors-text`, `$theme-colors-bg-subtle`, and `$theme-colors-border-subtle` for light theme; but also in `$theme-colors-text-dark`, `$theme-colors-bg-subtle-dark`, and `$theme-colors-border-subtle-dark` for dark theme.
-
-This is a manual process because Sass cannot generate its own Sass variables from an existing variable or map. In future versions of Bootstrap, we'll revisit this setup to reduce the duplication.
-
-```scss
-// Required
-@import "functions";
-@import "variables";
-@import "variables-dark";
-
-// Add a custom color to $theme-colors
-$custom-colors: (
- "custom-color": #712cf9
-);
-$theme-colors: map-merge($theme-colors, $custom-colors);
-
-@import "maps";
-@import "mixins";
-@import "utilities";
-
-// Add a custom color to new theme maps
-
-// Light mode
-$custom-colors-text: ("custom-color": #712cf9);
-$custom-colors-bg-subtle: ("custom-color": #e1d2fe);
-$custom-colors-border-subtle: ("custom-color": #bfa1fc);
-
-$theme-colors-text: map-merge($theme-colors-text, $custom-colors-text);
-$theme-colors-bg-subtle: map-merge($theme-colors-bg-subtle, $custom-colors-bg-subtle);
-$theme-colors-border-subtle: map-merge($theme-colors-border-subtle, $custom-colors-border-subtle);
-
-// Dark mode
-$custom-colors-text-dark: ("custom-color": #e1d2f2);
-$custom-colors-bg-subtle-dark: ("custom-color": #8951fa);
-$custom-colors-border-subtle-dark: ("custom-color": #e1d2f2);
-
-$theme-colors-text-dark: map-merge($theme-colors-text-dark, $custom-colors-text-dark);
-$theme-colors-bg-subtle-dark: map-merge($theme-colors-bg-subtle-dark, $custom-colors-bg-subtle-dark);
-$theme-colors-border-subtle-dark: map-merge($theme-colors-border-subtle-dark, $custom-colors-border-subtle-dark);
-
-// Remainder of Bootstrap imports
-@import "root";
-@import "reboot";
-// etc
-```
-
## CSS
### Variables
})}
</div>
-All these colors are available as a Sass map, `$theme-colors`.
-
-{/* <ScssDocs name="theme-colors-map" file="scss/_variables.scss" /> */}
-
-Check out [our Sass maps and loops docs]([[docsref:/customize/sass#maps-and-loops]]) for how to modify these colors.
+All these colors are available as a nested Sass map, `$theme-colors`, in `scss/_theme.scss`. Check out [our Sass maps and loops docs]([[docsref:/customize/sass#maps-and-loops]]) for how to modify these colors.
### Notes on Sass
Bootstrap’s source Sass files include three maps to help you quickly and easily loop over a list of colors and their hex values.
- `$colors` lists all our available base (`500`) colors
-- `$theme-colors` lists all semantically named theme colors (shown below)
+- `$theme-colors` is a nested map of semantically named theme colors (defined in `scss/_theme.scss`)
Within `scss/_variables.scss`, you’ll find Bootstrap’s color variables and Sass map. Here’s an example of the `$colors` Sass map:
Bootstrap’s components are largely built with a base-modifier nomenclature. We group as many shared properties as possible into a base class, like `.btn`, and then group individual styles for each variant into modifier classes, like `.btn-primary` or `.btn-success`.
-To build our modifier classes, we use Sass’s `@each` loops to iterate over a Sass map. This is especially helpful for generating variants of a component by our `$theme-colors` and creating responsive variants for each breakpoint. As you customize these Sass maps and recompile, you’ll automatically see your changes reflected in these loops.
+To build our modifier classes, we use Sass’s `@each` loops to iterate over Sass maps. This is especially helpful for generating variants of a component from our `$theme-colors` nested map and creating responsive variants for each breakpoint. As you customize these Sass maps and recompile, you’ll automatically see your changes reflected in these loops.
Check out [our Sass maps and loops docs]([[docsref:/customize/sass#maps-and-loops]]) for how to customize these loops and extend Bootstrap’s base-modifier approach to your own code.
1. **Color scales** (`_colors.scss`) — Base hue variables defined in `oklch()` generate a full scale of color steps (025–975) as CSS custom properties using `color-mix()`. For example, `--blue-500`, `--red-200`, `--gray-900`.
-2. **Theme colors** (`_theme.scss`) — The `$new-theme-colors` map defines semantic color roles like `primary`, `success`, and `danger`. Each theme color is a nested map with sub-keys: `base`, `text`, `text-emphasis`, `bg`, `bg-subtle`, `bg-muted`, `border`, `focus-ring`, and `contrast`.
+2. **Theme colors** (`_theme.scss`) — The `$theme-colors` map defines semantic color roles like `primary`, `success`, and `danger`. Each theme color is a nested map with sub-keys: `base`, `text`, `text-emphasis`, `bg`, `bg-subtle`, `bg-muted`, `border`, `focus-ring`, and `contrast`.
3. **Global tokens** (`_theme.scss` and `_root.scss`) — Semantic tokens for backgrounds (`$theme-bgs`), foregrounds (`$theme-fgs`), and borders (`$theme-borders`) are defined alongside the `$root-tokens` map, which aggregates everything into `:root` CSS custom properties.
### Theme color map
-The `$new-theme-colors` map defines the semantic color palette. Each entry is a nested map with sub-keys like `base`, `text`, `bg`, `border`, and more. See the [Theme documentation]([[docsref:/customize/theme]]) for the full map, sub-key reference, and usage examples.
+The `$theme-colors` map defines the semantic color palette. Each entry is a nested map with sub-keys like `base`, `text`, `bg`, `border`, and more. See the [Theme documentation]([[docsref:/customize/theme]]) for the full map, sub-key reference, and usage examples.
To modify, add, or remove theme colors at compile time:
```scss
@use "sass:map";
@use "../node_modules/bootstrap/scss/theme" with (
- $new-theme-colors: (
+ $theme-colors: (
"primary": (
"base": var(--indigo-500),
"text": light-dark(var(--indigo-600), var(--indigo-400)),
Bootstrap assumes the presence of some specific keys within Sass maps as we use and extend these ourselves. As you customize the included maps, you may encounter errors where a specific Sass map's key is being used.
-For `$new-theme-colors`, the `primary`, `success`, and `danger` keys are required for links, buttons, and form states. Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues.
+For `$theme-colors`, the `primary`, `success`, and `danger` keys are required for links, buttons, and form states. Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues.
## Functions
To help with this, we included the `color-contrast` function in Bootstrap. It uses the [WCAG contrast ratio algorithm](https://www.w3.org/TR/WCAG/#dfn-contrast-ratio) for calculating contrast thresholds based on [relative luminance](https://www.w3.org/TR/WCAG/#dfn-relative-luminance) in an `sRGB` color space to automatically return a light (`#fff`), dark (`#212529`) or black (`#000`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
-For example, to generate color swatches from our `$new-theme-colors` map:
+For example, to generate color swatches from our `$theme-colors` map:
```scss
-@each $color, $value in $new-theme-colors {
+@each $color, $value in $theme-colors {
.swatch-#{$color} {
color: color-contrast(map.get($value, "base"));
}
## How it works
-Theme colors are defined in the `$new-theme-colors` Sass map. This map is used to generate our theme color values. You'll find these values in the `_theme.scss` file. These are where we define our design tokens for Bootstrap, across both light and dark color modes.
+Theme colors are defined in the `$theme-colors` Sass map. This map is used to generate our theme color values. You'll find these values in the `_theme.scss` file. These are where we define our design tokens for Bootstrap, across both light and dark color modes.
Theme colors include the following semantic colors:
## Layer colors
-Color tokens that are used for foreground, background, and border colors are called **theme layer colors** in Bootstrap. These layer colors are configured outside the `$new-theme-colors` Sass map in their own respective Sass maps as they have more nuanced theming use cases.
+Color tokens that are used for foreground, background, and border colors are called **theme layer colors** in Bootstrap. These layer colors are configured outside the `$theme-colors` Sass map in their own respective Sass maps as they have more nuanced theming use cases.
Tokens for these three themes are defined in the `$theme-fgs`, `$theme-bgs`, and `$theme-borders` Sass maps. These maps are used to generate color mode adaptive `color`, `background-color`, and `border-color` values that are then consumed by our utilities and components. You'll find these values in the `_theme.scss` file.
## Theme utility classes
-We generate theme utility classes from the `$new-theme-colors` Sass map that make all theme color tokens available as CSS variables. We use these in our component variants to allow for quick theming with a single, global class. This requires components to support theme colors, and not every component does.
+We generate theme utility classes from the `$theme-colors` Sass map that make all theme color tokens available as CSS variables. We use these in our component variants to allow for quick theming with a single, global class. This requires components to support theme colors, and not every component does.
With theme utilities, you can apply a theme color to an element with a single class.
## CSS variables
-CSS variables are generated from the `$new-theme-colors` Sass map at the `:root` level inside `_root.scss` using a Sass loop.
+CSS variables are generated from the `$theme-colors` Sass map at the `:root` level inside `_root.scss` using a Sass loop.
<ScssDocs name="root-theme-tokens" file="scss/_root.scss" />
projects / thirdparty / bootstrap.git / commitdiff
