From: Mark Otto Date: Wed, 4 Mar 2026 05:49:35 +0000 (-0800) Subject: Rename $new-theme-colors to $theme-colors, update docs for old and new theme maps... X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=36ff50095a901c2443c3ab8378fe277c5664c0ba;p=thirdparty%2Fbootstrap.git Rename $new-theme-colors to $theme-colors, update docs for old and new theme maps (#42112) --- diff --git a/scss/_root.scss b/scss/_root.scss index d5ad07053c..09101cdbbc 100644 --- a/scss/_root.scss +++ b/scss/_root.scss @@ -148,7 +148,7 @@ $root-tokens: defaults( // 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); } diff --git a/scss/_theme.scss b/scss/_theme.scss index ef341c8da4..42b4671093 100644 --- a/scss/_theme.scss +++ b/scss/_theme.scss @@ -6,7 +6,7 @@ @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))); } @@ -35,7 +35,7 @@ // 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}); @@ -59,7 +59,7 @@ } // scss-docs-start theme-colors -$new-theme-colors: ( +$theme-colors: ( "primary": ( "base": var(--blue-500), "text": light-dark(var(--blue-600), var(--blue-400)), diff --git a/site/src/content/docs/customize/color-modes.mdx b/site/src/content/docs/customize/color-modes.mdx index f84ccaa4fc..4d6573ecb1 100644 --- a/site/src/content/docs/customize/color-modes.mdx +++ b/site/src/content/docs/customize/color-modes.mdx @@ -182,54 +182,6 @@ Here’s a look at the JavaScript that powers it. Feel free to inspect our own d -## 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 diff --git a/site/src/content/docs/customize/color.mdx b/site/src/content/docs/customize/color.mdx index d241f3606b..aaf1de0af4 100644 --- a/site/src/content/docs/customize/color.mdx +++ b/site/src/content/docs/customize/color.mdx @@ -77,11 +77,7 @@ We use a subset of all colors to create a smaller color palette for generating c })} -All these colors are available as a Sass map, `$theme-colors`. - -{/* */} - -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 @@ -96,7 +92,7 @@ Our `tint-color()` and `shade-color()` functions use `mix()` alongside our `$the 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: diff --git a/site/src/content/docs/customize/components.mdx b/site/src/content/docs/customize/components.mdx index 026a7426e1..c9c798b8c5 100644 --- a/site/src/content/docs/customize/components.mdx +++ b/site/src/content/docs/customize/components.mdx @@ -8,7 +8,7 @@ toc: true 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. diff --git a/site/src/content/docs/customize/sass.mdx b/site/src/content/docs/customize/sass.mdx index e271260f59..e845017de3 100644 --- a/site/src/content/docs/customize/sass.mdx +++ b/site/src/content/docs/customize/sass.mdx @@ -130,7 +130,7 @@ The layers, from lowest to highest level: 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. @@ -204,14 +204,14 @@ Bootstrap includes several Sass maps that generate families of related CSS custo ### 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)), @@ -354,7 +354,7 @@ This removes the `.btn-text` and `.btn-subtle` classes from the compiled CSS whi 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 @@ -396,10 +396,10 @@ In order to meet the [Web Content Accessibility Guidelines (WCAG)](https://www.w 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")); } diff --git a/site/src/content/docs/customize/theme.mdx b/site/src/content/docs/customize/theme.mdx index 24678ef0d5..77fe3e2d62 100644 --- a/site/src/content/docs/customize/theme.mdx +++ b/site/src/content/docs/customize/theme.mdx @@ -42,7 +42,7 @@ export const themeFgs = [ ## 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: @@ -118,7 +118,7 @@ Not all colors can be used for all purposes due to accessibility, color contrast ## 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. @@ -196,7 +196,7 @@ Here are some examples showing them together. Note ## 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. @@ -252,6 +252,6 @@ We use a large, nested Sass map to generate our theme color values. ## 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.