Add and document additional :root CSS variables

- Adds grayscale colors - Adds root and body variables Note that some Sass variables default to `null`, so as we generate and use the CSS variable, we'll be potentially adding some lines of code.
twbs · Aug 4, 2021 · 4d7911a · 4d7911a
1 parent e72916e
commit 4d7911a
Show file tree

Hide file tree

Showing 4 changed files with 68 additions and 11 deletions.
diff --git a/scss/_reboot.scss b/scss/_reboot.scss
@@ -26,7 +26,9 @@
 // null by default, thus nothing is generated.
 
 :root {
-  font-size: $font-size-root;
+  @if $font-size-root != null {
+    font-size: var(--#{$variable-prefix}-root-font-size);
+  }
 
   @if $enable-smooth-scroll {
     @media (prefers-reduced-motion: no-preference) {
@@ -43,18 +45,20 @@
 // 3. Prevent adjustments of font size after orientation changes in iOS.
 // 4. Change the default tap highlight to be completely transparent in iOS.
 
+// scss-docs-start reboot-body-rules
 body {
   margin: 0; // 1
-  font-family: $font-family-base;
-  @include font-size($font-size-base);
-  font-weight: $font-weight-base;
-  line-height: $line-height-base;
-  color: $body-color;
-  text-align: $body-text-align;
-  background-color: $body-bg; // 2
+  font-family: var(--#{$variable-prefix}body-font-family);
+  @include font-size(var(--#{$variable-prefix}body-font-size));
+  font-weight: var(--#{$variable-prefix}body-font-weight);
+  line-height: var(--#{$variable-prefix}body-line-height);
+  color: var(--#{$variable-prefix}body-color);
+  text-align: var(--#{$variable-prefix}body-text-align);
+  background-color: var(--#{$variable-prefix}body-bg); // 2
   -webkit-text-size-adjust: 100%; // 3
   -webkit-tap-highlight-color: rgba($black, 0); // 4
 }
+// scss-docs-end reboot-body-rules
 
 
 // Content grouping

diff --git a/scss/_root.scss b/scss/_root.scss
@@ -1,9 +1,18 @@
 :root {
-  // Custom variable values only support SassScript inside `#{}`.
+  // Note: Custom variable values only support SassScript inside `#{}`.
+
+  // Colors
+  //
+  // Generate palettes for full colors, grays, and theme colors.
+
   @each $color, $value in $colors {
     --#{$variable-prefix}#{$color}: #{$value};
   }
 
+  @each $color, $value in $grays {
+    --#{$variable-prefix}gray-#{$color}: #{$value};
+  }
+
   @each $color, $value in $theme-colors {
     --#{$variable-prefix}#{$color}: #{$value};
   }
@@ -16,9 +25,29 @@
   --#{$variable-prefix}black-rgb: #{to-rgb($black)};
   --#{$variable-prefix}body-rgb: #{to-rgb($body-color)};
 
-  // Use `inspect` for lists so that quoted items keep the quotes.
+  // Fonts
+
+  // Note: Use `inspect` for lists so that quoted items keep the quotes.
   // See https://github.com/sass/sass/issues/2383#issuecomment-336349172
   --#{$variable-prefix}font-sans-serif: #{inspect($font-family-sans-serif)};
   --#{$variable-prefix}font-monospace: #{inspect($font-family-monospace)};
   --#{$variable-prefix}gradient: #{$gradient};
+
+  // Root and body
+  // stylelint-disable custom-property-empty-line-before
+  // scss-docs-start root-body-variables
+  @if $font-size-root != null {
+    --#{$variable-prefix}root-font-size: #{$font-size-root};
+  }
+  --#{$variable-prefix}body-font-family: #{$font-family-base};
+  --#{$variable-prefix}body-font-size: #{$font-size-base};
+  --#{$variable-prefix}body-font-weight: #{$font-weight-base};
+  --#{$variable-prefix}body-line-height: #{$line-height-base};
+  --#{$variable-prefix}body-color: #{$body-color};
+  @if $body-text-align != null {
+    --#{$variable-prefix}body-text-align: #{$body-text-align};
+  }
+  --#{$variable-prefix}body-bg: #{$body-bg};
+  // scss-docs-end root-body-variables
+  // stylelint-enable custom-property-empty-line-before
 }
diff --git a/site/content/docs/5.0/content/reboot.md b/site/content/docs/5.0/content/reboot.md
@@ -56,6 +56,26 @@ Note that because the font stack includes emoji fonts, many common symbol/dingba
 
 This `font-family` is applied to the `<body>` and automatically inherited globally throughout Bootstrap. To switch the global `font-family`, update `$font-family-base` and recompile Bootstrap.
 
+## CSS variables
+
+As Bootstrap 5 continues to mature, more and more styles will be built with [CSS variables]({{< docsref "/customize/css-variables" >}}) as a means to provide more real-time customization without the need to always recompile Sass. Our approach is to take our source Sass variables and transform them into CSS variables. That way, even if you don't use CSS variables, you still have all the power of Sass. **This is still in-progress and will take time to fully implement.**
+
+For example, consider these `:root` CSS variables for common `<body>` styles:
+
+{{< scss-docs name="root-body-variables" file="scss/_root.scss" >}}
+
+In practice, those variables are then applied in Reboot like so:
+
+{{< scss-docs name="reboot-body-rules" file="scss/_reboot.scss" >}}
+
+Which allows you to make real-time customizations however you like:
+
+```html
+<body style="--bs-body-color: #333;">
+  <!-- ... -->
+</body>
+```
+
 ## Headings and paragraphs
 
 All heading elements—e.g., `<h1>`—and `<p>` are reset to have their `margin-top` removed. Headings have `margin-bottom: .5rem` added and paragraphs `margin-bottom: 1rem` for easy spacing.

diff --git a/site/content/docs/5.0/customize/css-variables.md b/site/content/docs/5.0/customize/css-variables.md
@@ -6,7 +6,7 @@ group: customize
 toc: true
 ---
 
-Bootstrap includes around two dozen [CSS custom properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) in its compiled CSS, with dozens more on the way for improved customization on a per-component basis. These provide easy access to commonly used values like our theme colors, breakpoints, and primary font stacks when working in your browser's inspector, a code sandbox, or general prototyping.
+Bootstrap includes many [CSS custom properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) in its compiled CSS for real-time customization without the need to recomple Sass. These provide easy access to commonly used values like our theme colors, breakpoints, and primary font stacks when working in your browser's inspector, a code sandbox, or general prototyping.
 
 **All our custom properties are prefixed with `bs-`** to avoid conflicts with third party CSS.
 
@@ -48,3 +48,7 @@ a {
   color: var(--bs-blue);
 }
 ```
+
+## Grid breakpoints
+
+While we include our grid breakpoints as CSS variables (except for `xs`), be aware that **CSS variables do not work in media queries**. This is by design in the CSS spec for variables, but may change in coming years with support for `env()` variables. Check out [this Stack Overflow answer](https://stackoverflow.com/a/47212942) for some helpful links. In the mean team, you can use these variables in other CSS situations, as well as in your JavaScript.