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
{{< /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" >}}
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") }}
+
.bg-{{ .name }}
+{{- end -}}
+{{< /colors.inline >}}
+
.bg-body
+
.bg-white
+
.bg-transparent
+{{< /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") }}
+
.bg-{{ .name }}.bg-gradient
+{{- 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 `
` 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
.text-white-50
{{< /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") }}
-
.bg-{{ .name }}
-{{- end -}}
-{{< /colors.inline >}}
-
.bg-white
-
.bg-body
-
.bg-transparent
-{{< /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 `
` 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") }}
-
.bg-{{ .name }}.bg-gradient
-{{- 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.
Print Only (Hide on screen only)
Hide up to large on screen, but always show on print
{{< /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
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 -}}