Add Sass variable for prefers-reduced-motion, add callout to affected components (#27581)

* Tweak the accessibility/reduced motion text

include mention of carousel slides, remove the (now inaccurate, as Firefox 63 includes it too) mention that support is limited to Safari/macOS

xref https://github.com/twbs/bootstrap/issues/27525

* Add new callout for reduced motion

* Add variable to control prefers-reduced-motion media query support

* Add callout about prefers-reduced-motion to all components currently using animation which are affected

11 files changed, 32 insertions, 12 deletions

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 157ddbab2..eb9bdc682 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -107,15 +107,16 @@ $yiq-text-light:            $white !default;
 //
 // 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-hover-media-query:  false !default; // Deprecated, no longer affects any compiled CSS
-$enable-grid-classes:       true !default;
-$enable-print-styles:       true !default;
-$enable-validation-icons:   true !default;
+$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-hover-media-query:                    false !default; // Deprecated, no longer affects any compiled CSS
+$enable-grid-classes:                         true !default;
+$enable-print-styles:                         true !default;
+$enable-validation-icons:                     true !default;
 
 
 // Spacing
diff --git a/scss/mixins/_transition.scss b/scss/mixins/_transition.scss
index a457b6bdb..485f76c76 100644
--- a/scss/mixins/_transition.scss
+++ b/scss/mixins/_transition.scss
@@ -8,7 +8,9 @@
     }
   }
 
-  @media screen and (prefers-reduced-motion: reduce) {
-    transition: none;
+  @if $enable-prefers-reduced-motion-media-query {
+    @media screen and (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
   }
 }
diff --git a/site/_includes/callout-info-prefersreducedmotion.md b/site/_includes/callout-info-prefersreducedmotion.md
new file mode 100644
index 000000000..9c3090376
--- /dev/null
+++ b/site/_includes/callout-info-prefersreducedmotion.md
@@ -0,0 +1,4 @@
+{% capture callout %}
+The animation effect of this component is dependent on the `prefers-reduced-motion` media query. See the [reduced motion section of our accessibility documentation]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/accessibility/#reduced-motion).
+{% endcapture %}
+{% include callout.html content=callout type="info" %}
diff --git a/site/docs/4.1/components/carousel.md b/site/docs/4.1/components/carousel.md
index b568a02cd..8ba5c07ea 100644
--- a/site/docs/4.1/components/carousel.md
+++ b/site/docs/4.1/components/carousel.md
@@ -12,6 +12,8 @@ The carousel is a slideshow for cycling through a series of content, built with
 
 In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibility/) is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.).
 
+{% include callout-info-prefersreducedmotion.md %}
+
 Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards.
 
 Lastly, if you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
diff --git a/site/docs/4.1/components/collapse.md b/site/docs/4.1/components/collapse.md
index 6ede6e4b5..59faa7331 100644
--- a/site/docs/4.1/components/collapse.md
+++ b/site/docs/4.1/components/collapse.md
@@ -10,6 +10,8 @@ toc: true
 
 The collapse JavaScript plugin is used to show and hide content. Buttons or anchors are used as triggers that are mapped to specific elements you toggle. Collapsing an element will animate the `height` from its current value to `0`. Given how CSS handles animations, you cannot use `padding` on a `.collapse` element. Instead, use the class as an independent wrapping element.
 
+{% include callout-info-prefersreducedmotion.md %}
+
 ## Example
 
 Click the buttons below to show and hide another element via class changes:
diff --git a/site/docs/4.1/components/modal.md b/site/docs/4.1/components/modal.md
index a29347b6f..86996ecda 100644
--- a/site/docs/4.1/components/modal.md
+++ b/site/docs/4.1/components/modal.md
@@ -23,6 +23,8 @@ $('#myModal').on('shown.bs.modal', function () {
 })
 {% endhighlight %}
 
+{% include callout-info-prefersreducedmotion.md %}
+
 Keep reading for demos and usage guidelines.
 
 ## Examples
diff --git a/site/docs/4.1/components/navbar.md b/site/docs/4.1/components/navbar.md
index d56843691..61c807114 100644
--- a/site/docs/4.1/components/navbar.md
+++ b/site/docs/4.1/components/navbar.md
@@ -17,6 +17,8 @@ Here's what you need to know before getting started with the navbar:
 - Navbars are hidden by default when printing. Force them to be printed by adding `.d-print` to the `.navbar`. See the [display]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/display/) utility class.
 - Ensure accessibility by using a `<nav>` element or, if using a more generic element such as a `<div>`, add a `role="navigation"` to every navbar to explicitly identify it as a landmark region for users of assistive technologies.
 
+{% include callout-info-prefersreducedmotion.md %}
+
 Read on for an example and list of supported sub-components.
 
 ## Supported content
diff --git a/site/docs/4.1/components/popovers.md b/site/docs/4.1/components/popovers.md
index 825ee3127..f55826d7c 100644
--- a/site/docs/4.1/components/popovers.md
+++ b/site/docs/4.1/components/popovers.md
@@ -21,6 +21,8 @@ Things to know when using the popover plugin:
 - When triggered from anchors that wrap across multiple lines, popovers will be centered between the anchors' overall width. Use `.text-nowrap` on your `<a>`s to avoid this behavior.
 - Popovers must be hidden before their corresponding elements have been removed from the DOM.
 
+{% include callout-info-prefersreducedmotion.md %}
+
 Keep reading to see how popovers work with some examples.
 
 ## Example: Enable popovers everywhere
diff --git a/site/docs/4.1/components/tooltips.md b/site/docs/4.1/components/tooltips.md
index 714236531..aa3ebe077 100644
--- a/site/docs/4.1/components/tooltips.md
+++ b/site/docs/4.1/components/tooltips.md
@@ -20,6 +20,8 @@ Things to know when using the tooltip plugin:
 - When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use `white-space: nowrap;` on your `<a>`s to avoid this behavior.
 - Tooltips must be hidden before their corresponding elements have been removed from the DOM.
 
+{% include callout-info-prefersreducedmotion.md %}
+
 Got all that? Great, let's see how they work with some examples.
 
 ## Example: Enable tooltips everywhere
diff --git a/site/docs/4.1/getting-started/accessibility.md b/site/docs/4.1/getting-started/accessibility.md
index d300a9ba9..edfe914df 100644
--- a/site/docs/4.1/getting-started/accessibility.md
+++ b/site/docs/4.1/getting-started/accessibility.md
@@ -45,7 +45,7 @@ For visually hidden interactive controls, such as traditional "skip" links, `.sr
 
 ### Reduced motion
 
-Bootstrap includes support for the [`prefers-reduced-motion` media feature](https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-motion). In browsers/environments that allow the user to specify their preference for reduced motion, most CSS transition effects in Bootstrap (for instance, when a modal dialog is opened or closed) will be disabled. Currently, support is limited to Safari on macOS and iOS.
+Bootstrap includes support for the [`prefers-reduced-motion` media feature](https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-motion). In browsers/environments that allow the user to specify their preference for reduced motion, most CSS transition effects in Bootstrap (for instance, when a modal dialog is opened or closed, or the sliding animation in carousels) will be disabled.
 
 ## Additional resources
 
diff --git a/site/docs/4.1/getting-started/theming.md b/site/docs/4.1/getting-started/theming.md
index 15bea40c4..964cb0bee 100644
--- a/site/docs/4.1/getting-started/theming.md
+++ b/site/docs/4.1/getting-started/theming.md
@@ -237,6 +237,7 @@ You can find and customize these variables for key global options in Bootstrap's
 | `$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]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/accessibility/#reduced-motion), which suppresses certain animations/transitions based on the users' browser/operating system preferences. |
 | `$enable-hover-media-query` | `true` or `false` (default)        | **Deprecated** |
 | `$enable-grid-classes`      | `true` (default) or `false`        | Enables the generation of CSS classes for the grid system (e.g., `.container`, `.row`, `.col-md-1`, etc.). |
 | `$enable-caret`             | `true` (default) or `false`        | Enables pseudo element caret on `.dropdown-toggle`. |