From bb7ada6548290faad01eaea7c8746b9d8ead956c Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Mon, 13 Apr 2020 17:45:20 -0700
Subject: [PATCH 01/14] Remove existing Theming page as we build out a new
 Customize section

---
 .../docs/4.3/getting-started/theming.md       | 433 ------------------
 1 file changed, 433 deletions(-)
 delete mode 100644 site/content/docs/4.3/getting-started/theming.md

diff --git a/site/content/docs/4.3/getting-started/theming.md b/site/content/docs/4.3/getting-started/theming.md
deleted file mode 100644
index 71bccebf2c06..000000000000
--- a/site/content/docs/4.3/getting-started/theming.md
+++ /dev/null
@@ -1,433 +0,0 @@
----
-layout: docs
-title: Theming Bootstrap
-description: Customize Bootstrap 4 with our new built-in Sass variables for global style preferences for easy theming and component changes.
-group: getting-started
-toc: true
----
-
-## Introduction
-
-In Bootstrap 3, theming was largely driven by variable overrides in LESS, custom CSS, and a separate theme stylesheet that we included in our `dist` files. With some effort, one could completely redesign the look of Bootstrap 3 without touching the core files. Bootstrap 4 provides a familiar, but slightly different approach.
-
-Now, theming is accomplished by Sass variables, Sass maps, and custom CSS. There's no more dedicated theme stylesheet; instead, you can enable the built-in theme to add gradients, shadows, and more.
-
-## Sass
-
-Utilize our source Sass files to take advantage of variables, maps, mixins, and more. In our build we've increased the Sass rounding precision to 6 (by default it's 5) to prevent issues with browser rounding.
-
-### File structure
-
-Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you're using a package manager like npm, you'll have a file structure that looks like this:
-
-{{< highlight text >}}
-your-project/
-├── scss
-│   └── custom.scss
-└── node_modules/
-    └── bootstrap
-        ├── js
-        └── scss
-{{< /highlight >}}
-
-If you've downloaded our source files and aren't using a package manager, you'll want to manually setup something similar to that structure, keeping Bootstrap's source files separate from your own.
-
-{{< highlight text >}}
-your-project/
-├── scss
-│   └── custom.scss
-└── bootstrap/
-    ├── js
-    └── scss
-{{< /highlight >}}
-
-### Importing
-
-In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two options: include all of Bootstrap, or pick the parts you need. We encourage the latter, though be aware there are some requirements and dependencies across our components. You also will need to include some JavaScript for our plugins.
-
-{{< highlight scss >}}
-// Custom.scss
-// Option A: Include all of Bootstrap
-
-@import "../node_modules/bootstrap/scss/bootstrap";
-{{< /highlight >}}
-
-{{< highlight scss >}}
-// Custom.scss
-// Option B: Include parts of Bootstrap
-
-// Required
-@import "../node_modules/bootstrap/scss/functions";
-@import "../node_modules/bootstrap/scss/variables";
-@import "../node_modules/bootstrap/scss/mixins";
-
-// Optional
-@import "../node_modules/bootstrap/scss/reboot";
-@import "../node_modules/bootstrap/scss/type";
-@import "../node_modules/bootstrap/scss/images";
-@import "../node_modules/bootstrap/scss/code";
-@import "../node_modules/bootstrap/scss/grid";
-{{< /highlight >}}
-
-With that setup in place, you can begin to modify any of the Sass variables and maps in your `custom.scss`. You can also start to add parts of Bootstrap under the `// Optional` section as needed. We suggest using the full import stack from our `bootstrap.scss` file as your starting point.
-
-### Variable defaults
-
-Every Sass variable in Bootstrap 4 includes the `!default` flag allowing you to override the variable's default value in your own Sass without modifying Bootstrap's source code. Copy and paste variables as needed, modify their values, and remove the `!default` flag. If a variable has already been assigned, then it won't be re-assigned by the default values in Bootstrap.
-
-You will find the complete list of Bootstrap's variables in `scss/_variables.scss`. Some variables are set to `null`, these variables don't output the property unless they are overridden in your configuration.
-
-Variable overrides within the same Sass file can come before or after the default variables. However, when overriding across Sass files, your overrides must come before you import Bootstrap's Sass files.
-
-Here's an example that changes the `background-color` and `color` for the `<body>` when importing and compiling Bootstrap via npm:
-
-{{< highlight scss >}}
-// Your variable overrides
-$body-bg: #000;
-$body-color: #111;
-
-// Bootstrap and its default variables
-@import "../node_modules/bootstrap/scss/bootstrap";
-{{< /highlight >}}
-
-Repeat as necessary for any variable in Bootstrap, including the global options below.
-
-### Maps and loops
-
-Bootstrap 5 includes a handful of Sass maps, key value pairs that make it easier to generate families of related CSS. We use Sass maps for our colors, grid breakpoints, and more. Just like Sass variables, all Sass maps include the `!default` flag and can be overridden and extended.
-
-From Bootstrap 5, we decided to [ditch the map merges](https://github.com/twbs/bootstrap/pull/28508) we had in `v4`. This way we have more control over removing redundant values.
-
-#### Modify map
-
-All variables in the `$theme-colors` map are defined as standalone variables. To modify an existing color in our `$theme-colors` map, add the following to your custom Sass file:
-
-{{< highlight scss >}}
-$primary: #0074d9;
-$danger: #ff4136;
-{{< /highlight >}}
-
-Later on, theses variables are set in Bootstrap's `$theme-colors` map:
-
-{{< highlight scss >}}
-$theme-colors: (
-  "primary": $primary,
-  "danger": $danger,
-  ...
-);
-{{< /highlight >}}
-
-#### Add to map
-
-To add a new color to `$theme-colors`, add the new key and value. Keep in mind not to remove the existing colors:
-
-{{< highlight scss >}}
-$my-custom-color: #ff00dd;
-
-// Make sure to define `$primary`, `$secondary`, ect.. first
-$theme-colors: (
-  "primary":      $primary,
-  "secondary":    $secondary,
-  "success":      $success,
-  "info":         $info,
-  "warning":      $warning,
-  "danger":       $danger,
-  "light":        $light,
-  "dark":         $dark,
-  "custom-color": $my-custom-color,
-);
-{{< /highlight >}}
-
-#### Remove from map
-
-From Bootstrap 5, this is simplified quite a lot, just remove the redundant items from the Sass map:
-
-{{< highlight scss >}}
-// Make sure to define `$primary`, `$secondary`, ect.. first
-$theme-colors: (
-  "primary":      $primary,
-  "secondary":    $secondary,
-  "success":      $success,
-  "warning":      $warning,
-  "danger":       $danger,
-);
-{{< /highlight >}}
-
-#### Required keys
-
-Bootstrap assumes the presence of some specific keys within Sass maps as we used and extend these ourselves. As you customize the included maps, you may encounter errors where a specific Sass map's key is being used.
-
-For example, we use the `primary`, `success`, and `danger` keys from `$theme-colors` for links, buttons, and form states. Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues. In these instances, you'll need to modify the Sass code that makes use of those values.
-
-### Functions
-
-In Bootstrap 5, we've dropped the `color()`, `theme-color()` and `gray()` functions because the values are also available as standalone variables. So instead of using `theme-color("primary")`, you can now just use the `$primary` variable.
-
-{{< highlight scss >}}
-.custom-element {
-  color: $gray-100;
-  background-color: $dark;
-}
-{{< /highlight >}}
-
-We also have a function for getting a particular _level_ of color. Negative level values will lighten the color, while higher levels will darken.
-
-{{< scss-docs name="color-level" file="scss/_functions.scss" >}}
-
-In practice, you'd call the function and pass in two parameters: the name of the color from `$theme-colors` (e.g., primary or danger) and a numeric level.
-
-{{< highlight scss >}}
-.custom-element {
-  color: color-level($primary, -10);
-}
-{{< /highlight >}}
-
-#### Color contrast
-
-An additional function we include in Bootstrap is the color contrast function, `color-contrast`. It utilizes the [WCAG 2.0 algorithm](https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests) for calculating contrast thresholds based on [relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance) in a `sRGB` colorspace to automatically return a light (`#fff`) or dark (`#111`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
-
-For example, to generate color swatches from our `$theme-colors` map:
-
-{{< highlight scss >}}
-@each $color, $value in $theme-colors {
-  .swatch-#{$color} {
-    color: color-contrast($value);
-  }
-}
-{{< /highlight >}}
-
-It can also be used for one-off contrast needs:
-
-{{< highlight scss >}}
-.custom-element {
-  color: color-contrast(#000); // returns `color: #fff`
-}
-{{< /highlight >}}
-
-You can also specify a base color with our color map functions:
-
-{{< highlight scss >}}
-.custom-element {
-  color: color-contrast($dark); // returns `color: #fff`
-}
-{{< /highlight >}}
-
-{{< callout info >}}
-##### Accessibility
-
-In order to meet [WCAG 2.0 accessibility standards for color contrast](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html), authors **must** provide [a contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG20/quickref/20160105/Overview.php#visual-audio-contrast-contrast), with very few exceptions.
-{{< /callout >}}
-
-#### Escape SVG
-
-We use the `escape-svg` function to escape the `<`, `>` and `#` characters for SVG background images.
-
-#### Add and Subtract functions
-
-We use the `add` and `subtract` functions to wrap the CSS `calc` function. The primary purpose of these functions is to avoid errors when a "unitless" `0` value is passed into a `calc` expression. Expressions like `calc(10px - 0)` will return an error in all browsers, despite being mathematically correct.
-
-Example where the calc is valid:
-
-{{< highlight scss >}}
-$border-radius: .25rem;
-$border-width: 1px;
-
-.element {
-  // Output calc(.25rem - 1px) is valid
-  border-radius: calc($border-radius - $border-width);
-}
-
-.element {
-  // Output the same calc(.25rem - 1px) as above
-  border-radius: subtract($border-radius, $border-width);
-}
-{{< /highlight >}}
-
-Example where the calc is invalid:
-
-{{< highlight scss >}}
-$border-radius: .25rem;
-$border-width: 0;
-
-.element {
-  // Output calc(.25rem - 0) is invalid
-  border-radius: calc($border-radius - $border-width);
-}
-
-.element {
-  // Output .25rem
-  border-radius: subtract($border-radius, $border-width);
-}
-{{< /highlight >}}
-
-## Sass options
-
-Customize Bootstrap 4 with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with `npm run test` as needed.
-
-You can find and customize these variables for key global options in Bootstrap's `scss/_variables.scss` file.
-
-| Variable                                     | Values                             | Description                                                                            |
-| -------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
-| `$spacer`                                    | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{< docsref "/utilities/spacing" >}}). |
-| `$enable-rounded`                            | `true` (default) or `false`        | Enables predefined `border-radius` styles on various components. |
-| `$enable-shadows`                            | `true` or `false` (default)        | Enables predefined `box-shadow` styles on various components. |
-| `$enable-gradients`                          | `true` or `false` (default)        | Enables predefined gradients via `background-image` styles on various components. |
-| `$enable-transitions`                        | `true` (default) or `false`        | Enables predefined `transition`s on various components. |
-| `$enable-prefers-reduced-motion-media-query` | `true` (default) or `false`        | Enables the [`prefers-reduced-motion` media query]({{< docsref "/getting-started/accessibility#reduced-motion" >}}), which suppresses certain animations/transitions based on the users' browser/operating system preferences. |
-| `$enable-grid-classes`                       | `true` (default) or `false`        | Enables the generation of CSS classes for the grid system (e.g. `.row`, `.col-md-1`, etc.). |
-| `$enable-caret`                              | `true` (default) or `false`        | Enables pseudo element caret on `.dropdown-toggle`. |
-| `$enable-pointer-cursor-for-buttons`         | `true` (default) or `false`        | Add "hand" cursor to non-disabled button elements. |
-| `$enable-rfs`                                | `true` (default) or `false`        | Globally enables [RFS]({{< docsref "/getting-started/rfs" >}}). |
-| `$enable-validation-icons`                   | `true` (default) or `false`        | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
-| `$enable-negative-margins`                   | `true` or `false` (default)        | Enables the generation of [negative margin utilities]({{< docsref "/utilities/spacing#negative-margin" >}}). |
-| `$enable-deprecation-messages`               | `true` or `false` (default)        | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
-| `$enable-important-utilities`                | `true` (default) or `false`        | Enables the `!important` suffix in utility classes. |
-
-## Color
-
-Many of Bootstrap's various components and utilities are built through a series of colors defined in a Sass map. This map can be looped over in Sass to quickly generate a series of rulesets.
-
-### All colors
-
-All colors available in Bootstrap 5 are available as Sass variables and as a Sass map in `scss/_variables.scss`. To avoid increased file sizes, we do not create classes for each of these variables.
-
-Sass cannot programmatically generate variables, so we must manually create them ourselves. We specify the midpoint value (`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 need. See the `scss/_functions.scss` and `scss/_variables.scss` files for the full source code.
-
-<div class="row">
-  {{< 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 font-monospace">
-      <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 -}}
-  {{< /theme-colors.inline >}}
-</div>
-
-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`.
-
-### 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>
-
-### Grays
-
-An expansive set of gray variables and a Sass map in `scss/_variables.scss` for consistent shades of gray across your project. Note that these are "cool grays", which tend towards a subtle blue tone, rather than neutral grays.
-
-<div class="row mb-3">
-  <div class="col-md-4">
-    {{< theme-colors.inline >}}
-    {{- range $.Site.Data.grays }}
-      <div class="p-3 swatch-{{ .name }}">{{ .name }}</div>
-    {{ end -}}
-  {{< /theme-colors.inline >}}
-  </div>
-</div>
-
-Within `scss/_variables.scss`, you'll find Bootstrap's color variables and Sass map. Here's an example of the `$colors` Sass map:
-
-{{< highlight scss >}}
-$colors: (
-  "blue": $blue,
-  "indigo": $indigo,
-  "purple": $purple,
-  "pink": $pink,
-  "red": $red,
-  "orange": $orange,
-  "yellow": $yellow,
-  "green": $green,
-  "teal": $teal,
-  "cyan": $cyan,
-  "white": $white,
-  "gray": $gray-600,
-  "gray-dark": $gray-800
-) !default;
-{{< /highlight >}}
-
-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.
-
-## Components
-
-Many of Bootstrap's components and utilities are built with `@each` loops that 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.
-
-### 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 need to modify your `$grid-breakpoints`, your changes will apply to all the loops iterating over that map.
-
-## CSS variables
-
-Bootstrap 4 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.
-
-### Available variables
-
-Here are the variables we include (note that the `:root` is required). They're located in our `_root.scss` file.
-
-{{< 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 >}}
-
-### 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 >}}

From 0408799ae5ddad0ea8d441bca6de5d5bbb730e16 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Mon, 13 Apr 2020 17:48:19 -0700
Subject: [PATCH 02/14] Rename variables for brevity

- Rename `$enable-prefers-reduced-motion-media-query` to `$enable-reduced-motion`
- Rename `$enable-pointer-cursor-for-buttons` to `$enable-button-pointers`
---
 scss/_buttons.scss                 |  2 +-
 scss/_progress.scss                |  2 +-
 scss/_reboot.scss                  |  2 +-
 scss/_variables.scss               | 26 +++++++++++++-------------
 scss/mixins/_transition.scss       |  2 +-
 site/content/docs/4.3/migration.md |  1 +
 6 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/scss/_buttons.scss b/scss/_buttons.scss
index 7381de5332bd..db9d172e8e4a 100644
--- a/scss/_buttons.scss
+++ b/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;
diff --git a/scss/_progress.scss b/scss/_progress.scss
index 1dbaa67c0c19..a3fbecf2b57e 100644
--- a/scss/_progress.scss
+++ b/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;
       }
diff --git a/scss/_reboot.scss b/scss/_reboot.scss
index 4c5dfcba41e1..73b974b57071 100644
--- a/scss/_reboot.scss
+++ b/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
     }
diff --git a/scss/_variables.scss b/scss/_variables.scss
index e95343496a1f..a3d1df747b65 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -204,19 +204,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
diff --git a/scss/mixins/_transition.scss b/scss/mixins/_transition.scss
index 54553deb9c67..bf4c00a64b87 100644
--- a/scss/mixins/_transition.scss
+++ b/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;
       }
diff --git a/site/content/docs/4.3/migration.md b/site/content/docs/4.3/migration.md
index 3806b6049ab2..eef9193ac588 100644
--- a/site/content/docs/4.3/migration.md
+++ b/site/content/docs/4.3/migration.md
@@ -38,6 +38,7 @@ Changes to our source Sass files and compiled CSS.
 - Dropped `color()`, `theme-color()` & `gray()` functions in favor of variables. [See #29083](https://github.com/twbs/bootstrap/pull/29083)
 - The `theme-color-level()` function is renamed to `color-level()` and now accepts any color you want instead of only `$theme-color` colors. [See #29083](https://github.com/twbs/bootstrap/pull/29083)
 - `$enable-grid-classes` doesn't disable the generation of container classes anymore [See #29146](https://github.com/twbs/bootstrap/pull/29146)
+- Renamed `$enable-prefers-reduced-motion-media-query` and `$enable-pointer-cursor-for-buttons` to `$enable-reduced-motion` and `$enable-button-pointers` for brevity.
 - Line heights are dropped from several components to simplify our codebase. The `button-size()` and `pagination-size()` do not accept line height parameters anymore. [See #29271](https://github.com/twbs/bootstrap/pull/29271)
 - The `button-variant()` mixin now accepts 3 optional color parameters, for each button state, to override the color provided by `color-contrast()`. By default, these parameters will find which color provides more contrast against the button state's background color with `color-contrast()`.
 - The `button-outline-variant()` mixin now accepts an additional argument, `$active-color`, for setting the button's active state text color. By default, this parameter will find which color provides more contrast against the button's active background color with `color-contrast()`.

From 85ac2fc35e60c430d5ba0342e584ba0a9b5b916e Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Mon, 13 Apr 2020 17:53:06 -0700
Subject: [PATCH 03/14] Create a new table shortcode so we can easily add
 Bootstrap table classes to Markdown tables

---
 site/layouts/shortcodes/bs-table.html | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 site/layouts/shortcodes/bs-table.html

diff --git a/site/layouts/shortcodes/bs-table.html b/site/layouts/shortcodes/bs-table.html
new file mode 100644
index 000000000000..6f972d66513f
--- /dev/null
+++ b/site/layouts/shortcodes/bs-table.html
@@ -0,0 +1,11 @@
+{{- /*
+  Usage: `table "class"`,
+  where class can be anything
+*/ -}}
+
+{{ $htmlTable := .Inner | markdownify }}
+{{ $css_class := .Get 0 | default "table" }}
+{{ $old := "<table>" }}
+{{ $new := printf "<table class=\"%s\">" $css_class }}
+{{ $htmlTable := replace $htmlTable $old $new }}
+{{ $htmlTable | safeHTML }}

From f6e2f4c656cdca7d7c55ad3faa1ef1314db53121 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Mon, 13 Apr 2020 17:55:33 -0700
Subject: [PATCH 04/14] Rewrite Theming docs as Customize section

- Broke up existing theming page into separate pages
- Audited and updated each new docs page (some pages include some TBD sections)
- Update sidenav to reflect changes
- Fix links that pointed to the old Theming page
- Update docs styles to reflect recent changes
- Rewrite some bits in the Migration page
---
 scss/bootstrap.scss                           |   9 +-
 site/assets/scss/_colors.scss                 |  13 +
 site/assets/scss/_content.scss                |   1 +
 site/content/docs/4.3/customize/color.md      | 133 ++++++++++
 site/content/docs/4.3/customize/components.md |  33 +++
 .../docs/4.3/customize/css-variables.md       |  40 +++
 site/content/docs/4.3/customize/optimize.md   |  40 +++
 site/content/docs/4.3/customize/options.md    |  28 ++
 site/content/docs/4.3/customize/overview.md   |  21 ++
 site/content/docs/4.3/customize/sass.md       | 243 ++++++++++++++++++
 .../docs/4.3/getting-started/webpack.md       |   2 +-
 site/content/docs/4.3/migration.md            |  14 +-
 site/content/docs/4.3/utilities/colors.md     |   2 +-
 site/data/sidebar.yml                         |  12 +-
 14 files changed, 577 insertions(+), 14 deletions(-)
 create mode 100644 site/content/docs/4.3/customize/color.md
 create mode 100644 site/content/docs/4.3/customize/components.md
 create mode 100644 site/content/docs/4.3/customize/css-variables.md
 create mode 100644 site/content/docs/4.3/customize/optimize.md
 create mode 100644 site/content/docs/4.3/customize/options.md
 create mode 100644 site/content/docs/4.3/customize/overview.md
 create mode 100644 site/content/docs/4.3/customize/sass.md

diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss
index dcfdc05cee72..f6705344af6c 100644
--- a/scss/bootstrap.scss
+++ b/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
diff --git a/site/assets/scss/_colors.scss b/site/assets/scss/_colors.scss
index fe0bf6c5b63c..911c44c7368b 100644
--- a/site/assets/scss/_colors.scss
+++ b/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; }
diff --git a/site/assets/scss/_content.scss b/site/assets/scss/_content.scss
index 8368f9eb261f..4ba926c90761 100644
--- a/site/assets/scss/_content.scss
+++ b/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;
diff --git a/site/content/docs/4.3/customize/color.md b/site/content/docs/4.3/customize/color.md
new file mode 100644
index 000000000000..bf04525f1b88
--- /dev/null
+++ b/site/content/docs/4.3/customize/color.md
@@ -0,0 +1,133 @@
+---
+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`.
+
+{{< highlight scss >}}
+$theme-colors: (
+  "primary":    $primary,
+  "secondary":  $secondary,
+  "success":    $success,
+  "info":       $info,
+  "warning":    $warning,
+  "danger":     $danger,
+  "light":      $light,
+  "dark":       $dark
+) !default;
+{{< /highlight >}}
+
+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:
+
+{{< highlight scss >}}
+$colors: (
+  "blue": $blue,
+  "indigo": $indigo,
+  "purple": $purple,
+  "pink": $pink,
+  "red": $red,
+  "orange": $orange,
+  "yellow": $yellow,
+  "green": $green,
+  "teal": $teal,
+  "cyan": $cyan,
+  "white": $white,
+  "gray": $gray-600,
+  "gray-dark": $gray-800
+) !default;
+{{< /highlight >}}
+
+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.
diff --git a/site/content/docs/4.3/customize/components.md b/site/content/docs/4.3/customize/components.md
new file mode 100644
index 000000000000..35fb2a7460f5
--- /dev/null
+++ b/site/content/docs/4.3/customize/components.md
@@ -0,0 +1,33 @@
+---
+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 need to modify your `$grid-breakpoints`, your changes will apply to all the loops iterating over that map.
diff --git a/site/content/docs/4.3/customize/css-variables.md b/site/content/docs/4.3/customize/css-variables.md
new file mode 100644
index 000000000000..a78fb21a1d3c
--- /dev/null
+++ b/site/content/docs/4.3/customize/css-variables.md
@@ -0,0 +1,40 @@
+---
+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, breakpoints, and primary font stacks when working in your browser's Inspector, a code sandbox, or general prototyping.
+
+## Available variables
+
+Here are the variables we include (note that the `:root` is required). They're located in our `_root.scss` file.
+
+{{< 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 >}}
+
+## 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(--font-family-sans-serif);
+}
+a {
+  color: var(--blue);
+}
+{{< /highlight >}}
diff --git a/site/content/docs/4.3/customize/optimize.md b/site/content/docs/4.3/customize/optimize.md
new file mode 100644
index 000000000000..1456cce8c7b9
--- /dev/null
+++ b/site/content/docs/4.3/customize/optimize.md
@@ -0,0 +1,40 @@
+---
+layout: docs
+title: Optimize
+description: Keep your projects lean, responsive, and maintainable so you can deliver the best experience and focus on more important jobs.
+group: customize
+toc: true
+---
+
+## Lean Sass imports
+
+When using Sass in your asset pipeline, make sure you optimize Bootstrap by only `@import`ing the components you need. Your largest optimizations will likely come from the `Layout & Components` section of our `bootstrap.scss`.
+
+{{< scss-docs name="import-stack" file="scss/bootstrap.scss" >}}
+
+
+If you're not using a component, comment it out or delete it entirely. For example, if you're not using the carousel, remove that import to save some file size in your compiled CSS. Keep in mind there are some dependencies across Sass imports that may make it more difficult to omit a file.
+
+## Lean JavaScript
+
+Bootstrap's JavaScript includes every component in our primary dist files (`bootstrap.js` and `bootstrap.min.js`), and even our primary dependency (Popper.js) with our bundle files (`bootstrap.bundle.js` and `bootstrap.bundle.min.js`). While you're customizing via Sass, be sure to remove related JavaScript.
+
+## Autoprefixer browserslist.rc
+
+Bootstrap depends on Autoprefixer to automatically add browser prefixes to certain CSS properties. Prefixes are dictated by our `browserslist.rc` file, found in the root of the Bootstrap repo. Customizing this list of browsers and recompiling the Sass will automatically remove some CSS from your compiled CSS, if there are vendor prefixes unique to that browser or version.
+
+## Use Purge CSS
+
+_Help wanted with this section, please consider opening a PR. Thanks!_
+
+## Minify and gzip
+
+Whenever possible, be sure to compress all the code you serve to your visitors. If you're using Bootstrap dist files, try to stick to the minified versions (indicated by the `.min.css` and `.min.js` extensions). If you're building Bootstrap from the source with your own build system, be sure to implement your own minifiers for HTML, CSS, and JS.
+
+## Nonblocking files
+
+_Help wanted with this section, please consider opening a PR. Thanks!_
+
+## Always use https
+
+_Help wanted with this section, please consider opening a PR. Thanks!_
diff --git a/site/content/docs/4.3/customize/options.md b/site/content/docs/4.3/customize/options.md
new file mode 100644
index 000000000000..381722f8505f
--- /dev/null
+++ b/site/content/docs/4.3/customize/options.md
@@ -0,0 +1,28 @@
+---
+layout: docs
+title: Options
+description: Quickly customize Bootstrap with built-in variables to easily toggle global CSS preferences for controlling style and behavior.
+group: customize
+---
+
+Customize Bootstrap with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with `npm run test` as needed.
+
+You can find and customize these variables for key global options in Bootstrap's `scss/_variables.scss` file.
+
+{{< table "table text-left" >}}
+| Variable                       | Values                             | Description                                                                            |
+| ------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------- |
+| `$spacer`                      | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{< docsref "/utilities/spacing" >}}). |
+| `$enable-rounded`              | `true` (default) or `false`        | Enables predefined `border-radius` styles on various components. |
+| `$enable-shadows`              | `true` or `false` (default)        | Enables predefined `box-shadow` styles on various components. |
+| `$enable-gradients`            | `true` or `false` (default)        | Enables predefined gradients via `background-image` styles on various components. |
+| `$enable-transitions`          | `true` (default) or `false`        | Enables predefined `transition`s on various components. |
+| `$enable-reduced-motion`       | `true` (default) or `false`        | Enables the [`prefers-reduced-motion` media query]({{< docsref "/getting-started/accessibility#reduced-motion" >}}), which suppresses certain animations/transitions based on the users' browser/operating system preferences. |
+| `$enable-grid-classes`         | `true` (default) or `false`        | Enables the generation of CSS classes for the grid system (e.g. `.row`, `.col-md-1`, etc.). |
+| `$enable-caret`                | `true` (default) or `false`        | Enables pseudo element caret on `.dropdown-toggle`. |
+| `$enable-button-pointers`      | `true` (default) or `false`        | Add "hand" cursor to non-disabled button elements. |
+| `$enable-rfs`                  | `true` (default)  or `false`       | Globally enables [RFS]({{< docsref "/getting-started/rfs" >}}). |
+| `$enable-validation-icons`     | `true` (default) or `false`        | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
+| `$enable-deprecation-messages` | `true` or `false` (default)        | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
+| `$enable-important-utilities`  | `true` (default) or `false`        | Enables the `!important` suffix in utility classes. |
+{{< /table >}}
diff --git a/site/content/docs/4.3/customize/overview.md b/site/content/docs/4.3/customize/overview.md
new file mode 100644
index 000000000000..23a092c4f107
--- /dev/null
+++ b/site/content/docs/4.3/customize/overview.md
@@ -0,0 +1,21 @@
+---
+layout: docs
+title: Customize
+description: Learn how to theme, customize, and extend Bootstrap with Sass, a boatload of global options, an expansive color system, and more.
+group: customize
+toc: false
+aliases: "/docs/4.3/customize/"
+sections:
+  - title: Sass
+    description: Utilize our source Sass files to take advantage of variables, maps, mixins, and functions.
+  - title: Options
+    description: Customize Bootstrap with built-in variables to easily toggle global CSS preferences.
+  - title: Color
+    description: Learn about and customize the color systems that support the entire toolkit.
+  - title: Components
+    description: Learn how we build nearly all our components responsively and with base and modifier classes.
+  - title: CSS variables
+    description: Use Bootstrap's CSS custom properties for fast and forward-looking design and development.
+  - title: Optimize
+    description: Keep your projects lean, responsive, and maintainable so you can deliver the best experience.
+---
diff --git a/site/content/docs/4.3/customize/sass.md b/site/content/docs/4.3/customize/sass.md
new file mode 100644
index 000000000000..402b75fc5d38
--- /dev/null
+++ b/site/content/docs/4.3/customize/sass.md
@@ -0,0 +1,243 @@
+---
+layout: docs
+title: Sass
+description: Utilize our source Sass files to take advantage of variables, maps, mixins, and functions to help you build faster and customize your project.
+group: customize
+toc: true
+---
+
+Utilize our source Sass files to take advantage of variables, maps, mixins, and more. In our build we've increased the Sass rounding precision to 6 (by default it's 5) to prevent issues with browser rounding.
+
+## File structure
+
+Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you're using a package manager like npm, you'll have a file structure that looks like this:
+
+{{< highlight text >}}
+your-project/
+├── scss
+│   └── custom.scss
+└── node_modules/
+    └── bootstrap
+        ├── js
+        └── scss
+{{< /highlight >}}
+
+If you've downloaded our source files and aren't using a package manager, you'll want to manually setup something similar to that structure, keeping Bootstrap's source files separate from your own.
+
+{{< highlight text >}}
+your-project/
+├── scss
+│   └── custom.scss
+└── bootstrap/
+    ├── js
+    └── scss
+{{< /highlight >}}
+
+## Importing
+
+In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two options: include all of Bootstrap, or pick the parts you need. We encourage the latter, though be aware there are some requirements and dependencies across our components. You also will need to include some JavaScript for our plugins.
+
+{{< highlight scss >}}
+// Custom.scss
+// Option A: Include all of Bootstrap
+
+@import "../node_modules/bootstrap/scss/bootstrap";
+{{< /highlight >}}
+
+{{< highlight scss >}}
+// Custom.scss
+// Option B: Include parts of Bootstrap
+
+// Required
+@import "../node_modules/bootstrap/scss/functions";
+@import "../node_modules/bootstrap/scss/variables";
+@import "../node_modules/bootstrap/scss/mixins";
+
+// Optional
+@import "../node_modules/bootstrap/scss/reboot";
+@import "../node_modules/bootstrap/scss/type";
+@import "../node_modules/bootstrap/scss/images";
+@import "../node_modules/bootstrap/scss/code";
+@import "../node_modules/bootstrap/scss/grid";
+{{< /highlight >}}
+
+With that setup in place, you can begin to modify any of the Sass variables and maps in your `custom.scss`. You can also start to add parts of Bootstrap under the `// Optional` section as needed. We suggest using the full import stack from our `bootstrap.scss` file as your starting point.
+
+## Variable defaults
+
+Every Sass variable in Bootstrap 4 includes the `!default` flag allowing you to override the variable's default value in your own Sass without modifying Bootstrap's source code. Copy and paste variables as needed, modify their values, and remove the `!default` flag. If a variable has already been assigned, then it won't be re-assigned by the default values in Bootstrap.
+
+You will find the complete list of Bootstrap's variables in `scss/_variables.scss`. Some variables are set to `null`, these variables don't output the property unless they are overridden in your configuration.
+
+Variable overrides within the same Sass file can come before or after the default variables. However, when overriding across Sass files, your overrides must come before you import Bootstrap's Sass files.
+
+Here's an example that changes the `background-color` and `color` for the `<body>` when importing and compiling Bootstrap via npm:
+
+{{< highlight scss >}}
+// Your variable overrides
+$body-bg: #000;
+$body-color: #111;
+
+// Bootstrap and its default variables
+@import "../node_modules/bootstrap/scss/bootstrap";
+{{< /highlight >}}
+
+Repeat as necessary for any variable in Bootstrap, including the global options below.
+
+## Maps and loops
+
+Bootstrap 4 includes a handful of Sass maps, key value pairs that make it easier to generate families of related CSS. We use Sass maps for our colors, grid breakpoints, and more. Just like Sass variables, all Sass maps include the `!default` flag and can be overridden and extended.
+
+Some of our Sass maps are merged into empty ones by default. This is done to allow easy expansion of a given Sass map, but comes at the cost of making _removing_ items from a map slightly more difficult.
+
+### Modify map
+
+All variables in the `$theme-colors` map are defined as standalone variables. To modify an existing color in our `$theme-colors` map, add the following to your custom Sass file:
+
+{{< highlight scss >}}
+$primary: #0074d9;
+$danger: #ff4136;
+{{< /highlight >}}
+
+Later on, theses variables are set in Bootstrap's `$theme-colors` map:
+
+{{< highlight scss >}}
+$theme-colors: (
+  "primary": $primary,
+  "danger": $danger
+);
+{{< /highlight >}}
+
+### Add to map
+
+To add a new color to `$theme-colors`, add the new key and value:
+
+{{< highlight scss >}}
+$theme-colors: (
+  "custom-color": #900
+);
+{{< /highlight >}}
+
+### Remove from map
+
+To remove colors from `$theme-colors`, or any other map, use `map-remove`. Be aware you must insert it between our requirements and options:
+
+{{< highlight scss >}}
+// Required
+@import "../node_modules/bootstrap/scss/functions";
+@import "../node_modules/bootstrap/scss/variables";
+@import "../node_modules/bootstrap/scss/mixins";
+
+$theme-colors: map-remove($theme-colors, "info", "light", "dark");
+
+// Optional
+@import "../node_modules/bootstrap/scss/root";
+@import "../node_modules/bootstrap/scss/reboot";
+@import "../node_modules/bootstrap/scss/type";
+...
+{{< /highlight >}}
+
+## Required keys
+
+Bootstrap assumes the presence of some specific keys within Sass maps as we used and extend these ourselves. As you customize the included maps, you may encounter errors where a specific Sass map's key is being used.
+
+For example, we use the `primary`, `success`, and `danger` keys from `$theme-colors` for links, buttons, and form states. Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues. In these instances, you'll need to modify the Sass code that makes use of those values.
+
+## Functions
+
+### Colors
+
+In Bootstrap 5, we've dropped the `color()`, `theme-color()` and `gray()` functions because the values are also available as standalone variables. So instead of using `theme-color("primary")`, you can now just use the `$primary` variable.
+
+{{< highlight scss >}}
+.custom-element {
+  color: $gray-100;
+  background-color: $dark;
+}
+{{< /highlight >}}
+
+We also have a function for getting a particular _level_ of color. Negative level values will lighten the color, while higher levels will darken.
+
+{{< scss-docs name="color-level" file="scss/_functions.scss" >}}
+
+In practice, you'd call the function and pass in two parameters: the name of the color from `$theme-colors` (e.g., primary or danger) and a numeric level.
+
+{{< highlight scss >}}
+.custom-element {
+  color: color-level($primary, -10);
+}
+{{< /highlight >}}
+
+### Color contrast
+
+In order to meet [WCAG 2.0 accessibility standards for color contrast](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html), authors **must** provide [a contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG20/quickref/20160105/Overview.php#visual-audio-contrast-contrast), with very few exceptions.
+
+An additional function we include in Bootstrap is the color contrast function, `color-contrast`. It utilizes the [WCAG 2.0 algorithm](https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests) for calculating contrast thresholds based on [relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance) in a `sRGB` colorspace to automatically return a light (`#fff`) or dark (`#111`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
+
+For example, to generate color swatches from our `$theme-colors` map:
+
+{{< highlight scss >}}
+@each $color, $value in $theme-colors {
+  .swatch-#{$color} {
+    color: color-contrast($value);
+  }
+}
+{{< /highlight >}}
+
+It can also be used for one-off contrast needs:
+
+{{< highlight scss >}}
+.custom-element {
+  color: color-contrast(#000); // returns `color: #fff`
+}
+{{< /highlight >}}
+
+You can also specify a base color with our color map functions:
+
+{{< highlight scss >}}
+.custom-element {
+  color: color-contrast($dark); // returns `color: #fff`
+}
+{{< /highlight >}}
+
+### Escape SVG
+
+We use the `escape-svg` function to escape the `<`, `>` and `#` characters for SVG background images.
+
+### Add and Subtract functions
+
+We use the `add` and `subtract` functions to wrap the CSS `calc` function. The primary purpose of these functions is to avoid errors when a "unitless" `0` value is passed into a `calc` expression. Expressions like `calc(10px - 0)` will return an error in all browsers, despite being mathematically correct.
+
+Example where the calc is valid:
+
+{{< highlight scss >}}
+$border-radius: .25rem;
+$border-width: 1px;
+
+.element {
+  // Output calc(.25rem - 1px) is valid
+  border-radius: calc($border-radius - $border-width);
+}
+
+.element {
+  // Output the same calc(.25rem - 1px) as above
+  border-radius: subtract($border-radius, $border-width);
+}
+{{< /highlight >}}
+
+Example where the calc is invalid:
+
+{{< highlight scss >}}
+$border-radius: .25rem;
+$border-width: 0;
+
+.element {
+  // Output calc(.25rem - 0) is invalid
+  border-radius: calc($border-radius - $border-width);
+}
+
+.element {
+  // Output .25rem
+  border-radius: subtract($border-radius, $border-width);
+}
+{{< /highlight >}}
diff --git a/site/content/docs/4.3/getting-started/webpack.md b/site/content/docs/4.3/getting-started/webpack.md
index f170c1a4d586..10e536bbf2aa 100644
--- a/site/content/docs/4.3/getting-started/webpack.md
+++ b/site/content/docs/4.3/getting-started/webpack.md
@@ -35,7 +35,7 @@ This means that you will have to make sure to add both of them to your `package.
 
 To enjoy the full potential of Bootstrap and customize it to your needs, use the source files as a part of your project's bundling process.
 
-First, create your own `_custom.scss` and use it to override the [built-in custom variables]({{< docsref "/getting-started/theming" >}}). Then, use your main Sass file to import your custom variables, followed by Bootstrap:
+First, create your own `_custom.scss` and use it to override the [built-in custom variables]({{< docsref "/customize/sass" >}}). Then, use your main Sass file to import your custom variables, followed by Bootstrap:
 
 {{< highlight scss >}}
 @import "custom";
diff --git a/site/content/docs/4.3/migration.md b/site/content/docs/4.3/migration.md
index eef9193ac588..44c0421bceeb 100644
--- a/site/content/docs/4.3/migration.md
+++ b/site/content/docs/4.3/migration.md
@@ -42,9 +42,9 @@ Changes to our source Sass files and compiled CSS.
 - Line heights are dropped from several components to simplify our codebase. The `button-size()` and `pagination-size()` do not accept line height parameters anymore. [See #29271](https://github.com/twbs/bootstrap/pull/29271)
 - The `button-variant()` mixin now accepts 3 optional color parameters, for each button state, to override the color provided by `color-contrast()`. By default, these parameters will find which color provides more contrast against the button state's background color with `color-contrast()`.
 - The `button-outline-variant()` mixin now accepts an additional argument, `$active-color`, for setting the button's active state text color. By default, this parameter will find which color provides more contrast against the button's active background color with `color-contrast()`.
-- Ditch the Sass map merges, which makes it easier to remove redundant values. Keep in mind you now have to define all values in the Sass maps like `$theme-colors`. Check out how to deal with Sass maps on the [theming documentation]({{< docsref "/getting-started/theming#maps-and-loops" >}}).
-- `color-yiq()` function is renamed to `color-contrast()` since it's not related to YIQ colorspace anymore — [See #30168](https://github.com/twbs/bootstrap/pull/30168/) — and related variables are renamed alongside:
-  - `$yiq-contrasted-threshold` is renamed `$min-contrast-ratio`,
+- Ditch the Sass map merges, which makes it easier to remove redundant values. Keep in mind you now have to define all values in the Sass maps like `$theme-colors`. Check out how to deal with [Sass maps]({{< docsref "/customize/sass#maps-and-loops" >}}).
+- `color-yiq()` function and related variables are renamed to `color-contrast()` since it's not related to YIQ colorspace anymore. [See #30168.](https://github.com/twbs/bootstrap/pull/30168/)
+  - `$yiq-contrasted-threshold` is renamed `$min-contrast-ratio`.
   - `$yiq-text-dark` and `$yiq-text-light` are respectively renamed `$color-contrast-dark` and `$color-contrast-light`.
 
 ## JavaScript
@@ -54,6 +54,14 @@ Changes to our source and compiled JavaScript files.
 - Dropped jQuery dependency and rewrote plugins to be in regular JavaScript.
 - Removed underscore from public static methods like `_getInstance()` → `getInstance()`.
 
+## Color system
+
+We've updated the color system that powers Bootstrap to improve color contrast and provide a much more extensive set of colors.
+
+- Updated blue and pink base colors (`-500`) to ensure AA contrast.
+- Added new tints and shades for every color, providing nine separate colors for each base color.
+- To support our color system, we've added new custom `tint()` and `shade()` functions to mix our colors appropriately.
+
 ## Grid and layout
 
 Changes to any layout tools and our grid system.
diff --git a/site/content/docs/4.3/utilities/colors.md b/site/content/docs/4.3/utilities/colors.md
index 62a35b059ca5..cef79ab6623f 100644
--- a/site/content/docs/4.3/utilities/colors.md
+++ b/site/content/docs/4.3/utilities/colors.md
@@ -39,7 +39,7 @@ Similar to the contextual text color classes, easily set the background of an el
 
 ## Background gradient
 
-When `$enable-gradients` is set to `true` (default is `false`), you can use `.bg-gradient-` utility classes. [Learn about our Sass options]({{< docsref "/getting-started/theming#sass-options" >}}) to enable these classes and more.
+When `$enable-gradients` is set to `true` (default is `false`), you can use `.bg-gradient-` utility classes. [Learn about our Sass options]({{< docsref "/customize/sass" >}}) to enable these classes and more.
 
 {{< markdown >}}
 {{< colors.inline >}}
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index b8ea627ee351..4864085c0ff3 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -5,13 +5,21 @@
     - title: Contents
     - title: Browsers & devices
     - title: JavaScript
-    - title: Theming
     - title: Build tools
-    # - title: Best practices # TODO: Write this content
     - title: Webpack
     - title: Accessibility
     - title: RFS
 
+- title: Customize
+  pages:
+    - title: Overview
+    - title: Sass
+    - title: Options
+    - title: Color
+    - title: Components
+    - title: CSS variables
+    - title: Optimize
+
 - title: Layout
   pages:
     - title: Breakpoints

From cbe8ad0bf8ff073f1bf7d574ab5e3fda74eef004 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Mon, 13 Apr 2020 20:31:36 -0700
Subject: [PATCH 05/14] Add overview intro to the Customize section

---
 site/content/docs/4.3/customize/overview.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/site/content/docs/4.3/customize/overview.md b/site/content/docs/4.3/customize/overview.md
index 23a092c4f107..a69ea1b1fc9a 100644
--- a/site/content/docs/4.3/customize/overview.md
+++ b/site/content/docs/4.3/customize/overview.md
@@ -19,3 +19,16 @@ sections:
   - title: Optimize
     description: Keep your projects lean, responsive, and maintainable so you can deliver the best experience.
 ---
+
+## Overview
+
+There are multiple ways to customize Bootstrap. Your best path can depend on your project, the complexity of your build tools, the version of Bootstrap you're using, browser support, and more. Our two preferred methods are:
+
+1. Using Bootstrap [via package manager]({{< docsref "/getting-started/download#package-managers" >}}) so you can use and extend our source files.
+2. Using Bootstrap's compiled distribution files or the [Bootstrap CDN]({{< docsref "/getting-started/download#bootstrapcdn" >}}) so you can add onto or override Bootstrap's styles.
+
+While we cannot go into details here on how to use every package manager, we can give some guidance on [using Bootstrap with your own Sass compiler]({{< docsref "/customize/sass" >}}).
+
+For those who want to use the distribution files, review the [getting started page]({{< docsref "/getting-started/introduction" >}}) for how to include those files and an example HTML page. From there, consult the docs for the layout, components, and behaviors you'd like to use.
+
+As you familiarize yourself with Bootstrap, continue exploring this section for more details on how to utilize our global options, making use of and changing our color system, how we build our components, how to use our growing list of CSS custom properties, and how to optimize your code when building with Bootstrap.

From cab56abd0822f238fe0cd6fbfbdd33f0a9c0a1cd Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Tue, 14 Apr 2020 08:54:29 -0700
Subject: [PATCH 06/14] Add more context to customizing components

---
 site/content/docs/4.3/customize/components.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/site/content/docs/4.3/customize/components.md b/site/content/docs/4.3/customize/components.md
index 35fb2a7460f5..7ca3920ad9bf 100644
--- a/site/content/docs/4.3/customize/components.md
+++ b/site/content/docs/4.3/customize/components.md
@@ -30,4 +30,8 @@ These Sass loops aren't limited to color maps, either. You can also generate res
 
 {{< scss-docs name="responsive-breakpoints" file="scss/_dropdown.scss" >}}
 
-Should you need to modify your `$grid-breakpoints`, your changes will apply to all the loops iterating over that map.
+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" >}}).

From 88490fe81d1cc7b9da16c2a60405f8c86c19d2f1 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Tue, 14 Apr 2020 11:04:16 -0700
Subject: [PATCH 07/14] Use scss-docs for color maps

---
 scss/_variables.scss                     |  4 +++
 site/content/docs/4.3/customize/color.md | 31 ++----------------------
 2 files changed, 6 insertions(+), 29 deletions(-)

diff --git a/scss/_variables.scss b/scss/_variables.scss
index a3d1df747b65..bef7c3841029 100644
--- a/scss/_variables.scss
+++ b/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;
diff --git a/site/content/docs/4.3/customize/color.md b/site/content/docs/4.3/customize/color.md
index bf04525f1b88..9e36bc976015 100644
--- a/site/content/docs/4.3/customize/color.md
+++ b/site/content/docs/4.3/customize/color.md
@@ -22,18 +22,7 @@ We use a subset of all colors to create a smaller color palette for generating c
 
 All these colors are available as a Sass map, `$theme-colors`.
 
-{{< highlight scss >}}
-$theme-colors: (
-  "primary":    $primary,
-  "secondary":  $secondary,
-  "success":    $success,
-  "info":       $info,
-  "warning":    $warning,
-  "danger":     $danger,
-  "light":      $light,
-  "dark":       $dark
-) !default;
-{{< /highlight >}}
+{{< 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.
 
@@ -98,23 +87,7 @@ Bootstrap's source Sass files include three maps to help you quickly and easily
 
 Within `scss/_variables.scss`, you'll find Bootstrap's color variables and Sass map. Here's an example of the `$colors` Sass map:
 
-{{< highlight scss >}}
-$colors: (
-  "blue": $blue,
-  "indigo": $indigo,
-  "purple": $purple,
-  "pink": $pink,
-  "red": $red,
-  "orange": $orange,
-  "yellow": $yellow,
-  "green": $green,
-  "teal": $teal,
-  "cyan": $cyan,
-  "white": $white,
-  "gray": $gray-600,
-  "gray-dark": $gray-800
-) !default;
-{{< /highlight >}}
+{{< 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.
 

From 1e3672418ab495fbee0f1de8f67d1d12805b4a9a Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Wed, 15 Apr 2020 17:11:16 -0700
Subject: [PATCH 08/14] pull in latest from old theming page

---
 site/content/docs/4.3/customize/css-variables.md | 8 +++++---
 site/content/docs/4.3/customize/options.md       | 3 ++-
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/site/content/docs/4.3/customize/css-variables.md b/site/content/docs/4.3/customize/css-variables.md
index a78fb21a1d3c..94989c3f1a2c 100644
--- a/site/content/docs/4.3/customize/css-variables.md
+++ b/site/content/docs/4.3/customize/css-variables.md
@@ -6,7 +6,9 @@ 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, breakpoints, and primary font stacks when working in your browser's Inspector, a code sandbox, or general prototyping.
+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.**
 
 ## Available variables
 
@@ -32,9 +34,9 @@ CSS variables offer similar flexibility to Sass's variables, but without the nee
 
 {{< highlight css >}}
 body {
-  font: 1rem/1.5 var(--font-family-sans-serif);
+  font: 1rem/1.5 var(--bs-font-sans-serif);
 }
 a {
-  color: var(--blue);
+  color: var(--bs-blue);
 }
 {{< /highlight >}}
diff --git a/site/content/docs/4.3/customize/options.md b/site/content/docs/4.3/customize/options.md
index 381722f8505f..ed0a19210da2 100644
--- a/site/content/docs/4.3/customize/options.md
+++ b/site/content/docs/4.3/customize/options.md
@@ -21,8 +21,9 @@ You can find and customize these variables for key global options in Bootstrap's
 | `$enable-grid-classes`         | `true` (default) or `false`        | Enables the generation of CSS classes for the grid system (e.g. `.row`, `.col-md-1`, etc.). |
 | `$enable-caret`                | `true` (default) or `false`        | Enables pseudo element caret on `.dropdown-toggle`. |
 | `$enable-button-pointers`      | `true` (default) or `false`        | Add "hand" cursor to non-disabled button elements. |
-| `$enable-rfs`                  | `true` (default)  or `false`       | Globally enables [RFS]({{< docsref "/getting-started/rfs" >}}). |
+| `$enable-rfs`                  | `true` (default) or `false`        | Globally enables [RFS]({{< docsref "/getting-started/rfs" >}}). |
 | `$enable-validation-icons`     | `true` (default) or `false`        | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
+| `$enable-negative-margins`     | `true` or `false` (default)        | Enables the generation of [negative margin utilities]({{< docsref "/utilities/spacing#negative-margin" >}}). |
 | `$enable-deprecation-messages` | `true` or `false` (default)        | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
 | `$enable-important-utilities`  | `true` (default) or `false`        | Enables the `!important` suffix in utility classes. |
 {{< /table >}}

From 81417a2fc69ed831a68a1a1fd1853346d2cbb46a Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Wed, 15 Apr 2020 17:46:20 -0700
Subject: [PATCH 09/14] wordsmithing

---
 site/content/docs/4.3/customize/overview.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/site/content/docs/4.3/customize/overview.md b/site/content/docs/4.3/customize/overview.md
index a69ea1b1fc9a..5ccbd68d6c20 100644
--- a/site/content/docs/4.3/customize/overview.md
+++ b/site/content/docs/4.3/customize/overview.md
@@ -22,7 +22,9 @@ sections:
 
 ## Overview
 
-There are multiple ways to customize Bootstrap. Your best path can depend on your project, the complexity of your build tools, the version of Bootstrap you're using, browser support, and more. Our two preferred methods are:
+There are multiple ways to customize Bootstrap. Your best path can depend on your project, the complexity of your build tools, the version of Bootstrap you're using, browser support, and more.
+
+Our two preferred methods are:
 
 1. Using Bootstrap [via package manager]({{< docsref "/getting-started/download#package-managers" >}}) so you can use and extend our source files.
 2. Using Bootstrap's compiled distribution files or the [Bootstrap CDN]({{< docsref "/getting-started/download#bootstrapcdn" >}}) so you can add onto or override Bootstrap's styles.

From cb4aff6eac63083bc22962ba0105395653e1a490 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 24 Apr 2020 13:13:35 -0700
Subject: [PATCH 10/14] Update shortcode usage

---
 site/content/docs/4.3/customize/options.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/site/content/docs/4.3/customize/options.md b/site/content/docs/4.3/customize/options.md
index ed0a19210da2..5bfa42e28334 100644
--- a/site/content/docs/4.3/customize/options.md
+++ b/site/content/docs/4.3/customize/options.md
@@ -9,7 +9,7 @@ Customize Bootstrap with our built-in custom variables file and easily toggle gl
 
 You can find and customize these variables for key global options in Bootstrap's `scss/_variables.scss` file.
 
-{{< table "table text-left" >}}
+{{< bs-table "table text-left" >}}
 | Variable                       | Values                             | Description                                                                            |
 | ------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------- |
 | `$spacer`                      | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{< docsref "/utilities/spacing" >}}). |
@@ -26,4 +26,4 @@ You can find and customize these variables for key global options in Bootstrap's
 | `$enable-negative-margins`     | `true` or `false` (default)        | Enables the generation of [negative margin utilities]({{< docsref "/utilities/spacing#negative-margin" >}}). |
 | `$enable-deprecation-messages` | `true` or `false` (default)        | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
 | `$enable-important-utilities`  | `true` (default) or `false`        | Enables the `!important` suffix in utility classes. |
-{{< /table >}}
+{{< /bs-table >}}

From 78261846ddb16b0e0da52b69e25a398a909674fa Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 24 Apr 2020 15:29:28 -0700
Subject: [PATCH 11/14] Add example of a custom component using docs callouts

---
 site/content/docs/4.3/customize/components.md | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/site/content/docs/4.3/customize/components.md b/site/content/docs/4.3/customize/components.md
index 7ca3920ad9bf..62a1d401f400 100644
--- a/site/content/docs/4.3/customize/components.md
+++ b/site/content/docs/4.3/customize/components.md
@@ -35,3 +35,43 @@ Should you modify your `$grid-breakpoints`, your changes will apply to all the l
 {{< 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 >}}

From 7ba43e3361ab5f8347b508ce02fbeb85f60cd412 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 24 Apr 2020 15:33:15 -0700
Subject: [PATCH 12/14] Include code snippet for lean JS section

---
 site/content/docs/4.3/customize/optimize.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/site/content/docs/4.3/customize/optimize.md b/site/content/docs/4.3/customize/optimize.md
index 1456cce8c7b9..8a3b7e2be37c 100644
--- a/site/content/docs/4.3/customize/optimize.md
+++ b/site/content/docs/4.3/customize/optimize.md
@@ -19,6 +19,20 @@ If you're not using a component, comment it out or delete it entirely. For examp
 
 Bootstrap's JavaScript includes every component in our primary dist files (`bootstrap.js` and `bootstrap.min.js`), and even our primary dependency (Popper.js) with our bundle files (`bootstrap.bundle.js` and `bootstrap.bundle.min.js`). While you're customizing via Sass, be sure to remove related JavaScript.
 
+For instance, assuming you're using your own JavaScript bundler like Webpack or Rollup, you'd only import the JavaScript you plan on using. In the example below, we show how to just include our modal JavaScript:
+
+```js
+// Import just what we need
+
+// If you're importing tooltips or popovers, be sure to include the Popper.js dependency
+// import "../../node_modules/popper.js/dist/popper.min.js";
+
+import "../../node_modules/bootstrap/js/dist/util.js";
+import "../../node_modules/bootstrap/js/dist/modal.js";
+```
+
+This way, you're not including any JavaScript you don't intend to use for components like buttons, carousels, and tooltips.
+
 ## Autoprefixer browserslist.rc
 
 Bootstrap depends on Autoprefixer to automatically add browser prefixes to certain CSS properties. Prefixes are dictated by our `browserslist.rc` file, found in the root of the Bootstrap repo. Customizing this list of browsers and recompiling the Sass will automatically remove some CSS from your compiled CSS, if there are vendor prefixes unique to that browser or version.

From ac58c25dc8b65928ac817b8a2bf7c0e46a58de97 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 24 Apr 2020 15:38:39 -0700
Subject: [PATCH 13/14] Update CSS variables docs

- Rename available vars section to root vars and mention they're globally available
- Add new component vars section and link to table docs for WIP example
---
 site/content/docs/4.3/customize/css-variables.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/site/content/docs/4.3/customize/css-variables.md b/site/content/docs/4.3/customize/css-variables.md
index 94989c3f1a2c..fecabbf711cd 100644
--- a/site/content/docs/4.3/customize/css-variables.md
+++ b/site/content/docs/4.3/customize/css-variables.md
@@ -10,9 +10,9 @@ Bootstrap includes around two dozen [CSS custom properties (variables)](https://
 
 **All our custom properties are prefixed with `bs-` to avoid conflicts with third party CSS.**
 
-## Available variables
+## Root variables
 
-Here are the variables we include (note that the `:root` is required). They're located in our `_root.scss` file.
+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 >}}
@@ -28,6 +28,12 @@ Here are the variables we include (note that the `:root` is required). They're l
 {{< /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.

From 28cb1ff2b23253293601c51aff434c39b461025e Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Fri, 24 Apr 2020 15:42:49 -0700
Subject: [PATCH 14/14] Fill in some unusedcss section links

---
 site/content/docs/4.3/customize/optimize.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/site/content/docs/4.3/customize/optimize.md b/site/content/docs/4.3/customize/optimize.md
index 8a3b7e2be37c..eea4a7a3b86f 100644
--- a/site/content/docs/4.3/customize/optimize.md
+++ b/site/content/docs/4.3/customize/optimize.md
@@ -37,10 +37,17 @@ This way, you're not including any JavaScript you don't intend to use for compon
 
 Bootstrap depends on Autoprefixer to automatically add browser prefixes to certain CSS properties. Prefixes are dictated by our `browserslist.rc` file, found in the root of the Bootstrap repo. Customizing this list of browsers and recompiling the Sass will automatically remove some CSS from your compiled CSS, if there are vendor prefixes unique to that browser or version.
 
-## Use Purge CSS
+## Unused CSS
 
 _Help wanted with this section, please consider opening a PR. Thanks!_
 
+While we don't have a prebuilt example for using [PurgeCSS](https://github.com/FullHuman/purgecss) with Bootstrap, there are some helpful articles and walkthroughs that the community has written. Here are some options:
+
+- https://medium.com/dwarves-foundation/remove-unused-css-styles-from-bootstrap-using-purgecss-88395a2c5772
+- https://lukencode.com/2018/07/29/automatically-removeunused-css-from-bootstrap-or-other-frameworks/
+
+Lastly, this [CSS Tricks article on unused CSS](https://css-tricks.com/how-do-you-remove-unused-css-from-a-site/) shows how to use PurgeCSS and other similar tools.
+
 ## Minify and gzip
 
 Whenever possible, be sure to compress all the code you serve to your visitors. If you're using Bootstrap dist files, try to stick to the minified versions (indicated by the `.min.css` and `.min.js` extensions). If you're building Bootstrap from the source with your own build system, be sure to implement your own minifiers for HTML, CSS, and JS.