Merge branch 'main' into new-border-bg-utils

- bg-gray is new and maps to gray-400
- border-gray-500 and border-gray-700 are new and are meant to complement bg-gray and bg-secondary as one level off from the borders

scss/_utilities.scss

@@ -110,7 +110,15 @@ $utilities: map-merge(
     "border-color": (
       property: border-color,
       class: border,
-      values: map-merge($theme-colors, ("white": $white))
+      values: map-merge(
+        $theme-colors,
+        (
+          "white": $white,
+          "gray-500": $gray-500,
+          "gray-700": $gray-700,
+          "black": $black
+        )
+      )
     ),
     "border-width": (
       property: border-width,
@@ -473,6 +481,8 @@ $utilities: map-merge(
         (
           "body": $body-bg,
           "white": $white,
+          "gray": $gray-400,
+          "black": black,
           "transparent": transparent
         )
       )

site/content/docs/5.0/utilities/borders.md

@@ -32,7 +32,7 @@ Use border utilities to add or remove an element's borders. Choose from all bord
 
 ## Border color
 
-Change the border color using utilities built on our theme colors.
+Change the border color using utilities built on our theme colors. We've also included a subset of our gray colors to provide more flexibility.
 
 {{< example class="bd-example-border-utils" >}}
 {{< border.inline >}}
@@ -41,6 +41,18 @@ Change the border color using utilities built on our theme colors.
 {{- end -}}
 {{< /border.inline >}}
 <span class="border border-white"></span>
+<span class="border border-gray-500"></span>
+<span class="border border-gray-700"></span>
+<span class="border border-black"></span>
+{{< /example >}}
+
+The gray `border-color` utilities differ slightly than our `background-color` utilities so that there's some slight contrast between the two.
+
+{{< example >}}
+<div class="p-3 mb-1 bg-light border"></div>
+<div class="p-3 mb-1 bg-gray border border-gray-500"></div>
+<div class="p-3 mb-1 bg-secondary border border-gray-700"></div>
+<div class="p-3 mb-1 bg-dark border border-black"></div>
 {{< /example >}}
 
 ## Border-width

site/content/docs/5.0/utilities/colors.md

@@ -43,7 +43,9 @@ Similar to the contextual text color classes, easily set the background of an el
 <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-gray text-dark">.bg-gray</div>
 <div class="p-3 mb-2 bg-white text-dark">.bg-white</div>
+<div class="p-3 mb-2 bg-black text-white">.bg-black</div>
 <div class="p-3 mb-2 bg-transparent text-dark">.bg-transparent</div>
 {{< /example >}}