Docs: new section to explain how to add a new color to the theme (#37737)

* Docs: new section to explain how to add a new color to the theme

* Commit to revert

* Edit copy

* Typo

* bundlewatch

* Restore blog example

* Remove Sass modifications

* Complete documentation

* Revert bootstrap.scss modifications

---------

Co-authored-by: Mark Otto <[email protected]>

1 files changed, 48 insertions, 0 deletions

diff --git a/site/content/docs/5.3/customize/color-modes.md b/site/content/docs/5.3/customize/color-modes.md
index 5c7ccf862..945d5ec33 100644
--- a/site/content/docs/5.3/customize/color-modes.md
+++ b/site/content/docs/5.3/customize/color-modes.md
@@ -189,6 +189,54 @@ Here's a look at the JavaScript that powers it. Feel free to inspect our own doc
 {{< /js.inline >}}
 {{< /example >}}
 
+## 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