Merge branch 'main' into jo-docs-thanks-pagejo-docs-thanks-page

5 files changed, 89 insertions, 13 deletions

diff --git a/site/content/docs/5.0/customize/color.md b/site/content/docs/5.0/customize/color.md
index 452b3d77c..7d1615589 100644
--- a/site/content/docs/5.0/customize/color.md
+++ b/site/content/docs/5.0/customize/color.md
@@ -105,4 +105,4 @@ Here's how you can use these in your Sass:
 }
 ```
 
-[Color utility classes]({{< docsref "/utilities/colors" >}}) are also available for setting `color` and `background-color` using the `500` color values.
+[Color]({{< docsref "/utilities/colors" >}}) and [background]({{< docsref "/utilities/background" >}}) utility classes are also available for setting `color` and `background-color` using the `500` color values.
diff --git a/site/content/docs/5.0/customize/optimize.md b/site/content/docs/5.0/customize/optimize.md
index fbf3f6b05..0911667d0 100644
--- a/site/content/docs/5.0/customize/optimize.md
+++ b/site/content/docs/5.0/customize/optimize.md
@@ -72,8 +72,21 @@ Whenever possible, be sure to compress all the code you serve to your visitors.
 
 ## Nonblocking files
 
-_Help wanted with this section, please consider opening a PR. Thanks!_
+While minifying and using compression might seem like enough, making your files nonblocking ones is also a big step in making your site well-optimized and fast enough.
 
-## Always use https
+If you are using a [Lighthouse](https://developers.google.com/web/tools/lighthouse/) plugin in Google Chrome, you may have stumbled over FCP. [The First Contentful Paint](https://web.dev/fcp/) metric measures the time from when the page starts loading to when any part of the page's content is rendered on the screen.
 
-_Help wanted with this section, please consider opening a PR. Thanks!_
+You can improve FCP by deferring non-critical JavaScript or CSS. What does that mean? Simply, JavaScript or stylesheets that don't need to be present on the first paint of your page should be marked with `async` or `defer` attributes.
+
+This ensures that the less important resources are loaded later and not blocking the first paint. On the other hand, critical resources can be included as inline scripts or styles.
+
+If you want to learn more about this, there are already a lot of great articles about it:
+
+- <https://web.dev/render-blocking-resources/>
+- <https://web.dev/defer-non-critical-css/>
+
+## Always use HTTPS
+
+Your website should only be available over HTTPS connections in production. HTTPS improves the security, privacy, and availability of all sites, and [there is no such thing as non-sensitive web traffic](https://https.cio.gov/everything/). The steps to configure your website to be served exclusively over HTTPS vary widely depending on your architecture and web hosting provider, and thus are beyond the scope of these docs.
+
+Sites served over HTTPS should also access all stylesheets, scripts, and other assets over HTTPS connections. Otherwise, you'll be sending users [mixed active content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content), leading to potential vulnerabilities where a site can be compromised by altering a dependency. This can lead to security issues and in-browser warnings displayed to users. Whether you're getting Bootstrap from a CDN or serving it yourself, ensure that you only access it over HTTPS connections.
diff --git a/site/content/docs/5.0/customize/options.md b/site/content/docs/5.0/customize/options.md
index d818d6d4a..0d846270b 100644
--- a/site/content/docs/5.0/customize/options.md
+++ b/site/content/docs/5.0/customize/options.md
@@ -14,7 +14,7 @@ You can find and customize these variables for key global options in Bootstrap's
 | ------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------- |
 | `$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-shadows`              | `true` or `false` (default)        | Enables predefined decorative `box-shadow` styles on various components. Does not affect `box-shadow`s used for focus states. |
 | `$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. |
@@ -24,6 +24,6 @@ You can find and customize these variables for key global options in Bootstrap's
 | `$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-deprecation-messages` | `true` (default) or `false`        | Set to `false` to hide warnings when using any of the deprecated mixins and functions that are planned to be removed in `v6`. |
 | `$enable-important-utilities`  | `true` (default) or `false`        | Enables the `!important` suffix in utility classes. |
 {{< /bs-table >}}
diff --git a/site/content/docs/5.0/customize/overview.md b/site/content/docs/5.0/customize/overview.md
index 16847589e..07431575a 100644
--- a/site/content/docs/5.0/customize/overview.md
+++ b/site/content/docs/5.0/customize/overview.md
@@ -34,3 +34,18 @@ While we cannot go into details here on how to use every package manager, we can
 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.
+
+## CSPs and embedded SVGs
+
+Several Bootstrap components include embedded SVGs in our CSS to style components consistently and easily across browsers and devices. **For organizations with more strict <abbr title="Content Security Policy">CSP</abbr> configurations**, we've documented all instances of our embedded SVGs (all of which are applied via `background-image`) so you can more thoroughly review your options.
+
+- [Accordion]({{< docsref "/components/accordion" >}})
+- [Close button]({{< docsref "/components/close-button" >}}) (used in alerts and modals)
+- [Form checkboxes and radio buttons]({{< docsref "/forms/checks-radios" >}})
+- [Form switches]({{< docsref "/forms/checks-radios#switches" >}})
+- [Form validation icons]({{< docsref "/forms/validation#server-side" >}})
+- [Select menus]({{< docsref "/forms/select" >}})
+- [Carousel controls]({{< docsref "/components/carousel#with-controls" >}})
+- [Navbar toggle buttons]({{< docsref "/components/navbar#responsive-behaviors" >}})
+
+Based on [community conversation](https://github.com/twbs/bootstrap/issues/25394), some options for addressing this in your own codebase include replacing the URLs with locally hosted assets, removing the images and using inline images (not possible in all components), and modifying your CSP. Our recommendation is to carefully review your own security policies and decide on a best path forward, if necessary.
diff --git a/site/content/docs/5.0/customize/sass.md b/site/content/docs/5.0/customize/sass.md
index 46b822525..98a6429fb 100644
--- a/site/content/docs/5.0/customize/sass.md
+++ b/site/content/docs/5.0/customize/sass.md
@@ -6,7 +6,7 @@ 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.
+Utilize our source Sass files to take advantage of variables, maps, mixins, and more.
 
 ## File structure
 
@@ -41,25 +41,35 @@ In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two
 // Custom.scss
 // Option A: Include all of Bootstrap
 
+// Include any default variable overrides here (though functions won't be available)
+
 @import "../node_modules/bootstrap/scss/bootstrap";
+
+// Then add additional custom code here
 ```
 
 ```scss
 // Custom.scss
 // Option B: Include parts of Bootstrap
 
-// Required
+// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
 @import "../node_modules/bootstrap/scss/functions";
+
+// 2. Include any default variable overrides here
+
+// 3. Include remainder of required Bootstrap stylesheets
 @import "../node_modules/bootstrap/scss/variables";
 @import "../node_modules/bootstrap/scss/mixins";
 
-// Optional
+// 4. Include any optional Bootstrap components as you like
 @import "../node_modules/bootstrap/scss/root";
 @import "../node_modules/bootstrap/scss/reboot";
 @import "../node_modules/bootstrap/scss/type";
 @import "../node_modules/bootstrap/scss/images";
 @import "../node_modules/bootstrap/scss/containers";
 @import "../node_modules/bootstrap/scss/grid";
+
+// 5. Add additional custom code here
 ```
 
 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.
@@ -70,21 +80,37 @@ Every Sass variable in Bootstrap includes the `!default` flag allowing you to ov
 
 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.
+Variable overrides must come after our functions, variables, and mixins are imported, but before the rest of the imports.
 
 Here's an example that changes the `background-color` and `color` for the `<body>` when importing and compiling Bootstrap via npm:
 
 ```scss
-// Your variable overrides
+// Required
+@import "../node_modules/bootstrap/scss/functions";
+
+// Default variable overrides
 $body-bg: #000;
 $body-color: #111;
 
+// Required
+@import "../node_modules/bootstrap/scss/variables";
+@import "../node_modules/bootstrap/scss/mixins";
+
 // Bootstrap and its default variables
-@import "../node_modules/bootstrap/scss/bootstrap";
+
+// Optional Bootstrap components here
+@import "../node_modules/bootstrap/scss/root";
+@import "../node_modules/bootstrap/scss/reboot";
+@import "../node_modules/bootstrap/scss/type";
+// etc
 ```
 
 Repeat as necessary for any variable in Bootstrap, including the global options below.
 
+{{< callout info >}}
+{{< partial "callout-info-npm-starter.md" >}}
+{{< /callout >}}
+
 ## Maps and loops
 
 Bootstrap 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.
@@ -139,7 +165,7 @@ $theme-colors: map-remove($theme-colors, "info", "light", "dark");
 @import "../node_modules/bootstrap/scss/root";
 @import "../node_modules/bootstrap/scss/reboot";
 @import "../node_modules/bootstrap/scss/type";
-...
+// etc
 ```
 
 ## Required keys
@@ -250,3 +276,25 @@ $border-width: 0;
   border-radius: subtract($border-radius, $border-width);
 }
 ```
+
+## Mixins
+
+Our `scss/mixins/` directory has a ton of mixins that power parts of Bootstrap and can also be used across your own project.
+
+### Color schemes
+
+A shorthand mixin for the `prefers-color-scheme` media query is available with support for `light`, `dark`, and custom color schemes.
+
+{{< scss-docs name="mixin-color-scheme" file="scss/mixins/_color-scheme.scss" >}}
+
+```scss
+.custom-element {
+  @include color-scheme(dark) {
+    // Insert dark mode styles here
+  }
+
+  @include color-scheme(custom-named-scheme) {
+    // Insert custom color scheme styles here
+  }
+}
+```