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

@@ -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,

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
 //

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

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 >}}

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
 

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">

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.

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 >}}

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" >}}

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" >}}

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" >}}

site/data/sidebar.yml

@@ -92,6 +92,7 @@
 - title: Utilities
   pages:
     - title: API
+    - title: Background
     - title: Borders
     - title: Colors
     - title: Display