7 files changed, 46 insertions, 161 deletions
diff --git a/site/content/docs/5.2/customize/color.md b/site/content/docs/5.2/customize/color.md
deleted file mode 100644
index 23a7f71..0000000
--- a/site/content/docs/5.2/customize/color.md
+++ /dev/null
@@ -1,151 +0,0 @@
----
-layout: docs
-title: Color
-description: Bootstrap is supported by an extensive color system that themes our styles and components. This enables more comprehensive customization and extension for any project.
-group: customize
-toc: true
----
-
-## Theme colors
-
-We use a subset of all colors to create a smaller color palette for generating color schemes, also available as Sass variables and a Sass map in Bootstrap's `scss/_variables.scss` file.
-
-<div class="row">
-  {{< theme-colors.inline >}}
-  {{- range (index $.Site.Data "theme-colors") }}
-    <div class="col-md-4">
-      <div class="p-3 mb-3 bg-{{ .name }} {{ if .contrast_color }}text-{{ .contrast_color }}{{ else }}text-white{{ end }}">{{ .name | title }}</div>
-    </div>
-  {{ end -}}
-  {{< /theme-colors.inline >}}
-</div>
-
-All these colors are available as a Sass map, `$theme-colors`.
-
-{{< scss-docs name="theme-colors-map" file="scss/_variables.scss" >}}
-
-Check out [our Sass maps and loops docs]({{< docsref "/customize/sass#maps-and-loops" >}}) for how to modify these colors.
-
-## All colors
-
-All Bootstrap colors are available as Sass variables and a Sass map in `scss/_variables.scss` file. To avoid increased file sizes, we don't create text or background color classes for each of these variables. Instead, we choose a subset of these colors for a [theme palette](#theme-colors).
-
-Be sure to monitor contrast ratios as you customize colors. As shown below, we've added three contrast ratios to each of the main colors—one for the swatch's current colors, one for against white, and one for against black.
-
-<div class="row font-monospace">
-  {{< theme-colors.inline >}}
-  {{- range $color := $.Site.Data.colors }}
-    {{- if (and (not (eq $color.name "white")) (not (eq $color.name "gray")) (not (eq $color.name "gray-dark"))) }}
-    <div class="col-md-4 mb-3">
-      <div class="p-3 mb-2 position-relative swatch-{{ $color.name }}">
-        <strong class="d-block">${{ $color.name }}</strong>
-        {{ $color.hex }}
-      </div>
-      {{ range (seq 100 100 900) }}
-      <div class="p-3 bd-{{ $color.name }}-{{ . }}">${{ $color.name }}-{{ . }}</div>
-      {{ end }}
-    </div>
-    {{ end -}}
-  {{ end -}}
-
-  <div class="col-md-4 mb-3">
-    <div class="p-3 mb-2 position-relative swatch-gray-500">
-      <strong class="d-block">$gray-500</strong>
-      #adb5bd
-    </div>
-  {{- range $.Site.Data.grays }}
-    <div class="p-3 bd-gray-{{ .name }}">$gray-{{ .name }}</div>
-  {{ end -}}
-  </div>
-  {{< /theme-colors.inline >}}
-
-  <div class="col-md-4 mb-3">
-    <div class="p-3 mb-2 bd-black text-white">
-      <strong class="d-block">$black</strong>
-      #000
-    </div>
-    <div class="p-3 mb-2 bd-white border">
-      <strong class="d-block">$white</strong>
-      #fff
-    </div>
-  </div>
-</div>
-
-### Notes on Sass
-
-Sass cannot programmatically generate variables, so we manually created variables for every tint and shade ourselves. We specify the midpoint value (e.g., `$blue-500`) and use custom color functions to tint (lighten) or shade (darken) our colors via Sass's `mix()` color function.
-
-Using `mix()` is not the same as `lighten()` and `darken()`—the former blends the specified color with white or black, while the latter only adjusts the lightness value of each color. The result is a much more complete suite of colors, as [shown in this CodePen demo](https://codepen.io/emdeoh/pen/zYOQOPB).
-
-Our `tint-color()` and `shade-color()` functions use `mix()` alongside our `$theme-color-interval` variable, which specifies a stepped percentage value for each mixed color we produce. See the `scss/_functions.scss` and `scss/_variables.scss` files for the full source code.
-
-## Color Sass maps
-
-Bootstrap's source Sass files include three maps to help you quickly and easily loop over a list of colors and their hex values.
-
-- `$colors` lists all our available base (`500`) colors
-- `$theme-colors` lists all semantically named theme colors (shown below)
-- `$grays` lists all tints and shades of gray
-
-Within `scss/_variables.scss`, you'll find Bootstrap's color variables and Sass map. Here's an example of the `$colors` Sass map:
-
-{{< scss-docs name="colors-map" file="scss/_variables.scss" >}}
-
-Add, remove, or modify values within the map to update how they're used in many other components. Unfortunately at this time, not _every_ component utilizes this Sass map. Future updates will strive to improve upon this. Until then, plan on making use of the `${color}` variables and this Sass map.
-
-### Example
-
-Here's how you can use these in your Sass:
-
-```scss
-.alpha { color: $purple; }
-.beta {
-  color: $yellow-300;
-  background-color: $indigo-900;
-}
-```
-
-[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.
-
-## Generating utilities
-
-{{< added-in "5.1.0" >}}
-
-Bootstrap doesn't include `color` and `background-color` utilities for every color variable, but you can generate these yourself with our [utility API]({{< docsref "/utilities/api" >}}) and our extended Sass maps added in v5.1.0.
-
-1. To start, make sure you've imported our functions, variables, mixins, and utilities.
-2. Use our `map-merge-multiple()` function to quickly merge multiple Sass maps together in a new map.
-3. Merge this new combined map to extend any utility with a `{color}-{level}` class name.
-
-Here's an example that generates text color utilities (e.g., `.text-purple-500`) using the above steps.
-
-```scss
-@import "bootstrap/scss/functions";
-@import "bootstrap/scss/variables";
-@import "bootstrap/scss/maps";
-@import "bootstrap/scss/mixins";
-@import "bootstrap/scss/utilities";
-
-$all-colors: map-merge-multiple($blues, $indigos, $purples, $pinks, $reds, $oranges, $yellows, $greens, $teals, $cyans);
-
-$utilities: map-merge(
-  $utilities,
-  (
-    "color": map-merge(
-      map-get($utilities, "color"),
-      (
-        values: map-merge(
-          map-get(map-get($utilities, "color"), "values"),
-          (
-            $all-colors
-          ),
-        ),
-      ),
-    ),
-  )
-);
-
-@import "bootstrap/scss/utilities/api";
-```
-
-This will generate new `.text-{color}-{level}` utilities for every color and level. You can do the same for any other utility and property as well.
diff --git a/site/content/docs/5.2/customize/components.md b/site/content/docs/5.3/customize/components.md
index b512a90..262c8d8 100644
--- a/site/content/docs/5.2/customize/components.md
+++ b/site/content/docs/5.3/customize/components.md
@@ -34,7 +34,7 @@ Should you modify your `$grid-breakpoints`, your changes will apply to all the l
 
 {{< scss-docs name="grid-breakpoints" file="scss/_variables.scss" >}}
 
-For more information and examples on how to modify our Sass maps and variables, please refer to [the Sass section of the Grid documentation]({{< docsref "/layout/grid#sass" >}}).
+For more information and examples on how to modify our Sass maps and variables, please refer to [the CSS section of the Grid documentation]({{< docsref "/layout/grid#css" >}}).
 
 ## Creating your own
 
diff --git a/site/content/docs/5.2/customize/css-variables.md b/site/content/docs/5.3/customize/css-variables.md
index 26d1675..ffb40c0 100644
--- a/site/content/docs/5.2/customize/css-variables.md
+++ b/site/content/docs/5.3/customize/css-variables.md
@@ -14,10 +14,14 @@ Bootstrap includes many [CSS custom properties (variables)](https://developer.mo
 
 Here are the variables we include (note that the `:root` is required) that can be accessed anywhere Bootstrap's CSS is loaded. They're located in our `_root.scss` file and included in our compiled dist files.
 
+### Default
+
+These CSS variables are available everywhere, regardless of color mode.
+
 ```css
 {{< root.inline >}}
 {{- $css := readFile "dist/css/bootstrap.css" -}}
-{{- $match := findRE ":root {([^}]*)}" $css 1 -}}
+{{- $match := findRE `:root,\n\[data-bs-theme=light\] {([^}]*)}` $css 1 -}}
 
 {{- if (eq (len $match) 0) -}}
 {{- errorf "Got no matches for :root in %q!" $.Page.Path -}}
@@ -28,6 +32,21 @@ Here are the variables we include (note that the `:root` is required) that can b
 {{< /root.inline >}}
 ```
 
+### Dark mode
+
+These variables are scoped to our built-in dark mode.
+
+```css
+{{< root.inline >}}
+{{- $css := readFile "dist/css/bootstrap.css" -}}
+{{- $match := findRE `\[data-bs-theme=dark\] {([^}]*)}` $css 1 -}}
+{{- if (eq (len $match) 0) -}}
+{{- errorf "Got no matches for [data-bs-theme=dark] in %q!" $.Page.Path -}}
+{{- end -}}
+{{- index $match 0 -}}
+{{< /root.inline >}}
+```
+
 ## Component variables
 
 Bootstrap 5 is increasingly making use of custom properties as local variables for various components. This way we reduce our compiled CSS, ensure styles aren't inherited in places like nested tables, and allow some basic restyling and extending of Bootstrap components after Sass compilation.
@@ -55,6 +74,20 @@ a {
 }
 ```
 
+## Focus variables
+
+{{< added-in "5.3.0" >}}
+
+Bootstrap provides custom `:focus` styles using a combination of Sass and CSS variables that can be optionally added to specific components and elements. We do not yet globally override all `:focus` styles.
+
+In our Sass, we set default values that can be customized before compiling.
+
+{{< scss-docs name="focus-ring-variables" file="scss/_variables.scss" >}}
+
+Those variables are then reassigned to `:root` level CSS variables that can be customized in real-time, including with options for `x` and `y` offsets (which default to their fallback value of `0`).
+
+{{< scss-docs name="root-focus-variables" file="scss/_root.scss" >}}
+
 ## Grid breakpoints
 
 While we include our grid breakpoints as CSS variables (except for `xs`), be aware that **CSS variables do not work in media queries**. This is by design in the CSS spec for variables, but may change in coming years with support for `env()` variables. Check out [this Stack Overflow answer](https://stackoverflow.com/a/47212942) for some helpful links. In the meantime, you can use these variables in other CSS situations, as well as in your JavaScript.
diff --git a/site/content/docs/5.2/customize/optimize.md b/site/content/docs/5.3/customize/optimize.md
index e618ce2..2622f88 100644
--- a/site/content/docs/5.2/customize/optimize.md
+++ b/site/content/docs/5.3/customize/optimize.md
@@ -42,14 +42,11 @@ import 'bootstrap/js/dist/modal';
 This way, you're not including any JavaScript you don't intend to use for components like buttons, carousels, and tooltips. If you're importing dropdowns, tooltips or popovers, be sure to list the Popper dependency in your `package.json` file.
 
 {{< callout info >}}
-### Default Exports
-
-Files in `bootstrap/js/dist` use the **default export**, so if you want to use one of them you have to do the following:
+**Heads up!** Files in `bootstrap/js/dist` use the **default export**. To use them, do the following:
 
 <!-- eslint-skip -->
 ```js
 import Modal from 'bootstrap/js/dist/modal'
-
 const modal = new Modal(document.getElementById('myModal'))
 ```
 {{< /callout >}}
diff --git a/site/content/docs/5.2/customize/options.md b/site/content/docs/5.3/customize/options.md
index 5013fb9..b5c4fc3 100644
--- a/site/content/docs/5.2/customize/options.md
+++ b/site/content/docs/5.3/customize/options.md
@@ -13,6 +13,7 @@ You can find and customize these variables for key global options in Bootstrap's
 | Variable                       | Values                             | Description                                                                            |
 | ------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------- |
 | `$spacer`                      | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{< docsref "/utilities/spacing" >}}). |
+| `$enable-dark-mode`            | `true` (default) or `false`        | Enables built-in [dark mode support]({{< docsref "/customize/color-modes#dark-mode" >}}) across the project and its components. |
 | `$enable-rounded`              | `true` (default) or `false`        | Enables predefined `border-radius` styles on various components. |
 | `$enable-shadows`              | `true` or `false` (default)        | Enables predefined decorative `box-shadow` styles on various components. Does not affect `box-shadow`s used for focus states. |
 | `$enable-gradients`            | `true` or `false` (default)        | Enables predefined gradients via `background-image` styles on various components. |
diff --git a/site/content/docs/5.2/customize/overview.md b/site/content/docs/5.3/customize/overview.md
index d0a853c..ed890ac 100644
--- a/site/content/docs/5.2/customize/overview.md
+++ b/site/content/docs/5.3/customize/overview.md
@@ -4,7 +4,7 @@ title: Customize
 description: Learn how to theme, customize, and extend Bootstrap with Sass, a boatload of global options, an expansive color system, and more.
 group: customize
 toc: false
-aliases: "/docs/5.2/customize/"
+aliases: "/docs/5.3/customize/"
 sections:
   - title: Sass
     description: Utilize our source Sass files to take advantage of variables, maps, mixins, and functions.
@@ -12,6 +12,8 @@ sections:
     description: Customize Bootstrap with built-in variables to easily toggle global CSS preferences.
   - title: Color
     description: Learn about and customize the color systems that support the entire toolkit.
+  - title: Color modes
+    description: Explore our default light mode and the new dark mode, or create custom color modes yourself.
   - title: Components
     description: Learn how we build nearly all our components responsively and with base and modifier classes.
   - title: CSS variables
diff --git a/site/content/docs/5.2/customize/sass.md b/site/content/docs/5.3/customize/sass.md
index 0fd90bc..6da6bbe 100644
--- a/site/content/docs/5.2/customize/sass.md
+++ b/site/content/docs/5.3/customize/sass.md
@@ -57,8 +57,9 @@ In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two
 
 // 2. Include any default variable overrides here
 
-// 3. Include remainder of required Bootstrap stylesheets
+// 3. Include remainder of required Bootstrap stylesheets (including any separate color mode stylesheets)
 @import "../node_modules/bootstrap/scss/variables";
+@import "../node_modules/bootstrap/scss/variables-dark";
 
 // 4. Include any default map overrides here
 
@@ -104,6 +105,7 @@ $body-color: #111;
 
 // Required
 @import "../node_modules/bootstrap/scss/variables";
+@import "../node_modules/bootstrap/scss/variables-dark";
 @import "../node_modules/bootstrap/scss/maps";
 @import "../node_modules/bootstrap/scss/mixins";
 @import "../node_modules/bootstrap/scss/root";
@@ -117,7 +119,7 @@ $body-color: #111;
 Repeat as necessary for any variable in Bootstrap, including the global options below.
 
 {{< callout info >}}
-{{< partial "callout-info-npm-starter.md" >}}
+{{< partial "callouts/info-npm-starter.md" >}}
 {{< /callout >}}
 
 ## Maps and loops
@@ -166,6 +168,7 @@ To remove colors from `$theme-colors`, or any other map, use `map-remove`. Be aw
 // Required
 @import "../node_modules/bootstrap/scss/functions";
 @import "../node_modules/bootstrap/scss/variables";
+@import "../node_modules/bootstrap/scss/variables-dark";
 
 $theme-colors: map-remove($theme-colors, "info", "light", "dark");
 
@@ -294,7 +297,7 @@ Our `scss/mixins/` directory has a ton of mixins that power parts of Bootstrap a
 
 ### Color schemes
 
-A shorthand mixin for the `prefers-color-scheme` media query is available with support for `light`, `dark`, and custom color schemes.
+A shorthand mixin for the `prefers-color-scheme` media query is available with support for `light`, `dark`, and custom color schemes. See [the color modes documentation]({{< docsref "/customize/color-modes" >}}) for information on our color mode mixin.
 
 {{< scss-docs name="mixin-color-scheme" file="scss/mixins/_color-scheme.scss" >}}