Move reassigned Sass maps for colors to another stylesheet (#34942)

scss/_maps.scss

@@ -0,0 +1,44 @@
+// Re-assigned maps
+//
+// Placed here so that others can override the default Sass maps and see automatic updates to utilities and more.
+
+// scss-docs-start theme-colors-rgb
+$theme-colors-rgb: map-loop($theme-colors, to-rgb, "$value") !default;
+// scss-docs-end theme-colors-rgb
+
+// Utilities maps
+//
+// Extends the default `$theme-colors` maps to help create our utilities.
+
+// Come v6, we'll de-dupe these variables. Until then, for backward compatibility, we keep them to reassign.
+// scss-docs-start utilities-colors
+$utilities-colors: $theme-colors-rgb !default;
+// scss-docs-end utilities-colors
+
+// scss-docs-start utilities-text-colors
+$utilities-text: map-merge(
+  $utilities-colors,
+  (
+    "black": to-rgb($black),
+    "white": to-rgb($white),
+    "body": to-rgb($body-color)
+  )
+) !default;
+$utilities-text-colors: map-loop($utilities-text, rgba-css-var, "$key", "text") !default;
+// scss-docs-end utilities-text-colors
+
+// scss-docs-start utilities-bg-colors
+$utilities-bg: map-merge(
+  $utilities-colors,
+  (
+    "black": to-rgb($black),
+    "white": to-rgb($white),
+    "body": to-rgb($body-bg)
+  )
+) !default;
+$utilities-bg-colors: map-loop($utilities-bg, rgba-css-var, "$key", "bg") !default;
+// scss-docs-end utilities-bg-colors
+
+$negative-spacers: if($enable-negative-margins, negativify-map($spacers), null) !default;
+
+$gutters: $spacers !default;

scss/_variables.scss

@@ -90,10 +90,6 @@ $theme-colors: (
 ) !default;
 // scss-docs-end theme-colors-map
 
-// scss-docs-start theme-colors-rgb
-$theme-colors-rgb: map-loop($theme-colors, to-rgb, "$value") !default;
-// scss-docs-end theme-colors-rgb
-
 // The contrast ratio to reach against white, to determine if color changes from "light" to "dark". Acceptable values for WCAG 2.0 are 3, 4.5 and 7.
 // See https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
 $min-contrast-ratio:   4.5 !default;
@@ -382,8 +378,6 @@ $spacers: (
   4: $spacer * 1.5,
   5: $spacer * 3,
 ) !default;
-
-$negative-spacers: if($enable-negative-margins, negativify-map($spacers), null) !default;
 // scss-docs-end spacer-variables-maps
 
 // Position
@@ -406,39 +400,6 @@ $body-bg:                   $white !default;
 $body-color:                $gray-900 !default;
 $body-text-align:           null !default;
 
-// Utilities maps
-//
-// Extends the default `$theme-colors` maps to help create our utilities.
-
-// Come v6, we'll de-dupe these variables. Until then, for backward compatibility, we keep them to reassign.
-// scss-docs-start utilities-colors
-$utilities-colors: $theme-colors-rgb !default;
-// scss-docs-end utilities-colors
-
-// scss-docs-start utilities-text-colors
-$utilities-text: map-merge(
-  $utilities-colors,
-  (
-    "black": to-rgb($black),
-    "white": to-rgb($white),
-    "body": to-rgb($body-color)
-  )
-) !default;
-$utilities-text-colors: map-loop($utilities-text, rgba-css-var, "$key", "text") !default;
-// scss-docs-end utilities-text-colors
-
-// scss-docs-start utilities-bg-colors
-$utilities-bg: map-merge(
-  $utilities-colors,
-  (
-    "black": to-rgb($black),
-    "white": to-rgb($white),
-    "body": to-rgb($body-bg)
-  )
-) !default;
-$utilities-bg-colors: map-loop($utilities-bg, rgba-css-var, "$key", "bg") !default;
-// scss-docs-end utilities-bg-colors
-
 // Links
 //
 // Style anchor elements.
@@ -504,8 +465,6 @@ $grid-columns:                12 !default;
 $grid-gutter-width:           1.5rem !default;
 $grid-row-columns:            6 !default;
 
-$gutters: $spacers !default;
-
 // Container padding
 
 $container-padding-x: $grid-gutter-width * .5 !default;

scss/bootstrap-grid.scss

@@ -9,6 +9,7 @@ $include-column-box-sizing: true !default;
 
 @import "functions";
 @import "variables";
+@import "maps";
 
 @import "mixins/lists";
 @import "mixins/breakpoints";

scss/bootstrap-reboot.scss

@@ -8,6 +8,7 @@
 
 @import "functions";
 @import "variables";
+@import "maps";
 @import "mixins";
 @import "root";
 @import "reboot";

scss/bootstrap-utilities.scss

@@ -8,6 +8,7 @@
 // Configuration
 @import "functions";
 @import "variables";
+@import "maps";
 @import "mixins";
 @import "utilities";
 

scss/bootstrap.scss

@@ -9,6 +9,7 @@
 // Configuration
 @import "functions";
 @import "variables";
+@import "maps";
 @import "mixins";
 @import "utilities";
 

site/content/docs/5.1/customize/sass.md

@@ -59,10 +59,15 @@ In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two
 
 // 3. Include remainder of required Bootstrap stylesheets
 @import "../node_modules/bootstrap/scss/variables";
+
+// 4. Include any default map overrides here
+
+// 5. Include remainder of required parts
+@import "../node_modules/bootstrap/scss/maps";
 @import "../node_modules/bootstrap/scss/mixins";
 @import "../node_modules/bootstrap/scss/root";
 
-// 4. Include any optional Bootstrap CSS as needed
+// 6. Optionally include any other parts as needed
 @import "../node_modules/bootstrap/scss/utilities";
 @import "../node_modules/bootstrap/scss/reboot";
 @import "../node_modules/bootstrap/scss/type";
@@ -71,10 +76,10 @@ In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two
 @import "../node_modules/bootstrap/scss/grid";
 @import "../node_modules/bootstrap/scss/helpers";
 
-// 5. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
+// 7. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
 @import "../node_modules/bootstrap/scss/utilities/api";
 
-// 6. Add additional custom code here
+// 8. Add additional custom code here
 ```
 
 With that setup in place, you can begin to modify any of the Sass variables and maps in your `custom.scss`. You can also start to add parts of Bootstrap under the `// Optional` section as needed. We suggest using the full import stack from our `bootstrap.scss` file as your starting point.

site/content/docs/5.1/migration.md

@@ -9,6 +9,52 @@ toc: true
 
 ## v5.2.0
 
+### New `_maps.scss`
+
+Bootstrap v5.2.0 introduced a new Sass file, `_maps.scss`, that pulled out several Sass maps from `_variables.scss` to fix an issue where updates to an original map were not applied to secondary maps that extend them. For example, updates to `$theme-colors` were not being applied to other theme maps that relied on `$theme-colors`, breaking key customization workflows. In short, Sass has a limitation where once a default variable or map has been _used_, it cannot be updated.
+
+This is why variable customizations in Bootstrap have to come after `@import "functions"`, but before `@import "variables"` and the rest of our import stack. The same applies to Sass maps—you must override the defaults before the defaults get used. The following maps have been moved to the new `_maps.scss`:
+
+- `$theme-colors-rgb`
+- `$utilities-colors`
+- `$utilities-text`
+- `$utilities-text-colors`
+- `$utilities-bg`
+- `$utilities-bg-colors`
+- `$negative-spacers`
+- `$gutters`
+
+Your custom Bootstrap CSS builds should now look something like this with a separate maps import.
+
+```diff
+  // Functions come first
+  @import "functions";
+
+  // Optional variable overrides here
++ $custom-color: #df711b;
++ $custom-theme-colors: (
++   "custom": $custom-color
++ );
+
+  // Variables come next
+  @import "variables";
+
++ // Optional Sass map overrides here
++ $theme-colors: map-merge($theme-colors, $custom-theme-colors);
++
++ // Followed by our default maps
++ @import "maps";
++
+  // Rest of our imports
+  @import "mixins";
+  @import "utilities";
+  @import "root";
+  @import "reboot";
+  // etc
+```
+
+### Key changes
+
 - **Introduced new `$enable-container-classes` option.** Now when opting into the experimental CSS Grid layout, `.container-*` classes will still be compiled, unless this option is set to `false`.
 
 ## Dependencies

site/content/docs/5.1/utilities/background.md

@@ -103,11 +103,11 @@ Grayscale colors are also available as a Sass map. **This map is not used to gen
 
 RGB colors are generated from a separate Sass map:
 
-{{< scss-docs name="theme-colors-rgb" file="scss/_variables.scss" >}}
+{{< scss-docs name="theme-colors-rgb" file="scss/_maps.scss" >}}
 
 And background color opacities build on that with their own map that's consumed by the utilities API:
 
-{{< scss-docs name="utilities-bg-colors" file="scss/_variables.scss" >}}
+{{< scss-docs name="utilities-bg-colors" file="scss/_maps.scss" >}}
 
 ### Mixins
 

site/content/docs/5.1/utilities/colors.md

@@ -100,11 +100,11 @@ Grayscale colors are also available as a Sass map. **This map is not used to gen
 
 RGB colors are generated from a separate Sass map:
 
-{{< scss-docs name="theme-colors-rgb" file="scss/_variables.scss" >}}
+{{< scss-docs name="theme-colors-rgb" file="scss/_maps.scss" >}}
 
 And color opacities build on that with their own map that's consumed by the utilities API:
 
-{{< scss-docs name="utilities-text-colors" file="scss/_variables.scss" >}}
+{{< scss-docs name="utilities-text-colors" file="scss/_maps.scss" >}}
 
 ### Utilities API