From 88be1ce5021229ba9615413fceaed1902c8d693e Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Sun, 17 Jan 2021 00:06:19 +0200
Subject: Update docs for color and bg utilities

- Split colors from background utilities with new docs page
- Add Sass docs for both pages
---
 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 +-
 site/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 +
 9 files changed, 127 insertions(+), 39 deletions(-)
 create mode 100644 site/content/docs/5.0/utilities/background.md

(limited to 'site')

diff --git a/site/content/docs/5.0/components/card.md b/site/content/docs/5.0/components/card.md
index e38432692..2db1a1f40 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 3591b343c..b9b00c3bb 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 eb879b650..5f7a59db6 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 452b3d77c..7d1615589 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 ffaf7cdba..e940196ff 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 000000000..7b1b48140
--- /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 3f11cb2b5..266f671f6 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 bcf001d40..9e5a5dfb2 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 a4d4ccbbd..4d7c9ff84 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
-- 
cgit v1.2.3