v5: Add Customize section to docs?

scss/_buttons.scss

@@ -12,7 +12,7 @@
   text-decoration: if($link-decoration == none, null, none);
   white-space: $btn-white-space;
   vertical-align: middle;
-  cursor: if($enable-pointer-cursor-for-buttons, pointer, null);
+  cursor: if($enable-button-pointers, pointer, null);
   user-select: none;
   background-color: transparent;
   border: $btn-border-width solid transparent;

scss/_progress.scss

@@ -36,7 +36,7 @@
   .progress-bar-animated {
     animation: progress-bar-stripes $progress-bar-animation-timing;
 
-    @if $enable-prefers-reduced-motion-media-query {
+    @if $enable-reduced-motion {
       @media (prefers-reduced-motion: reduce) {
         animation: none;
       }

scss/_reboot.scss

@@ -463,7 +463,7 @@ button,
 [type="submit"] {
   -webkit-appearance: button; // 2
 
-  @if $enable-pointer-cursor-for-buttons {
+  @if $enable-button-pointers {
     &:not(:disabled) {
       cursor: pointer; // 3
     }

scss/_variables.scss

@@ -42,6 +42,7 @@ $green:   #28a745 !default;
 $teal:    #20c997 !default;
 $cyan:    #17a2b8 !default;
 
+// scss-docs-start colors-map
 $colors: (
   "blue":       $blue,
   "indigo":     $indigo,
@@ -57,6 +58,7 @@ $colors: (
   "gray":       $gray-600,
   "gray-dark":  $gray-800
 ) !default;
+// scss-docs-end colors-map
 
 $primary:       $blue !default;
 $secondary:     $gray-600 !default;
@@ -67,6 +69,7 @@ $danger:        $red !default;
 $light:         $gray-100 !default;
 $dark:          $gray-800 !default;
 
+// scss-docs-start theme-colors-map
 $theme-colors: (
   "primary":    $primary,
   "secondary":  $secondary,
@@ -77,6 +80,7 @@ $theme-colors: (
   "light":      $light,
   "dark":       $dark
 ) !default;
+// scss-docs-end theme-colors-map
 
 // Set a specific jump point for requesting color jumps
 $theme-color-interval: 8% !default;
@@ -204,19 +208,19 @@ $escaped-characters: (
 //
 // Quickly modify global styling by enabling or disabling optional features.
 
-$enable-caret:                                true !default;
-$enable-rounded:                              true !default;
-$enable-shadows:                              false !default;
-$enable-gradients:                            false !default;
-$enable-transitions:                          true !default;
-$enable-prefers-reduced-motion-media-query:   true !default;
-$enable-grid-classes:                         true !default;
-$enable-pointer-cursor-for-buttons:           true !default;
-$enable-rfs:                                  true !default;
-$enable-validation-icons:                     true !default;
-$enable-negative-margins:                     false !default;
-$enable-deprecation-messages:                 true !default;
-$enable-important-utilities:                  true !default;
+$enable-caret:                true !default;
+$enable-rounded:              true !default;
+$enable-shadows:              false !default;
+$enable-gradients:            false !default;
+$enable-transitions:          true !default;
+$enable-reduced-motion:       true !default;
+$enable-grid-classes:         true !default;
+$enable-button-pointers:      true !default;
+$enable-rfs:                  true !default;
+$enable-validation-icons:     true !default;
+$enable-negative-margins:     false !default;
+$enable-deprecation-messages: true !default;
+$enable-important-utilities:  true !default;
 
 
 // Spacing

scss/bootstrap.scss

@@ -5,16 +5,14 @@
  * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
  */
 
+// scss-docs-start import-stack
 // Configuration
-
 @import "functions";
 @import "variables";
 @import "mixins";
 @import "utilities";
 
-
 // Layout & components
-
 @import "root";
 @import "reboot";
 @import "type";
@@ -44,12 +42,9 @@
 @import "carousel";
 @import "spinners";
 
-
 // Helpers
-
 @import "helpers";
 
-
 // Utilities
-
 @import "utilities/api";
+// scss-docs-end import-stack

scss/mixins/_transition.scss

@@ -17,7 +17,7 @@
       transition: $transition;
     }
 
-    @if $enable-prefers-reduced-motion-media-query and nth($transition, 1) != null and nth($transition, 1) != none {
+    @if $enable-reduced-motion and nth($transition, 1) != null and nth($transition, 1) != none {
       @media (prefers-reduced-motion: reduce) {
         transition: none;
       }

site/assets/scss/_colors.scss

@@ -117,3 +117,16 @@
 .bd-cyan-700 { color: color-contrast($cyan-700); background-color: $cyan-700; }
 .bd-cyan-800 { color: color-contrast($cyan-800); background-color: $cyan-800; }
 .bd-cyan-900 { color: color-contrast($cyan-900); background-color: $cyan-900; }
+
+.bd-gray-100 { color: color-contrast($gray-100); background-color: $gray-100; }
+.bd-gray-200 { color: color-contrast($gray-200); background-color: $gray-200; }
+.bd-gray-300 { color: color-contrast($gray-300); background-color: $gray-300; }
+.bd-gray-400 { color: color-contrast($gray-400); background-color: $gray-400; }
+.bd-gray-500 { color: color-contrast($gray-500); background-color: $gray-500; }
+.bd-gray-600 { color: color-contrast($gray-600); background-color: $gray-600; }
+.bd-gray-700 { color: color-contrast($gray-700); background-color: $gray-700; }
+.bd-gray-800 { color: color-contrast($gray-800); background-color: $gray-800; }
+.bd-gray-900 { color: color-contrast($gray-900); background-color: $gray-900; }
+
+.bd-white { color: color-yiq($white); background-color: $white; }
+.bd-black { color: color-yiq($black); background-color: $black; }

site/assets/scss/_content.scss

@@ -29,6 +29,7 @@
   > .table {
     max-width: 100%;
     margin-bottom: 1.5rem;
+    @include font-size(.875rem);
 
     @include media-breakpoint-down(md) {
       display: block;

site/content/docs/4.3/customize/color.md

@@ -0,0 +1,106 @@
+---
+layout: docs
+title: Color
+description: Bootstrap is supported by an extensive color system that themes our styles and components. This enables more comprehensive customization and extension for any project.
+group: customize
+toc: true
+---
+
+## Theme colors
+
+We use a subset of all colors to create a smaller color palette for generating color schemes, also available as Sass variables and a Sass map in Bootstrap's `scss/_variables.scss` file.
+
+<div class="row">
+  {{< theme-colors.inline >}}
+  {{- range (index $.Site.Data "theme-colors") }}
+    <div class="col-md-4">
+      <div class="p-3 mb-3 bg-{{ .name }} {{ if or (eq .name "light") (eq .name "warning") }}text-dark{{ else }}text-white{{ end }}">{{ .name | title }}</div>
+    </div>
+  {{ end -}}
+  {{< /theme-colors.inline >}}
+</div>
+
+All these colors are available as a Sass map, `$theme-colors`.
+
+{{< scss-docs name="theme-colors-map" file="scss/_variables.scss" >}}
+
+Check out [our Sass maps and loops docs]({{< docsref "/customize/sass#maps-and-loops" >}}) for how to modify these colors.
+
+## All colors
+
+All Bootstrap colors are available as Sass variables and a Sass map in `scss/_variables.scss` file. To avoid increased file sizes, we don't create text or background color classes for each of these variables. Instead, we choose a subset of these colors for a [theme palette](#theme-colors).
+
+<div class="row font-monospace">
+  {{< theme-colors.inline >}}
+  {{- range $color := $.Site.Data.colors }}
+    {{- if (and (not (eq $color.name "white")) (not (eq $color.name "gray")) (not (eq $color.name "gray-dark"))) }}
+    <div class="col-md-4 mb-3">
+      <div class="p-3 mb-2 swatch-{{ $color.name }}">
+        <strong class="d-block">${{ $color.name }}</strong>
+        {{ $color.hex }}
+      </div>
+      {{ range (seq 100 100 900) }}
+      <div class="p-3 bd-{{ $color.name }}-{{ . }}">${{ $color.name }}-{{ . }}</div>
+      {{ end }}
+    </div>
+    {{ end -}}
+  {{ end -}}
+
+  <div class="col-md-4 mb-3">
+    <div class="p-3 mb-2 bd-gray-500">
+      <strong class="d-block">$gray-500</strong>
+      #adb5bd
+    </div>
+  {{- range $.Site.Data.grays }}
+    <div class="p-3 bd-gray-{{ .name }}">$gray-{{ .name }}</div>
+  {{ end -}}
+  </div>
+  {{< /theme-colors.inline >}}
+
+  <div class="col-md-4 mb-3">
+    <div class="p-3 mb-2 bd-black text-white">
+      <strong class="d-block">$black</strong>
+      #000
+    </div>
+    <div class="p-3 mb-2 bd-white border">
+      <strong class="d-block">$white</strong>
+      #fff
+    </div>
+  </div>
+</div>
+
+### Notes on Sass
+
+Sass cannot programmatically generate variables, so we manually created variables for every tint and shade ourselves. We specify the midpoint value (e.g., `$blue-500`) and use custom color functions to tint (lighten) or shade (darken) our colors via Sass's `mix()` color function.
+
+Using `mix()` is not the same as `lighten()` and `darken()`—the former blends the specified color with white or black, while the latter only adjusts the lightness value of each color. The result is a much more complete suite of colors, as [shown in this CodePen demo](https://codepen.io/emdeoh/pen/zYOQOPB).
+
+Our `tint-color()` and `shade-color()` functions use `mix()` alongside our `$theme-color-interval` variable, which specifies a stepped percentage value for each mixed color we produce. See the `scss/_functions.scss` and `scss/_variables.scss` files for the full source code.
+
+## Color Sass maps
+
+Bootstrap's source Sass files include three maps to help you quickly and easily loop over a list of colors and their hex values.
+
+- `$colors` lists all our available base (`500`) colors
+- `$theme-colors` lists all semantically named theme colors (shown below)
+- `$grays` lists all tins and shades of gray
+
+Within `scss/_variables.scss`, you'll find Bootstrap's color variables and Sass map. Here's an example of the `$colors` Sass map:
+
+{{< scss-docs name="colors-map" file="scss/_variables.scss" >}}
+
+Add, remove, or modify values within the map to update how they're used in many other components. Unfortunately at this time, not _every_ component utilizes this Sass map. Future updates will strive to improve upon this. Until then, plan on making use of the `${color}` variables and this Sass map.
+
+### Example
+
+Here's how you can use these in your Sass:
+
+{{< highlight scss >}}
+.alpha { color: $purple; }
+.beta {
+  color: $yellow-300;
+  background-color: $indigo-900;
+}
+{{< /highlight >}}
+
+[Color utility classes]({{< docsref "/utilities/colors" >}}) are also available for setting `color` and `background-color` using the `500` color values.

site/content/docs/4.3/customize/components.md

@@ -0,0 +1,77 @@
+---
+layout: docs
+title: Components
+description: Learn how and why we build nearly all our components responsively and with base and modifier classes.
+group: customize
+toc: true
+---
+
+## Base classes
+
+Bootstrap's components are largely built with a base-modifier nomenclature. We group as many shared properties as possible into a base class, like `.btn`, and then group individual styles for each variant into modifier classes, like `.btn-primary` or `.btn-success`.
+
+To build our modifier classes, we use Sass's `@each` loops to iterate over a Sass map. This is especially helpful for generating variants of a component by our `$theme-colors` and creating responsive variants for each breakpoint. As you customize these Sass maps and recompile, you'll automatically see your changes reflected in these loops.
+
+Check out [our Sass maps and loops docs]({{< docsref "/customize/sass#maps-and-loops" >}}) for how to customize these loops and extend Bootstrap's base-modifier approach to your own code.
+
+## Modifiers
+
+Many of Bootstrap's components are built with a base-modifier class approach. This means the bulk of the styling is contained to a base class (e.g., `.btn`) while style variations are confined to modifier classes (e.g., `.btn-danger`). These modifier classes are built from the `$theme-colors` map to make customizing the number and name of our modifier classes.
+
+Here are two examples of how we loop over the `$theme-colors` map to generate modifiers to the `.alert` and `.list-group` components.
+
+{{< scss-docs name="alert-modifiers" file="scss/_alert.scss" >}}
+
+{{< scss-docs name="list-group-modifiers" file="scss/_list-group.scss" >}}
+
+## Responsive
+
+These Sass loops aren't limited to color maps, either. You can also generate responsive variations of your components. Take for example our responsive alignment of the dropdowns where we mix an `@each` loop for the `$grid-breakpoints` Sass map with a media query include.
+
+{{< scss-docs name="responsive-breakpoints" file="scss/_dropdown.scss" >}}
+
+Should you modify your `$grid-breakpoints`, your changes will apply to all the loops iterating over that map.
+
+{{< scss-docs name="grid-breakpoints" file="scss/_variables.scss" >}}
+
+For more information and examples on how to modify our Sass maps and variables, please refer to [the Sass section of the Grid documentation]({{< docsref "/layout/grid#sass" >}}).
+
+## Creating your own
+
+We encourage you to adopt these guidelines when building with Bootstrap to create your own components. We've extended the approach ourselves to the custom components in our documentation and examples. Consider the our custom callouts in our documentation that allow us
+
+<div class="bd-example">
+  <div class="bd-callout my-0">
+    <strong>This is a callout.</strong> We built it custom for our docs so our messages to you stand out. It has three variants via modifier classes.
+  </div>
+</div>
+
+{{< highlight html >}}
+<div class="callout">...</div>
+{{< /highlight >}}
+
+In your CSS, you'd have something like the following where the bulk of the styling is done via `.callout`. Then, the unique styles between each variant is controlled via modifier class.
+
+```scss
+// Base class
+.callout {}
+
+// Modifier classes
+.callout-info {}
+.callout-warning {}
+.callout-danger {}
+```
+
+For the callouts, that unique styling is just a `border-left-color`. When you combine that base class with one of those modifier classes, you get your complete component family:
+
+{{< callout info >}}
+**This is an info callout.** Example text to show it in action.
+{{< /callout >}}
+
+{{< callout warning >}}
+**This is a warning callout.** Example text to show it in action.
+{{< /callout >}}
+
+{{< callout danger >}}
+**This is a danger callout.** Example text to show it in action.
+{{< /callout >}}

site/content/docs/4.3/customize/css-variables.md

@@ -0,0 +1,48 @@
+---
+layout: docs
+title: CSS variables
+description: Use Bootstrap's CSS custom properties for fast and forward-looking design and development.
+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. These provide easy access to commonly used values like our theme colors 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.**
+
+## Root variables
+
+Here are the variables we include (note that the `:root` is required) that can be accessed anywhere Bootstrap's CSS is loaded. They're located in our `_root.scss` file and included in our compiled dist files.
+
+{{< highlight css >}}
+{{< root.inline >}}
+{{- $css := readFile "dist/css/bootstrap.css" -}}
+{{- $match := findRE ":root {([^}]*)}" $css 1 -}}
+
+{{- if (eq (len $match) 0) -}}
+{{- errorf "Got no matches for :root in %q!" $.Page.Path -}}
+{{- end -}}
+
+{{- index $match 0 -}}
+
+{{< /root.inline >}}
+{{< /highlight >}}
+
+## Component variables
+
+We're also beginning to make use of custom properties as local variables for various components. By using CSS variables in this way, we can heavily reduce our compiled CSS, ensure that table styles aren't inherited, and allow you to dynamically restyle or extend Bootstrap components without recompiling Sass.
+
+Have a look at our table documentation for some [insight into how we're using CSS variables]({{< docsref "/content/tables#how-do-the-variants-and-accented-tables-work" >}}).
+
+## Examples
+
+CSS variables offer similar flexibility to Sass's variables, but without the need for compilation before being served to the browser. For example, here we're resetting our page's font and link styles with CSS variables.
+
+{{< highlight css >}}
+body {
+  font: 1rem/1.5 var(--bs-font-sans-serif);
+}
+a {
+  color: var(--bs-blue);
+}
+{{< /highlight >}}