From 47bbd945f0f92f50dd2f2dbdd78d10ada39a41cb Mon Sep 17 00:00:00 2001
From: Mark Otto <markd.otto@gmail.com>
Date: Tue, 6 Jul 2021 11:31:20 -1000
Subject: Add maps for all colors, document how to extend color utilities
 (#32319)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add maps for all colors, document how to extend color utilities

* Updates to make this more functional for v5

- Moves color maps into _variables.scss for now (felt weird to split them out when the variables are there)
- Adds a new function, map-merge-multiple(), and updates docs that reference combo-map
- Updates code snippet and docs guidance about how to extend the color utils to handle this

* Update site/content/docs/5.0/customize/color.md

Co-authored-by: Gaël Poupard <ffoodd@users.noreply.github.com>
Co-authored-by: XhmikosR <xhmikosr@gmail.com>
---
 site/content/docs/5.0/customize/color.md | 42 ++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'site/content/docs')

diff --git a/site/content/docs/5.0/customize/color.md b/site/content/docs/5.0/customize/color.md
index 7d1615589..63e5d19e6 100644
--- a/site/content/docs/5.0/customize/color.md
+++ b/site/content/docs/5.0/customize/color.md
@@ -106,3 +106,45 @@ Here's how you can use these in your Sass:
 ```
 
 [Color]({{< docsref "/utilities/colors" >}}) and [background]({{< docsref "/utilities/background" >}}) utility classes are also available for setting `color` and `background-color` using the `500` color values.
+
+## Generating utilities
+
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.1.0</small>
+
+Bootstrap doesn't include `color` and `background-color` utilities for every color variable, but you can generate these yourself with our [utility API]({{< docsref "/utilities/api" >}}) and our extended Sass maps added in v5.1.0.
+
+1. To start, make sure you've imported our functions, variables, mixins, and utilities.
+2. Use our `map-merge-multiple()` function to quickly merge multiple Sass maps together in a new map.
+3. Merge this new combined map to extend any utility with a `{color}-{level}` class name.
+
+Here's an example that generates text color utilities (e.g., `.text-purple-500`) using the above steps.
+
+```scss
+@import "bootstrap/scss/functions";
+@import "bootstrap/scss/variables";
+@import "bootstrap/scss/mixins";
+@import "bootstrap/scss/utilities";
+
+$all-colors: map-merge-multiple($blues, $indigos, $purples, $pinks, $reds, $oranges, $yellows, $greens, $teals, $cyans);
+
+$utilities: map-merge(
+  $utilities,
+  (
+    "color": map-merge(
+      map-get($utilities, "color"),
+      (
+        values: map-merge(
+          map-get(map-get($utilities, "color"), "values"),
+          (
+            $all-colors
+          ),
+        ),
+      ),
+    ),
+  )
+);
+
+@import "bootstrap/scss/utilities/api";
+```
+
+This will generate new `.text-{color}-{level}` utilities for every color and level. You can do the same for any other utility and property as well.
-- 
cgit v1.2.3