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

diff --git a/scss/_maps.scss b/scss/_maps.scss
new file mode 100644 (file)
index 0000000..c8b9fa7
--- /dev/null
+++ b/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;

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 244a15c215f1d545b21a137e7fcd12ddb2d8cd47..f6a37b764c1ed6eb65b681e92bf4f2b38863aabc 100644 (file)
--- a/scss/_variables.scss
+++ b/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;

diff --git a/scss/bootstrap-grid.scss b/scss/bootstrap-grid.scss
index d4a37a063e848dbde72e2f32a514049cffd80125..edca104af8ae99865b14d1d7645eff15803ccd54 100644 (file)
--- a/scss/bootstrap-grid.scss
+++ b/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";

diff --git a/scss/bootstrap-reboot.scss b/scss/bootstrap-reboot.scss
index 965332a6065674855cdd0b46f54e7cb94c441189..726758e9286ddb787692514194595a03b0f685ff 100644 (file)
--- a/scss/bootstrap-reboot.scss
+++ b/scss/bootstrap-reboot.scss
@@ -8,6 +8,7 @@
 
 @import "functions";
 @import "variables";
+@import "maps";
 @import "mixins";
 @import "root";
 @import "reboot";

diff --git a/scss/bootstrap-utilities.scss b/scss/bootstrap-utilities.scss
index d4f981d450e6a9fea8980f2b3713d5787222c7b4..6d7968e686c3b276065c7bd6f791f20db821ba89 100644 (file)
--- a/scss/bootstrap-utilities.scss
+++ b/scss/bootstrap-utilities.scss
@@ -8,6 +8,7 @@
 // Configuration
 @import "functions";
 @import "variables";
+@import "maps";
 @import "mixins";
 @import "utilities";
 

diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss
index 0819eee3c7405b1beb4abe473f06180a32fd7baa..6a5d131667a3dfc06fc96fe86cfc32561f7281f8 100644 (file)
--- a/scss/bootstrap.scss
+++ b/scss/bootstrap.scss
@@ -9,6 +9,7 @@
 // Configuration
 @import "functions";
 @import "variables";
+@import "maps";
 @import "mixins";
 @import "utilities";
 

diff --git a/site/content/docs/5.1/customize/sass.md b/site/content/docs/5.1/customize/sass.md
index e00d1eeae05820e171e2cb00aabbad799795ba58..154ab69dc89e2171bd9e7b8f3a8765253d672cb5 100644 (file)
--- 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 10d4a44212160b0ea022c78a8e9a5e38b7701380..522e8551b671d5091877fdcee515ee207491bbd3 100644 (file)
--- 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 61c27365b1f1920cb00a5ea14d348ad94a7d6acb..b6f7a8bdff4c8ce3fcfc1e904efdcd29abf5b964 100644 (file)
--- 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 60462070b4d3acb8f593309c34b7f5bab0c48ab3..95752ed64c7b5f4cdef34391c5598b71e994526f 100644 (file)
--- 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