Dark mode: migration guide

site/content/docs/5.3/components/list-group.md

@@ -358,7 +358,7 @@ As part of Boosted's evolving CSS variables approach, list groups now use local
 
 {{< deprecated-in "5.3.0" >}}
 
-Used in combination with `$background-colors` to generate the [contextual variant classes](#variants) for `.list-group-item`s.
+Was used in to generate the [contextual variant classes](#variants) for `.list-group-item`s.
 
 {{< scss-docs name="list-group-mixin" file="scss/mixins/_list-group.scss" >}}
 

site/content/docs/5.3/migration.md

@@ -17,16 +17,53 @@ Boosted v5.3.3 has landed also including specific Boosted content as usual.
 
 If you need more details about the changes, please refer to the [v5.3.3 release](https://github.com/Orange-OpenSource/Orange-Boosted-Bootstrap/releases/tag/v5.3.3).
 
+### Color modes!
+
+Bootstrap introduced the inner color modes mechanism in v5.3.0. The dark mode was not yet available in the Orange Design System specifications at this time, but is now available since v5.3.3!
+
+Learn more by reading the new [color modes documentation]({{< docsref "/customize/color-modes" >}}).
+
+This change has an impact on how you should use Boosted. Please read carefully the following notes.
+
+From a general point of view, the dark mode is optional on Orange websites. However, a new concept has been introduced and replaces our dark variants for components. It is referred to as "contextual dark mode" and is based on the `data-bs-theme="dark"` attribute. It is used to switch a component or a container to dark mode, independently of the global color mode.
+
+Please note that `data-bs-theme="dark"` automatically sets the `color` and `background-color` CSS properties to `inherit` on the element it is applied to. This means that some of our components have been adapted to this new behavior by setting their default colors and background colors differently. Please double-check that it doesn't break your design. And more generally, please check carefully that this new version doesn't break your design even if you didn't use the dark variants before.
+
+All our helpers and utilities have also been adapted to the new color modes mechanism.
+<!--TODO: describe which ones-->
+<!--TODO: users should use .text-bg-{color} instead of .bg-{color} + forcing .text-{color} when available for automatic contrast-->
+
+<!--TODO: mode selector-->
+
+<!--TODO: new palette colors-->
+
+<!--
+.border-gray-400 has been changed to .border-subtle in `scss-docs.html`, `shortcodes/js-docs.html`, `shortcodes/example.html`
+-->
+
 ### Components
 
+- **Accordion**
+  - <span class="badge text-bg-danger">Breaking</span> The dark variant of the accordion (`.accordion-dark`) has been replaced by using the contextual dark mode with `data-bs-theme="dark"`.
+
 - **Badge**
   - <span class="badge text-bg-warning">Warning</span> It has been fixed in several places in the documentation that badge background and text colors should be handled by using `.text-bg-{color}` classes and not only `.bg-{color}` classes. Please reflect these modifications into your websites.
 
+- **Breadcrumb**
+  - <span class="badge text-bg-danger">Breaking</span> The dark variant of the breadcrumb (`.breadcrumb-dark`) has been replaced by using the contextual dark mode with `data-bs-theme="dark"`.
+
 - **List group**
   - <span class="badge text-bg-success">New</span> The list group variants using contextual classes are now branded correctly. Please check that it doesn't break your design.
   - <span class="badge text-bg-success">New</span> List group with badges has been added to Orange Design System specifications and can now be used in your websites.
   - <span class="badge text-bg-warning">Warning</span> List group font weight is now bold by default. Please check that it doesn't break your design.
 
+- **Orange navbar**
+  - <span class="badge text-bg-danger">Breaking</span> Supra bar variant has changed its markup:
+    - replaced `.navbar-dark.bg-dark` by `data-bs-theme="dark"`
+    - if a shopping basket was present in your supra bar, the notification text doesn't need `.text-white` anymore. It'll be automatically set to white in dark mode and black in light mode.
+
+    Please reflect these modifications into your websites.
+
 ### Contents
 
 - <span class="badge text-bg-warning">Warning</span> The `.lead` class has been updated to reflect the new letter-spacing value for desktop breakpoint, and the line-height values for tablet and mobile breakpoints. Please check that it doesn't break your design.
@@ -35,11 +72,15 @@ If you need more details about the changes, please refer to the [v5.3.3 release]
 
 - <span class="badge text-bg-warning">Warning</span> Quantity selector has been updated to ensure a proper visible focus state and the `.input-group` class has been removed. Make sure to incorporate these changes into your websites.
 
+### Examples
+- <span class="badge text-bg-success">New</span> A navbar mode selector has been added to the examples to render a single navbar with a mode selector to switch between light and dark mode.
+
 ### CSS and Sass variables
 
 - <details class="mb-2">
     <summary><span class="badge text-bg-success">New</span> CSS variables:</summary>
     <ul>
+      <li><code>--bs-back-to-top-link-bg</code></li>
       <li><code>--bs-list-group-font-weight</code></li>
       <li><code>--bs-list-group-item-icon-margin-x</code></li>
       <li><code>--bs-list-group-item-icon-size</code></li>
@@ -49,7 +90,6 @@ If you need more details about the changes, please refer to the [v5.3.3 release]
 - <details class="mb-2">
     <summary><span class="badge text-bg-success">New</span> Sass variables:</summary>
     <ul>
-      <li><code>$list-group-dark-hover-bg</code></li>
       <li><code>$list-group-divider-size</code></li>
       <li><code>$list-group-font-weight</code></li>
       <li><code>$list-group-icons</code></li>
@@ -74,6 +114,10 @@ If you need more details about the changes, please refer to the [v5.3.3 release]
     </ul>
   </details>
 
+### Docs
+
+- <span class="badge text-bg-warning">Warning</span> If you were using our `#check2` icon, please note that its content has been changed.
+
 ## v5.3.2
 
 <hr class="mb-4">