Add dark mode support (#35857)

* Add dark mode to docs

* Minor fix: missing space indentation

* Minor fix: revert utilities/z-index added-in modification

* Remove prev: and next: from doc because extracted to another PR

* Use .bg-body-tertiary in all Utilities > Overflow examples

* fix example

* Fix up spacing examples

* Update box-shadow Sass variables and utilities to auto-adjust to color modes

* Remove unused docs class

* Refactor form styles to use CSS variable for background images on .form-check and .form-switch

* Fix docs selector

* Rename shortcut for clarity

* Heading consistency

* Reintroduce missing 4th grid item in Utilities > Spacing example

* Fix bundlewatch

* .bd-callout* rendering is OK so removing comments in the code

* Update scss/_utilities.scss

Co-authored-by: Julien Déramond <julien.deramond@orange.com>

* Fix gutters example styling

* Fix text colors on background utils docs

* redesign and fix up position marker example, which doesn't show nicely in darkmode but at least isn't broken

* fix some color utils examples

* Deprecate mixin notice

* Deprecate notice for list-group-item-variant() mixin

* Revamp new link CSS vars

* Use map-keys in some each Sass files

* Remove list-group-item-variant mixin ref in sass loop desc

* Display CSS vars scoped to our built-in dark mode

* Revert previous commit

* Fix list group variant link

* Fix typo

* Remove imports of alert/list-group mixins in scss/_mixins.scss

* Small formatting + comments removal in scss/_content.scss

* Fix alert links colors

* fix dropdown border-radius mixin

* fix link color and underline again, this time using CSS var override for color var and fallback value for the underline

* fix colors on docs navbar for dark mode

* remove two changes

* missing ref

* another link underline fix, just use sass vars for link decoration for now

* missing color bg docs, plus move dropdown override to scss

* more changes from review

* fix some examples, drop unused docs navbar styles, update docs navbar color mode to use mixin

* Few fixes around type

- Restored CSS variable for color on headings, this time with a fallback value
- In conjunction, restored and wrapped the default CSS var with a null value check
- Split headings and paragraphs docs in Reboot, elaborated on them

* Restyle custom details > summary element in docs

* Rewrite some migration docs

* fix form checks

* Fix up some navbar styling, tweak docs callout

* Fix select images, mostly for validation styling

* Clean up some migration notes, document some new form control CSS vars, mention new variables-dark in sass docs

* Update site/content/docs/5.2/components/scrollspy.md

Co-authored-by: Julien Déramond <julien.deramond@orange.com>

* Apply suggestions from code review

Co-authored-by: Julien Déramond <julien.deramond@orange.com>

* mention form control css vars in migration guide

* Tweak grid and flex docs background examples

* clarify some docs

* fix some more things

Co-authored-by: Julien Déramond <juderamond@gmail.com>
Co-authored-by: Julien Déramond <julien.deramond@orange.com>

scss/forms/_form-check.scss

@@ -27,11 +27,14 @@
 }
 
 .form-check-input {
+  --#{$prefix}form-check-bg: #{escape-svg($form-check-input-bg)};
+
   width: $form-check-input-width;
   height: $form-check-input-width;
   margin-top: ($line-height-base - $form-check-input-width) * .5; // line-height minus check height
   vertical-align: top;
-  background-color: $form-check-input-bg;
+  background-color: var(--#{$prefix}form-check-bg);
+  background-image: var(--#{$prefix}form-check-bg-image);
   background-repeat: no-repeat;
   background-position: center;
   background-size: contain;
@@ -65,17 +68,17 @@
 
     &[type="checkbox"] {
       @if $enable-gradients {
-        background-image: escape-svg($form-check-input-checked-bg-image), var(--#{$prefix}gradient);
+        --#{$prefix}form-check-bg-image: #{escape-svg($form-check-input-checked-bg-image)}, var(--#{$prefix}gradient);
       } @else {
-        background-image: escape-svg($form-check-input-checked-bg-image);
+        --#{$prefix}form-check-bg-image: #{escape-svg($form-check-input-checked-bg-image)};
       }
     }
 
     &[type="radio"] {
       @if $enable-gradients {
-        background-image: escape-svg($form-check-radio-checked-bg-image), var(--#{$prefix}gradient);
+        --#{$prefix}form-check-bg-image: #{escape-svg($form-check-radio-checked-bg-image)}, var(--#{$prefix}gradient);
       } @else {
-        background-image: escape-svg($form-check-radio-checked-bg-image);
+        --#{$prefix}form-check-bg-image: #{escape-svg($form-check-radio-checked-bg-image)};
       }
     }
   }
@@ -85,9 +88,9 @@
     border-color: $form-check-input-indeterminate-border-color;
 
     @if $enable-gradients {
-      background-image: escape-svg($form-check-input-indeterminate-bg-image), var(--#{$prefix}gradient);
+      --#{$prefix}form-check-bg-image: #{escape-svg($form-check-input-indeterminate-bg-image)}, var(--#{$prefix}gradient);
     } @else {
-      background-image: escape-svg($form-check-input-indeterminate-bg-image);
+      --#{$prefix}form-check-bg-image: #{escape-svg($form-check-input-indeterminate-bg-image)};
     }
   }
 
@@ -121,24 +124,26 @@
   padding-left: $form-switch-padding-start;
 
   .form-check-input {
+    --#{$prefix}form-switch-bg: #{escape-svg($form-switch-bg-image)};
+
     width: $form-switch-width;
     margin-left: $form-switch-padding-start * -1;
-    background-image: escape-svg($form-switch-bg-image);
+    background-image: var(--#{$prefix}form-switch-bg);
     background-position: left center;
     @include border-radius($form-switch-border-radius);
     @include transition($form-switch-transition);
 
     &:focus {
-      background-image: escape-svg($form-switch-focus-bg-image);
+      --#{$prefix}form-switch-bg: #{escape-svg($form-switch-focus-bg-image)};
     }
 
     &:checked {
       background-position: $form-switch-checked-bg-position;
 
       @if $enable-gradients {
-        background-image: escape-svg($form-switch-checked-bg-image), var(--#{$prefix}gradient);
+        --#{$prefix}form-switch-bg: #{escape-svg($form-switch-checked-bg-image)}, var(--#{$prefix}gradient);
       } @else {
-        background-image: escape-svg($form-switch-checked-bg-image);
+        --#{$prefix}form-switch-bg: #{escape-svg($form-switch-checked-bg-image)};
       }
     }
   }
@@ -173,3 +178,11 @@
     }
   }
 }
+
+@if $enable-dark-mode {
+  @include color-mode(dark) {
+    .form-switch .form-check-input:not(:checked):not(:focus) {
+      --#{$prefix}form-switch-bg: #{escape-svg($form-switch-bg-image-dark)};
+    }
+  }
+}

scss/forms/_form-select.scss

@@ -4,6 +4,8 @@
 // https://primer.github.io/.
 
 .form-select {
+  --#{$prefix}form-select-bg-img: #{escape-svg($form-select-indicator)};
+
   display: block;
   width: 100%;
   padding: $form-select-padding-y $form-select-indicator-padding $form-select-padding-y $form-select-padding-x;
@@ -14,7 +16,7 @@
   line-height: $form-select-line-height;
   color: $form-select-color;
   background-color: $form-select-bg;
-  background-image: escape-svg($form-select-indicator);
+  background-image: var(--#{$prefix}form-select-bg-img), var(--#{$prefix}form-select-bg-icon, none);
   background-repeat: no-repeat;
   background-position: $form-select-bg-position;
   background-size: $form-select-bg-size;
@@ -69,3 +71,11 @@
   @include font-size($form-select-font-size-lg);
   @include border-radius($form-select-border-radius-lg);
 }
+
+@if $enable-dark-mode {
+  @include color-mode(dark) {
+    .form-select {
+      --#{$prefix}form-select-bg-img: #{escape-svg($form-select-indicator-dark)};
+    }
+  }
+}