diff --git a/site/content/docs/5.1/customize/sass.md b/site/content/docs/5.1/customize/sass.md
index f580460606..2c21302eb9 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 Boosted's source Sass files. You have two o
// 3. Include remainder of required Boosted stylesheets
@import "../node_modules/boosted/scss/variables";
+
+// 4. Include any default map overrides here
+
+// 5. Include remainder of required parts
+@import "../node_modules/boosted/scss/maps";
@import "../node_modules/boosted/scss/mixins";
@import "../node_modules/boosted/scss/root";
-// 4. Include any optional Boosted CSS as needed
+// 6. Optionally include any other parts as needed
@import "../node_modules/boosted/scss/utilities";
@import "../node_modules/boosted/scss/reboot";
@import "../node_modules/boosted/scss/type";
@@ -71,10 +76,10 @@ In your `custom.scss`, you'll import Boosted's source Sass files. You have two o
@import "../node_modules/boosted/scss/grid";
@import "../node_modules/boosted/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/boosted/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 Boosted under the `// Optional` section as needed. We suggest using the full import stack from our `boosted.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 a677a60164..c4cc98fb04 100644
--- a/site/content/docs/5.1/migration.md
+++ b/site/content/docs/5.1/migration.md
@@ -15,6 +15,51 @@ We only replaced `Bootstrap` with `Boosted`—especially in code examples and fi
## v5.2.0
+### New `_maps.scss`
+
+Boosted 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 Boosted 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`
+- `$background-colors`
+- `$utilities-colors`
+- `$utilities-text`
+- `$utilities-text-colors`
+- `$utilities-bg`
+- `$utilities-bg-colors`
+- `$negative-spacers`
+- `$gutters`
+- `$alert-colors`
+
+Your custom Boosted 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 a717da545c..73d17bfb44 100644
--- a/site/content/docs/5.1/utilities/background.md
+++ b/site/content/docs/5.1/utilities/background.md
@@ -104,6 +104,14 @@ Grayscale colors are also available as a Sass map. **This map is not used to gen
{{< scss-docs name="gray-colors-map" file="scss/_variables.scss" >}}
+RGB colors are generated from a separate Sass map:
+
+{{< 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/_maps.scss" >}}
+
### Mixins
**No mixins are used to generate our background utilities**, but we do have some additional mixins for other situations where you'd like to create your own gradients.
diff --git a/site/content/docs/5.1/utilities/colors.md b/site/content/docs/5.1/utilities/colors.md
index d593f89916..78938d1490 100644
--- a/site/content/docs/5.1/utilities/colors.md
+++ b/site/content/docs/5.1/utilities/colors.md
@@ -107,11 +107,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