Add dark mode support

[mdo]

Heavily WIP still, but this begins the process of implementing dark mode for our docs and across the project itself. Here's a quick look at what's coming. Builds on #35736.

Live Preview

Light	Dark

Toggling

Color modes are toggled in the docs navbar with a custom toggler, which stores the select color mode in local storage. Color modes are set via data attribute via data-theme (with light or dark options available currently). This allows us to theme the entire page, or specific components, like so.

New Sass and CSS variables

In order to best implement color modes, I've spiked out a number of new Sass and CSS variables (e.g., --bs-secondary-bg and --bs-tertiary-bg). In addition, I've added new global CSS variables like --bs-border-color and more. So, in addition to general color modes and theming support, we get greater real-time customization, too.

This allows us to have more nuance coloring, and a more system-wide color scheme, than we currently support. Some inspiration of the new CSS variables comes from macOS and other design systems where there are global constants (e.g., using the same border-color or blue being the color for links, primary actions, etc).

Todos and open questions:

• Do we refer to these as themes or color modes?
• Do we provide a color mode toggler JS plugin? (Would close Creating Dark Mode Button #35333)
• Finish docs for color modes
• Update all components to better utilize global CSS variables so they can be more easily themed (e.g., see $dropdown-* Sass variable changes in the diff).

---

• Fixes Support for prefers-color-scheme media query #27514
• Fixes Precompiled dark version #28424
• Replaces Docs dark mode #28449
• Fixes Bootstrap Dark Mode #28540
• Fixes Feature Request: Dark Mode #28754
• Fixes Support for dark mode on documentation pages #29720
• Fixes Dark theme for Bootstrap v5 #31175
• Fixes Add Dark Mode to the Doc #33071
• Fixes Add "dark mode" button in this website!! #33501
• Fixes Change text-muted value and bind color to body-color #34457
• Fixes Convert link colors to rgb #37081

[Kopyov]

@mdo consider also adding root CSS vars for $spacer as it would give a better control over margin/padding utility classes and prepare the code to re-use spacing CSS vars in all components. Something like this:

// root var
--#{$variable-prefix}spacer: #{$spacer};

// variables.scss
$spacer: 1rem !default;
$spacers: (
  0: 0,
  1: calc(var(--#{$variable-prefix}spacer) * .25),
  2: calc(var(--#{$variable-prefix}spacer) * .5),
  3: var(--#{$variable-prefix}spacer),
  4: calc(var(--#{$variable-prefix}spacer) * 1.5),
  5: calc(var(--#{$variable-prefix}spacer) * 3),
) !default;

// component vars in variables.scss
$card-spacer-y:                     var(--#{$variable-prefix}spacer) !default;
$card-spacer-x:                     var(--#{$variable-prefix}spacer) !default;
$card-title-spacer-y:             calc(var(--#{$variable-prefix}spacer) * .5) !default;

and convert all SASS calculations to calc(). This change will probably lead to other changes in a bunch of files, but would be definitely a good addition in one of future updates.

[mdo]

Pushed a big update here that revamps the toggler to be a dropdown so we can accept light mode, dark mode, or automatic (based on system preference). My JS isn't the best, but it feels decent and works well lol. Would love some eyes on it.

Light	Dark

And here's how the theme toggler looks in the navbar. Note that as you change the theme, the icon in the navbar updates accordingly to indicate what theme is active.

[julien-deramond]

It becomes very difficult to review it globally with all the comments and various topics mentioned by everyone so IMHO we got a first version that can be merged already.

@mdo tracked a part of all the discussions that happened in this PR in #37549. I'll complete it with my remaining feedback and double check we haven't forgotten any other feedback done by everyone. Thanks all for that 🙏

If we merge this PR, we could continue to tackle the different topics separately in dedicated PRs. And it'll allow us to manipulate on a daily-basis the light and dark mode while reviewing other PRs.

At some point, let's release an alpha version just to have first feedbacks regarding the color modes but also how the documentation allow the users to install this new color mode and also to evaluate the impact as a 5.3.0 (if there are no ultra breaking changes that should rather end up in a v6 rather than a v5.3.0).

⚠️ Before merging just double check and update the description with all the "Fixes" commands. Maybe all the issues couldn't be closed right away with this PR only

[mdo]

😮 We merged it!

I ended up removing the fix for the text underline CSS variable on links, but that could maybe come back. It was a little rougher to tackle than I expected, so waiting on a new fix there.

[tonimelisma]

Excellent! Thank you so much @mdo! Which release do you expect this to be in? Will it be in 5.3.0 or something earlier?

[mdo]

Excellent! Thank you so much @mdo! Which release do you expect this to be in? Will it be in 5.3.0 or something earlier?

It'll come in a v5.3.0-alpha1 release, 🔜

[kjoedion]

thank you @mdo you're a rock star

[kjoedion]

@mdo any idea when we can install this via something like npm i bootstrap@5.3.0-alpha1?

[burdittw]

Something is not right with the merge or modified code has been uploaded. In the _root.scss at line 135, it is trying to use some variables that not defined as in the --#{$prefix}body-color: #{$body-color-dark};. The ending section ends in #{$body-color-dark} and is not setup anywhere. This whole section starts with if $enable-dark-mode so I am guessing this was either some old code in main or the newer version from the new-masthead-darkmode did not get applied???

[julien-deramond]

@burdittw $body-color-dark is defined in _variables-dark.scss (new file) which is imported in bootstrap.scss before _root.scss (see https://twbs-bootstrap.netlify.app/docs/5.2/customize/sass/#importing)

[mmm8955405]

release v5.3.0-alpha1

[septatrix]

@mdo any idea when we can install this via something like npm i bootstrap@5.3.0-alpha1?

You can always install it using npm as a git repo (and hash)

[mmm8955405]

@mdo any idea when we can install this via something like npm i bootstrap@5.3.0-alpha1?

You can always install it using npm as a git repo (and hash)

Why not publish？

[mdo]

The next release will ship when it's ready :).