From 23cdd9d862f29eb43bec86df4b492908806ad396 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sun, 17 Jan 2021 00:06:19 +0200
Subject: [PATCH 1/2] Update docs for color and bg utilities

- Split colors from background utilities with new docs page
- Add Sass docs for both pages
---
 scss/_utilities.scss                          |  6 ++
 scss/_variables.scss                          | 10 +++
 scss/mixins/_gradients.scss                   |  4 +
 site/content/docs/5.0/components/card.md      |  2 +-
 site/content/docs/5.0/components/navbar.md    |  2 +-
 site/content/docs/5.0/components/toasts.md    |  2 +-
 site/content/docs/5.0/customize/color.md      |  2 +-
 .../content/docs/5.0/helpers/colored-links.md |  2 +-
 site/content/docs/5.0/utilities/background.md | 78 +++++++++++++++++++
 site/content/docs/5.0/utilities/colors.md     | 69 ++++++++--------
 site/content/docs/5.0/utilities/display.md    |  8 ++
 site/data/sidebar.yml                         |  1 +
 12 files changed, 147 insertions(+), 39 deletions(-)
 create mode 100644 site/content/docs/5.0/utilities/background.md

diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 89bf16847b17..82f3db114995 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -22,6 +22,7 @@ $utilities: map-merge(
       property: overflow,
       values: auto hidden visible scroll,
     ),
+    // scss-docs-start utils-display
     "display": (
       responsive: true,
       print: true,
@@ -29,6 +30,7 @@ $utilities: map-merge(
       class: d,
       values: inline inline-block block grid table table-row table-cell flex inline-flex none
     ),
+    // scss-docs-end utils-display
     "shadow": (
       property: box-shadow,
       class: shadow,
@@ -440,6 +442,7 @@ $utilities: map-merge(
         center: center,
       )
     ),
+    // scss-docs-start utils-color
     "color": (
       property: color,
       class: text,
@@ -455,6 +458,7 @@ $utilities: map-merge(
         )
       )
     ),
+    // scss-docs-end utils-color
     "line-height": (
       property: line-height,
       class: lh,
@@ -465,6 +469,7 @@ $utilities: map-merge(
         lg: $line-height-lg,
       )
     ),
+    // scss-docs-start utils-bg-color
     "background-color": (
       property: background-color,
       class: bg,
@@ -477,6 +482,7 @@ $utilities: map-merge(
         )
       )
     ),
+    // scss-docs-end utils-bg-color
     "gradient": (
       property: background-image,
       class: bg,
diff --git a/scss/_variables.scss b/scss/_variables.scss
index 3ad989a4196c..3f8014497825 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -5,6 +5,7 @@
 
 // Color system
 
+// scss-docs-start gray-color-variables
 $white:    #fff !default;
 $gray-100: #f8f9fa !default;
 $gray-200: #e9ecef !default;
@@ -16,8 +17,10 @@ $gray-700: #495057 !default;
 $gray-800: #343a40 !default;
 $gray-900: #212529 !default;
 $black:    #000 !default;
+// scss-docs-end gray-color-variables
 
 // fusv-disable
+// scss-docs-start gray-colors-map
 $grays: (
   "100": $gray-100,
   "200": $gray-200,
@@ -29,8 +32,10 @@ $grays: (
   "800": $gray-800,
   "900": $gray-900
 ) !default;
+// scss-docs-end gray-colors-map
 // fusv-enable
 
+// scss-docs-start color-variables
 $blue:    #0d6efd !default;
 $indigo:  #6610f2 !default;
 $purple:  #6f42c1 !default;
@@ -41,6 +46,7 @@ $yellow:  #ffc107 !default;
 $green:   #198754 !default;
 $teal:    #20c997 !default;
 $cyan:    #0dcaf0 !default;
+// scss-docs-end color-variables
 
 // scss-docs-start colors-map
 $colors: (
@@ -60,6 +66,7 @@ $colors: (
 ) !default;
 // scss-docs-end colors-map
 
+// scss-docs-start theme-color-variables
 $primary:       $blue !default;
 $secondary:     $gray-600 !default;
 $success:       $green !default;
@@ -68,6 +75,7 @@ $warning:       $yellow !default;
 $danger:        $red !default;
 $light:         $gray-100 !default;
 $dark:          $gray-900 !default;
+// scss-docs-end theme-color-variables
 
 // scss-docs-start theme-colors-map
 $theme-colors: (
@@ -228,7 +236,9 @@ $variable-prefix:             bs- !default;
 //
 // The gradient which is added to components if `$enable-gradients` is `true`
 // This gradient is also added to elements with `.bg-gradient`
+// scss-docs-start variable-gradient
 $gradient: linear-gradient(180deg, rgba($white, .15), rgba($white, 0)) !default;
+// scss-docs-end variable-gradient
 
 // Spacing
 //
diff --git a/scss/mixins/_gradients.scss b/scss/mixins/_gradients.scss
index ec38ca1417ff..44167d1b8b29 100644
--- a/scss/mixins/_gradients.scss
+++ b/scss/mixins/_gradients.scss
@@ -1,5 +1,6 @@
 // Gradients
 
+// scss-docs-start gradient-bg-mixin
 @mixin gradient-bg($color: null) {
   background-color: $color;
 
@@ -7,7 +8,9 @@
     background-image: var(--#{$variable-prefix}gradient);
   }
 }
+// scss-docs-end gradient-bg-mixin
 
+// scss-docs-start gradient-mixins
 // Horizontal gradient, from left to right
 //
 // Creates two color stops, start and end, by specifying a color and position for each color stop.
@@ -41,3 +44,4 @@
 @mixin gradient-striped($color: rgba($white, .15), $angle: 45deg) {
   background-image: linear-gradient($angle, $color 25%, transparent 25%, transparent 50%, $color 50%, $color 75%, transparent 75%, transparent);
 }
+// scss-docs-end gradient-mixins
diff --git a/site/content/docs/5.0/components/card.md b/site/content/docs/5.0/components/card.md
index e384326928ac..2db1a1f40d23 100644
--- a/site/content/docs/5.0/components/card.md
+++ b/site/content/docs/5.0/components/card.md
@@ -417,7 +417,7 @@ Cards include various options for customizing their backgrounds, borders, and co
 
 ### Background and color
 
-Use [text and background utilities]({{< docsref "/utilities/colors" >}}) to change the appearance of a card.
+Use [text color]({{< docsref "/utilities/colors" >}}) and [background utilities]({{< docsref "/utilities/background" >}}) to change the appearance of a card.
 
 {{< example >}}
 {{< card.inline >}}
diff --git a/site/content/docs/5.0/components/navbar.md b/site/content/docs/5.0/components/navbar.md
index 3591b343cd71..b9b00c3bb193 100644
--- a/site/content/docs/5.0/components/navbar.md
+++ b/site/content/docs/5.0/components/navbar.md
@@ -74,7 +74,7 @@ Here's an example of all the sub-components included in a responsive light-theme
 </nav>
 {{< /example >}}
 
-This example uses [color]({{< docsref "/utilities/colors" >}}) (`bg-light`) and [spacing]({{< docsref "/utilities/spacing" >}}) (`my-2`, `my-lg-0`, `me-sm-0`, `my-sm-0`) utility classes.
+This example uses [background]({{< docsref "/utilities/background" >}}) (`bg-light`) and [spacing]({{< docsref "/utilities/spacing" >}}) (`my-2`, `my-lg-0`, `me-sm-0`, `my-sm-0`) utility classes.
 
 ### Brand
 
diff --git a/site/content/docs/5.0/components/toasts.md b/site/content/docs/5.0/components/toasts.md
index eb879b650036..5f7a59db6e8e 100644
--- a/site/content/docs/5.0/components/toasts.md
+++ b/site/content/docs/5.0/components/toasts.md
@@ -162,7 +162,7 @@ Alternatively, you can also add additional controls and components to toasts.
 
 ### Color schemes
 
-Building on the above example, you can create different toast color schemes with our [color utilities]({{< docsref "/utilities/colors" >}}). Here we've added `.bg-primary` and `.text-white` to the `.toast`, and then added `.btn-close-white` to our close button. For a crisp edge, we remove the default border with `.border-0`.
+Building on the above example, you can create different toast color schemes with our [color]({{< docsref "/utilities/colors" >}}) and [background]({{< docsref "/utilities/background" >}}). Here we've added `.bg-primary` and `.text-white` to the `.toast`, and then added `.btn-close-white` to our close button. For a crisp edge, we remove the default border with `.border-0`.
 
 {{< example class="bg-light" >}}
 <div class="toast align-items-center text-white bg-primary border-0" role="alert" aria-live="assertive" aria-atomic="true">
diff --git a/site/content/docs/5.0/customize/color.md b/site/content/docs/5.0/customize/color.md
index 452b3d77cfb2..7d1615589b61 100644
--- a/site/content/docs/5.0/customize/color.md
+++ b/site/content/docs/5.0/customize/color.md
@@ -105,4 +105,4 @@ Here's how you can use these in your Sass:
 }
 ```
 
-[Color utility classes]({{< docsref "/utilities/colors" >}}) are also available for setting `color` and `background-color` using the `500` color values.
+[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.
diff --git a/site/content/docs/5.0/helpers/colored-links.md b/site/content/docs/5.0/helpers/colored-links.md
index ffaf7cdba45b..e940196ff85a 100644
--- a/site/content/docs/5.0/helpers/colored-links.md
+++ b/site/content/docs/5.0/helpers/colored-links.md
@@ -6,7 +6,7 @@ group: helpers
 toc: false
 ---
 
-You can use the `.link-*` classes to colorize links. Unlike the [`.text-*` classes]({{< docsref "/utilities/colors#colors" >}}), these classes have a `:hover` and `:focus` state.
+You can use the `.link-*` classes to colorize links. Unlike the [`.text-*` classes]({{< docsref "/utilities/colors" >}}), these classes have a `:hover` and `:focus` state.
 
 {{< example >}}
 {{< colored-links.inline >}}
diff --git a/site/content/docs/5.0/utilities/background.md b/site/content/docs/5.0/utilities/background.md
new file mode 100644
index 000000000000..7b1b481401f4
--- /dev/null
+++ b/site/content/docs/5.0/utilities/background.md
@@ -0,0 +1,78 @@
+---
+layout: docs
+title: Background
+description: Convey meaning through `background-color` and add decoration with gradients.
+group: utilities
+toc: true
+---
+
+## Background color
+
+Similar to the contextual text color classes, set the background of an element to any contextual class. Background utilities **do not set `color`**, so in some cases you'll want to use `.text-*` [color utilities]({{< docsref "/utilities/colors" >}}).
+
+{{< example >}}
+{{< colors.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<div class="p-3 mb-2 bg-{{ .name }}{{ if .contrast_color }} text-{{ .contrast_color }}{{ else }} text-white{{ end }}">.bg-{{ .name }}</div>
+{{- end -}}
+{{< /colors.inline >}}
+<div class="p-3 mb-2 bg-body text-dark">.bg-body</div>
+<div class="p-3 mb-2 bg-white text-dark">.bg-white</div>
+<div class="p-3 mb-2 bg-transparent text-dark">.bg-transparent</div>
+{{< /example >}}
+
+## Background gradient
+
+By adding a `.bg-gradient` class, a linear gradient is added as background image to the backgrounds. This gradient starts with a semi-transparent white which fades out to the bottom.
+
+Do you need a gradient in your custom CSS? Just add `background-image: var(--bs-gradient);`.
+
+{{< markdown >}}
+{{< colors.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<div class="p-3 mb-2 bg-{{ .name }} bg-gradient{{ with .contrast_color }} text-{{ . }}{{ else }} text-white{{ end }}">.bg-{{ .name }}.bg-gradient</div>
+{{- end -}}
+{{< /colors.inline >}}
+{{< /markdown >}}
+
+## Sass
+
+In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more.
+
+### Variables
+
+Most `background-color` utilities are generated by our theme colors, reassigned from our generic color palette variables.
+
+{{< scss-docs name="color-variables" file="scss/_variables.scss" >}}
+
+{{< scss-docs name="theme-color-variables" file="scss/_variables.scss" >}}
+
+{{< scss-docs name="variable-gradient" file="scss/_variables.scss" >}}
+
+Grayscale colors are also available, but only a subset are used to generate any utilities.
+
+{{< scss-docs name="gray-color-variables" file="scss/_variables.scss" >}}
+
+### Map
+
+Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more.
+
+{{< scss-docs name="theme-colors-map" file="scss/_variables.scss" >}}
+
+Grayscale colors are also available as a Sass map. **This map is not used to generate any utilities.**
+
+{{< scss-docs name="gray-colors-map" file="scss/_variables.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.
+
+{{< scss-docs name="gradient-bg-mixin" file="scss/mixins/_gradients.scss" >}}
+
+{{< scss-docs name="gradient-mixins" file="scss/mixins/_gradients.scss" >}}
+
+### Utilities API
+
+Background utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})
+
+{{< scss-docs name="utils-bg-color" file="scss/_utilities.scss" >}}
diff --git a/site/content/docs/5.0/utilities/colors.md b/site/content/docs/5.0/utilities/colors.md
index 3f11cb2b5ba3..266f671f6df6 100644
--- a/site/content/docs/5.0/utilities/colors.md
+++ b/site/content/docs/5.0/utilities/colors.md
@@ -1,22 +1,12 @@
 ---
 layout: docs
 title: Colors
-description: Convey meaning through color with a handful of color utility classes. Includes support for styling links with hover states, too.
+description: Convey meaning through `color` with a handful of color utility classes. Includes support for styling links with hover states, too.
 group: utilities
 toc: true
 ---
 
-{{< callout info >}}
-##### Dealing with specificity
-
-Sometimes contextual classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a `<div>` with the class.
-{{< /callout >}}
-
-{{< callout info >}}
-{{< partial "callout-warning-color-assistive-technologies.md" >}}
-{{< /callout >}}
-
-## Color
+## Colors
 
 Colorize text with color utilities. If you want to colorize links, you can use the [`.link-*` helper classes]({{< docsref "/helpers/colored-links" >}}) which have `:hover` and `:focus` states.
 
@@ -33,31 +23,42 @@ Colorize text with color utilities. If you want to colorize links, you can use t
 <p class="text-white-50 bg-dark">.text-white-50</p>
 {{< /example >}}
 
-## Background color
+{{< callout info >}}
+{{< partial "callout-warning-color-assistive-technologies.md" >}}
+{{< /callout >}}
 
-Similar to the contextual text color classes, easily set the background of an element to any contextual class. Background utilities **do not set `color`**, so in some cases you'll want to use `.text-*` utilities.
+## Specificity
 
-{{< example >}}
-{{< colors.inline >}}
-{{- range (index $.Site.Data "theme-colors") }}
-<div class="p-3 mb-2 bg-{{ .name }}{{ if .contrast_color }} text-{{ .contrast_color }}{{ else }} text-white{{ end }}">.bg-{{ .name }}</div>
-{{- end -}}
-{{< /colors.inline >}}
-<div class="p-3 mb-2 bg-white text-dark">.bg-white</div>
-<div class="p-3 mb-2 bg-body text-body">.bg-body</div>
-<div class="p-3 mb-2 bg-transparent text-dark">.bg-transparent</div>
-{{< /example >}}
+Sometimes contextual classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a `<div>` or more semantic element with the desired class.
 
-## Background gradient
+## Sass
 
-By adding a `.bg-gradient` class, a linear gradient is added as background image to the backgrounds. This gradient starts with a semi-transparent white which fades out to the bottom.
+In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more.
 
-Do you need a gradient in your custom CSS? Just add `background-image: var(--bs-gradient);`.
+### Variables
 
-{{< markdown >}}
-{{< colors.inline >}}
-{{- range (index $.Site.Data "theme-colors") }}
-<div class="p-3 mb-2 bg-{{ .name }} bg-gradient{{ with .contrast_color }} text-{{ . }}{{ else }} text-white{{ end }}">.bg-{{ .name }}.bg-gradient</div>
-{{- end -}}
-{{< /colors.inline >}}
-{{< /markdown >}}
+Most `color` utilities are generated by our theme colors, reassigned from our generic color palette variables.
+
+{{< scss-docs name="color-variables" file="scss/_variables.scss" >}}
+
+{{< scss-docs name="theme-color-variables" file="scss/_variables.scss" >}}
+
+Grayscale colors are also available, but only a subset are used to generate any utilities.
+
+{{< scss-docs name="gray-color-variables" file="scss/_variables.scss" >}}
+
+### Map
+
+Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more.
+
+{{< scss-docs name="theme-colors-map" file="scss/_variables.scss" >}}
+
+Grayscale colors are also available as a Sass map. **This map is not used to generate any utilities.**
+
+{{< scss-docs name="gray-colors-map" file="scss/_variables.scss" >}}
+
+### Utilities API
+
+Color utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})
+
+{{< scss-docs name="utils-color" file="scss/_utilities.scss" >}}
diff --git a/site/content/docs/5.0/utilities/display.md b/site/content/docs/5.0/utilities/display.md
index bcf001d40446..9e5a5dfb2d5b 100644
--- a/site/content/docs/5.0/utilities/display.md
+++ b/site/content/docs/5.0/utilities/display.md
@@ -150,3 +150,11 @@ The print and display classes can be combined.
 <div class="d-none d-print-block">Print Only (Hide on screen only)</div>
 <div class="d-none d-lg-block d-print-block">Hide up to large on screen, but always show on print</div>
 {{< /example >}}
+
+## Sass
+
+### Utilities API
+
+Display utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})
+
+{{< scss-docs name="utils-display" file="scss/_utilities.scss" >}}
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index a4d4ccbbd164..4d7c9ff84e4a 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -92,6 +92,7 @@
 - title: Utilities
   pages:
     - title: API
+    - title: Background
     - title: Borders
     - title: Colors
     - title: Display

From 67add99edb1bf5b0cc601a875f058f2bdc75cd74 Mon Sep 17 00:00:00 2001
From: XhmikosR <xhmikosr@gmail.com>
Date: Wed, 20 Jan 2021 12:00:57 +0200
Subject: [PATCH 2/2] Tweak scss-docs shortcode

Should work now with indented start/end capture statements
---
 site/layouts/shortcodes/scss-docs.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/layouts/shortcodes/scss-docs.html b/site/layouts/shortcodes/scss-docs.html
index 4a525e4dedf2..16a906e77709 100644
--- a/site/layouts/shortcodes/scss-docs.html
+++ b/site/layouts/shortcodes/scss-docs.html
@@ -13,7 +13,7 @@
 {{- $strip_default := .Get "strip-default" | default "true" -}}
 
 {{- $start := printf "// scss-docs-start %s\n" $name -}}
-{{- $end := printf "\n// scss-docs-end %s" $name -}}
+{{- $end := printf "// scss-docs-end %s" $name -}}
 {{- $regex := printf "%s(.|\n)*%s" $start $end -}}
 
 {{- $css := readFile $file -}}