Dark mode: Docs about background utility (#2411)

Co-authored-by: Julien Déramond <[email protected]>

site/content/docs/5.3/utilities/background.md

@@ -1,7 +1,7 @@
 ---
 layout: docs
 title: Background
-description: Convey meaning through `background-color` and add decoration with gradients.
+description: Convey meaning through `background-color`.
 group: utilities
 aliases:
   - "/docs/utilities/background/"
@@ -14,57 +14,57 @@ toc: true
 
 ## Background color
 
-Similar to the contextual text color classes, set the background of an element to any contextual class. Background utilities **do set `color`** to ensure contrasts.
+Background utilities like `.bg-*` are generated from our original `$theme-colors` Sass map and respond to color modes.
 
-{{< callout info >}}
-Background utilities like `.bg-*` that generated from our original `$theme-colors` Sass map don't yet respond to color modes, however, any `.bg-*-subtle` utility will. This will be resolved in v6.
-{{< /callout >}}
+Similar to the contextual text color classes, set the background of an element to any contextual class. Background utilities **do not set `color`**, so depending on the cases you'll want to use:
+* `.text-*` [color utilities]({{< docsref "/utilities/colors" >}}) when the background color remains the same in light and dark mode
+* `.text-bg-*` [color & background helper]({{< docsref "/helpers/color-background" >}}) from our [theme colors]({{< docsref "/customize/color-theme#theming" >}})
+* `[data-bs-theme]` [color mode attribute]({{< docsref "/customize/color-modes#example" >}}) when the element using a background utility contains complex sub-elements such as components that need to respond to color modes
 
-{{< callout info >}}
-In case you need to write over one of these background, prefer using our [color & background helper]({{< docsref "/helpers/color-background" >}}) when it exists.
-{{< /callout >}}
+{{< example >}}
+{{< colors.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<div class="p-3 mb-2 fw-bold bg-{{ .name }}"><span class="text-bg-{{ .name }}">.bg-{{ .name }}</span></div>
+{{- end -}}
+{{< /colors.inline >}}
+<div class="p-3 mb-2 fw-bold bg-body-secondary">.bg-body-secondary</div>
+<div class="p-3 mb-2 fw-bold bg-body">.bg-body</div>
+<div class="p-3 mb-2 fw-bold bg-black text-white">.bg-black</div>
+<div class="p-3 mb-2 fw-bold bg-white text-black">.bg-white</div>
+<div class="p-3 mb-2 fw-bold bg-transparent">.bg-transparent</div>
+{{< /example >}}
+
+Supporting background utilities are generated from our [supporting colors]({{< docsref "/customize/color-theme#supporting" >}}). Please note that their color value stays the same between light and dark mode.
 
-<!-- Boosted mod: inconsistent background color & naming, showing only supporting color naming -->
 {{< example >}}
-<div class="p-3 mb-2 fw-bold bg-primary"><span class="text-bg-primary">.bg-primary</span></div>
-<div class="p-3 mb-2 fw-bold bg-secondary"><span class="text-bg-secondary">.bg-secondary</span></div>
-<div class="p-3 mb-2 fw-bold bg-success"><span class="text-bg-success">.bg-success</span></div>
-<div class="p-3 mb-2 fw-bold bg-danger"><span class="text-bg-danger">.bg-danger</span></div>
-<div class="p-3 mb-2 fw-bold bg-warning"><span class="text-bg-warning">.bg-warning</span></div>
-<div class="p-3 mb-2 fw-bold bg-info"><span class="text-bg-info">.bg-info</span></div>
 <div class="p-3 mb-2 fw-bold bg-supporting-green text-black">.bg-supporting-green</div>
 <div class="p-3 mb-2 fw-bold bg-supporting-purple text-black">.bg-supporting-purple</div>
 <div class="p-3 mb-2 fw-bold bg-supporting-yellow text-black">.bg-supporting-yellow</div>
 <div class="p-3 mb-2 fw-bold bg-supporting-blue text-black">.bg-supporting-blue</div>
 <div class="p-3 mb-2 fw-bold bg-supporting-pink text-black">.bg-supporting-pink</div>
 <div class="p-3 mb-2 fw-bold bg-supporting-orange text-black">.bg-supporting-orange</div>
-<div class="p-3 mb-2 fw-bold bg-light"><span class="text-bg-light">.bg-light</span></div>
-<div class="p-3 mb-2 fw-bold bg-dark"><span class="text-bg-dark">.bg-dark</span></div>
-<div class="p-3 mb-2 fw-bold bg-body-secondary">.bg-body-secondary</div>
-<div class="p-3 mb-2 fw-bold bg-body-tertiary">.bg-body-tertiary</div>
-<div class="p-3 mb-2 fw-bold bg-body">.bg-body</div>
-<div class="p-3 mb-2 fw-bold bg-black text-white">.bg-black</div>
-<div class="p-3 mb-2 fw-bold bg-white text-black">.bg-white</div>
-<div class="p-3 mb-2 fw-bold bg-transparent">.bg-transparent</div>
 {{< /example >}}
 
-{{< callout info >}}
-For each `.background-*` there is a matching `.background-*-subtle` utility. In Boosted, they have exactly the same value so we decided not to display them in the example above so that you don't hesitate on which class to use.
+<details>
+  <summary>See list of Bootstrap-specific background color utilities</summary>
+  <br>
 
-Here is a list of these extra classes:
-{{< background-subtle.inline >}}
-{{- range (index $.Site.Data "theme-colors") }}
-- `.bg-{{ .name }}-subtle`
-{{- end -}}
-{{< /background-subtle.inline >}}
-{{< /callout >}}
+Another background utility is `.bg-body-tertiary` but doesn't have any matching color in our [grays colors]({{< docsref "/customize/color-theme#grays" >}}) so shouldn't be used for now.
 
-{{< callout >}}
-### Color naming
+{{< example >}}
+<p class="p-3 mb-2 fw-bold bg-body-tertiary">.bg-body-tertiary</p>
+{{< /example >}}
 
-Since [Orange brand distinguishes functional colors from supporting colors]({{< docsref "/customize/color-theme#theming" >}}) and Bootstrap doesn't, naming can be somewhat inconsistent.
-Bootstrap's `background-color` utilities are supported in Boosted, but will result in our core `.bg-supporting-*` utilities—making `.bg-danger` inconsistent with `.btn-danger` color, for example.
-{{< /callout >}}
+In Bootstrap, for each `.bg-*` there is a matching `.bg-*-subtle` utility responding to color modes. In Boosted, subtle colors don't exist so these background utilities have exactly the same value and shouldn't be used. Prefer the regular `.bg-*` utilities instead.
+
+{{< example >}}
+{{< colors.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<div class="p-3 mb-2 fw-bold bg-{{ .name }}-subtle"><span class="text-bg-{{ .name }}">.bg-{{ .name }}-subtle</span></div>
+{{- end -}}
+{{< /colors.inline >}}
+{{< /example >}}
+</details>
 
 <!-- Boosted mod: no background gradient -->