wip on deprecating dark mode variants, some migration guide notes to start

8 files changed, 50 insertions, 5 deletions

diff --git a/scss/_carousel.scss b/scss/_carousel.scss
index 858b83634d..61f472a7db 100644
--- a/scss/_carousel.scss
+++ b/scss/_carousel.scss
@@ -210,7 +210,8 @@
 
 // Dark mode carousel
 
-.carousel-dark {
+.carousel-dark,
+[data-bs-theme="dark"] .carousel {
   .carousel-control-prev-icon,
   .carousel-control-next-icon {
     filter: $carousel-dark-control-icon-filter;
diff --git a/scss/_navbar.scss b/scss/_navbar.scss
index 599b055ebc..8c4b7c2584 100644
--- a/scss/_navbar.scss
+++ b/scss/_navbar.scss
@@ -264,7 +264,8 @@
   @include deprecate("`.navbar-light`", "v5.2.0", "v6.0.0", true);
 }
 
-.navbar-dark {
+.navbar-dark,
+[data-bs-theme="dark"] .navbar {
   // scss-docs-start navbar-dark-css-vars
   --#{$prefix}navbar-color: #{$navbar-dark-color};
   --#{$prefix}navbar-hover-color: #{$navbar-dark-hover-color};
diff --git a/site/content/docs/5.2/components/carousel.md b/site/content/docs/5.2/components/carousel.md
index 376998298f..19a1ef1b6e 100644
--- a/site/content/docs/5.2/components/carousel.md
+++ b/site/content/docs/5.2/components/carousel.md
@@ -236,8 +236,12 @@ Carousels support swiping left/right on touchscreen devices to move between slid
 
 ## Dark variant
 
+{{< deprecated-in "5.3.0" >}}
+
 Add `.carousel-dark` to the `.carousel` for darker controls, indicators, and captions. Controls have been inverted from their default white fill with the `filter` CSS property. Captions and controls have additional Sass variables that customize the `color` and `background-color`.
 
+{{< callout-dark-variants "carousel" >}}
+
 {{< example >}}
 <div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel">
   <div class="carousel-indicators">
diff --git a/site/content/docs/5.2/components/dropdowns.md b/site/content/docs/5.2/components/dropdowns.md
index 57623026b4..4d64efd117 100644
--- a/site/content/docs/5.2/components/dropdowns.md
+++ b/site/content/docs/5.2/components/dropdowns.md
@@ -353,9 +353,7 @@ Button dropdowns work with buttons of all sizes, including default and split dro
 
 Opt into darker dropdowns to match a dark navbar or custom style by adding `.dropdown-menu-dark` onto an existing `.dropdown-menu`. No changes are required to the dropdown items.
 
-{{< callout warning >}}
-**Heads up!** Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of adding `.dropdown-menu-dark`, set `data-bs-theme="dark"` on the root element, a parent wrapper, or the component itself.
-{{< /callout >}}
+{{< callout-dark-variants "dropdown-menu" >}}
 
 {{< example >}}
 <div class="dropdown">
diff --git a/site/content/docs/5.2/migration.md b/site/content/docs/5.2/migration.md
index a991fb6839..bfbea7f746 100644
--- a/site/content/docs/5.2/migration.md
+++ b/site/content/docs/5.2/migration.md
@@ -7,6 +7,32 @@ aliases: "/migration/"
 toc: true
 ---
 
+## v5.3.0 (WIP)
+
+<hr class="mb-4">
+
+### Color modes!
+
+- Global support for light (default) and dark modes. Set color theme globally on the `:root` element, on groups of elements and components with a wrapper class, or directly on components. Color modes replace dark variants for components, so  `.carousel-dark`, `.dropdown-menu-dark`, and `.navbar-dark` are deprecated.
+
+- New extended color system. We've added new theme colors (but not in `$theme-colors)`) for a more nuanced, system-wide color palette with new secondary, tertiary, and emphasis colors for `color` and `background-color`. These new colors are available as Sass variables, CSS variables, and utilities.
+
+- Adds new `_variables-dark.scss` stylesheet to house dark-mode specific overrides.
+
+### CSS variables
+
+- Restores CSS variables for breakpoints, though we don't use them in our media queries as they're not supported. However, these can be useful in JS-specific contexts.
+
+- Adds additional variables for alerts, `.btn-close`, and `.offcanvas`.
+
+### Utilities
+
+- Adds new `.overflow-x`, `.overflow-y`, and several `.object-fit-*` utilities. _The object-fit property is used to specify how an `<img>` or `<video>` should be resized to fit its container. Offers a responsive alternative to using `background-image` for a resizable fill/fit image._
+
+- Adds new `.fw-medium` utility.
+
+For a complete list of changes, [see the v5.3.0 project on GitHub](https://github.com/twbs/bootstrap/projects/).
+
 ## v5.2.0
 
 <hr class="mb-4">
diff --git a/site/content/docs/5.2/utilities/colors.md b/site/content/docs/5.2/utilities/colors.md
index d5acd41b59..8e92875e18 100644
--- a/site/content/docs/5.2/utilities/colors.md
+++ b/site/content/docs/5.2/utilities/colors.md
@@ -18,6 +18,11 @@ Colorize text with color utilities. If you want to colorize links, you can use t
 {{< /colors.inline >}}
 <p class="text-body">.text-body</p>
 <p class="text-muted">.text-muted</p>
+
+<p class="text-body-emphasis">.text-body-emphasis</p>
+<p class="text-body-secondary">.text-body-secondary</p>
+<p class="text-body-tertiary">.text-body-tertiary</p>
+
 <p class="text-white bg-dark">.text-white</p>
 <p class="text-black-50">.text-black-50</p>
 <p class="text-white-50 bg-dark">.text-white-50</p>
diff --git a/site/layouts/partials/callout-warning-dark-variants.md b/site/layouts/partials/callout-warning-dark-variants.md
new file mode 100644
index 0000000000..429fcfdea6
--- /dev/null
+++ b/site/layouts/partials/callout-warning-dark-variants.md
@@ -0,0 +1 @@
+**Heads up!** Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of adding `.{component-name}-dark`, set `data-bs-theme="dark"` on the root element, a parent wrapper, or the component itself.
diff --git a/site/layouts/shortcodes/callout-dark-variants.html b/site/layouts/shortcodes/callout-dark-variants.html
new file mode 100644
index 0000000000..646b01bcdf
--- /dev/null
+++ b/site/layouts/shortcodes/callout-dark-variants.html
@@ -0,0 +1,9 @@
+{{- /* Outputs badge to identify the first version something was added */ -}}
+
+{{- $component := .Get 0 -}}
+
+<div class="bd-callout bd-callout-warning">
+  <p>
+   <strong>Heads up!</strong> Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of adding <code>.{{ $component }}-dark</code>, set <code>data-bs-theme="dark"</code> on the root element, a parent wrapper, or the component itself.
+  </p>
+</div>