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-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)};
+    }
+  }
+}