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

4 files changed, 58 insertions, 7 deletions

diff --git a/site/content/docs/5.1/customize/sass.md b/site/content/docs/5.1/customize/sass.md
index e00d1eeae0..154ab69dc8 100644
--- a/site/content/docs/5.1/customize/sass.md
+++ b/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.
diff --git a/site/content/docs/5.1/migration.md b/site/content/docs/5.1/migration.md
index 10d4a44212..522e8551b6 100644
--- a/site/content/docs/5.1/migration.md
+++ b/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
diff --git a/site/content/docs/5.1/utilities/background.md b/site/content/docs/5.1/utilities/background.md
index 61c27365b1..b6f7a8bdff 100644
--- a/site/content/docs/5.1/utilities/background.md
+++ b/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
 
diff --git a/site/content/docs/5.1/utilities/colors.md b/site/content/docs/5.1/utilities/colors.md
index 60462070b4..95752ed64c 100644
--- a/site/content/docs/5.1/utilities/colors.md
+++ b/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