Responsive font size implementation (#23816)

14 files changed, 43 insertions, 58 deletions

diff --git a/site/docs/4.2/assets/scss/_ads.scss b/site/docs/4.2/assets/scss/_ads.scss
index c207f1682f..0c08025c25 100644
--- a/site/docs/4.2/assets/scss/_ads.scss
+++ b/site/docs/4.2/assets/scss/_ads.scss
@@ -11,7 +11,7 @@
   padding: 15px 15px 15px 160px;
   margin: 2rem 0;
   overflow: hidden;
-  font-size: 13px;
+  @include font-size(.8125rem);
   line-height: 1.4;
   text-align: left;
   background-color: rgba(0, 0, 0, .05);
diff --git a/site/docs/4.2/assets/scss/_algolia.scss b/site/docs/4.2/assets/scss/_algolia.scss
index e523dec8ef..23781da12a 100644
--- a/site/docs/4.2/assets/scss/_algolia.scss
+++ b/site/docs/4.2/assets/scss/_algolia.scss
@@ -47,7 +47,7 @@
   .algolia-docsearch-suggestion--category-header {
     padding: .125rem 1rem !important;
     margin-top: 0 !important;
-    font-size: .875rem !important;
+    @include font-size(.875rem, true);
     font-weight: 600 !important;
     color: $bd-purple-bright !important;
     border-bottom: 0 !important;
@@ -68,7 +68,7 @@
 
   .algolia-docsearch-suggestion--subcategory-inline {
     display: block !important;
-    font-size: .875rem;
+    @include font-size(.875rem);
     color: $gray-700;
 
     &::after {
@@ -107,7 +107,7 @@
   .algolia-docsearch-suggestion--title {
     display: block;
     margin-bottom: 0 !important;
-    font-size: .875rem !important;
+    @include font-size(.875rem, true);
     font-weight: 400 !important;
   }
 
@@ -115,7 +115,7 @@
     flex: 0 0 100%;
     max-width: 100%;
     padding: .2rem 0;
-    font-size: .8125rem !important;
+    @include font-size(.8125rem, true);
     font-weight: 400;
     line-height: 1.25 !important;
     color: $gray-600;
@@ -126,7 +126,7 @@
     width: auto !important;
     height: auto !important;
     padding: .75rem 1rem 0;
-    font-size: .75rem !important;
+    @include font-size(.75rem, true);
     line-height: 1 !important;
     color: #767676 !important;
     border-top: 1px solid rgba(0, 0, 0, .1);
diff --git a/site/docs/4.2/assets/scss/_brand.scss b/site/docs/4.2/assets/scss/_brand.scss
index d7d9f1f09b..226d7db174 100644
--- a/site/docs/4.2/assets/scss/_brand.scss
+++ b/site/docs/4.2/assets/scss/_brand.scss
@@ -44,7 +44,7 @@
     }
 
     h1 {
-      font-size: 4rem;
+      @include font-size(4rem);
     }
   }
 }
diff --git a/site/docs/4.2/assets/scss/_clipboard-js.scss b/site/docs/4.2/assets/scss/_clipboard-js.scss
index e2dd56e259..6d4bfeea48 100644
--- a/site/docs/4.2/assets/scss/_clipboard-js.scss
+++ b/site/docs/4.2/assets/scss/_clipboard-js.scss
@@ -23,7 +23,7 @@
   z-index: 10;
   display: block;
   padding: .25rem .5rem;
-  font-size: 75%;
+  @include font-size(75%);
   color: #818a91;
   background-color: transparent;
   border: 0;
diff --git a/site/docs/4.2/assets/scss/_component-examples.scss b/site/docs/4.2/assets/scss/_component-examples.scss
index 4422a7295a..62ebf6953b 100644
--- a/site/docs/4.2/assets/scss/_component-examples.scss
+++ b/site/docs/4.2/assets/scss/_component-examples.scss
@@ -406,7 +406,7 @@
     border: 0;
   }
   pre code {
-    font-size: inherit;
+    @include font-size(inherit);
     color: $gray-900; // Effectively the base text color
   }
 }
diff --git a/site/docs/4.2/assets/scss/_content.scss b/site/docs/4.2/assets/scss/_content.scss
index ecd952bd87..723e4587dc 100644
--- a/site/docs/4.2/assets/scss/_content.scss
+++ b/site/docs/4.2/assets/scss/_content.scss
@@ -71,6 +71,18 @@
 //
 
 .bd-content {
+  > h2 {
+    @include font-size($h2-font-size);
+  }
+
+  > h3 {
+    @include font-size($h3-font-size);
+  }
+
+  > h4 {
+    @include font-size($h4-font-size);
+  }
+
   > h2:not(:first-child) {
     margin-top: 3rem;
   }
@@ -97,20 +109,15 @@
   margin-top: 1rem;
   margin-bottom: .5rem;
   font-weight: 300;
-
-  @include media-breakpoint-up(sm) {
-    font-size: 3rem;
-  }
+  @include font-size(3rem);
 }
 
 .bd-lead {
-  font-size: 1.125rem;
+  @include font-size(1.125rem);
   font-weight: 300;
 
-  @include media-breakpoint-up(sm) {
+  @include media-breakpoint-up(lg) {
     max-width: 80%;
-    margin-bottom: 1rem;
-    font-size: 1.5rem;
   }
 }
 
diff --git a/site/docs/4.2/assets/scss/_footer.scss b/site/docs/4.2/assets/scss/_footer.scss
index c9a8e70e4f..29d31df3a2 100644
--- a/site/docs/4.2/assets/scss/_footer.scss
+++ b/site/docs/4.2/assets/scss/_footer.scss
@@ -3,7 +3,7 @@
 //
 
 .bd-footer {
-  font-size: 85%;
+  @include font-size(.875rem);
   text-align: center;
   background-color: #f7f7f7;
 
diff --git a/site/docs/4.2/assets/scss/_masthead.scss b/site/docs/4.2/assets/scss/_masthead.scss
index e8007fc3c4..f4e70a2cfb 100644
--- a/site/docs/4.2/assets/scss/_masthead.scss
+++ b/site/docs/4.2/assets/scss/_masthead.scss
@@ -6,12 +6,14 @@
   // background-image: linear-gradient(45deg, #fafafa, #f5f5f5);
 
   h1 {
+    @include font-size(4rem);
     line-height: 1;
   }
 
   .btn {
     padding: .8rem 2rem;
     font-weight: 600;
+    @include font-size(1.25rem);
   }
 
   .carbonad {
@@ -29,10 +31,6 @@
   }
 
   @include media-breakpoint-up(md) {
-    h1 {
-      font-size: 4rem;
-    }
-
     .carbonad {
       margin-top: 3rem !important;
     }
diff --git a/site/docs/4.2/assets/scss/_nav.scss b/site/docs/4.2/assets/scss/_nav.scss
index 5ca226f7b5..c3fdc8e5f6 100644
--- a/site/docs/4.2/assets/scss/_nav.scss
+++ b/site/docs/4.2/assets/scss/_nav.scss
@@ -16,7 +16,6 @@
       height: 2.5rem;
       margin-top: .25rem;
       overflow: hidden;
-      font-size: .875rem;
 
       .navbar-nav {
         padding-bottom: 2rem;
@@ -61,7 +60,7 @@
   }
 
   .dropdown-menu {
-    font-size: .875rem;
+    @include font-size(.875rem);
   }
 
   .dropdown-item.active {
diff --git a/site/docs/4.2/assets/scss/_placeholder-img.scss b/site/docs/4.2/assets/scss/_placeholder-img.scss
index a9f8a41cb5..3fe6a8bbac 100644
--- a/site/docs/4.2/assets/scss/_placeholder-img.scss
+++ b/site/docs/4.2/assets/scss/_placeholder-img.scss
@@ -5,12 +5,10 @@
 // Remember to update `site/_layouts/examples.html` too if this changes!
 
 .bd-placeholder-img {
-  font-size: 1.125rem;
+  @include font-size(1.125rem);
   text-anchor: middle;
 }
 
 .bd-placeholder-img-lg {
-  @include media-breakpoint-up(md) {
-    font-size: 3.5rem;
-  }
+  @include font-size(3.5rem);
 }
diff --git a/site/docs/4.2/assets/scss/_sidebar.scss b/site/docs/4.2/assets/scss/_sidebar.scss
index 5af636f7e7..b302b22fea 100644
--- a/site/docs/4.2/assets/scss/_sidebar.scss
+++ b/site/docs/4.2/assets/scss/_sidebar.scss
@@ -14,7 +14,7 @@
   order: 2;
   padding-top: 1.5rem;
   padding-bottom: 1.5rem;
-  font-size: .875rem;
+  @include font-size(.875rem);
 }
 
 .section-nav {
@@ -144,7 +144,7 @@
 .bd-sidebar .nav > li > a {
   display: block;
   padding: .25rem 1.5rem;
-  font-size: 90%;
+  @include font-size(90%);
   color: rgba(0, 0, 0, .65);
 }
 
diff --git a/site/docs/4.2/assets/scss/_variables.scss b/site/docs/4.2/assets/scss/_variables.scss
index b60a21368b..e8bf3728db 100644
--- a/site/docs/4.2/assets/scss/_variables.scss
+++ b/site/docs/4.2/assets/scss/_variables.scss
@@ -7,3 +7,9 @@ $bd-download:      #ffe484 !default;
 $bd-info:          #5bc0de !default;
 $bd-warning:       #f0ad4e !default;
 $bd-danger:        #d9534f !default;
+
+// Enable responsive font sizes for font sizes defined in the docs
+// The weird if test is made as a workaround to prevent a false fusv error.
+//
+// stylelint-disable-next-line scss/dollar-variable-default
+$enable-responsive-font-sizes: if($enable-responsive-font-sizes, true, true);
diff --git a/site/docs/4.2/content/typography.md b/site/docs/4.2/content/typography.md
index 2451367e0c..19a783d8e7 100644
--- a/site/docs/4.2/content/typography.md
+++ b/site/docs/4.2/content/typography.md
@@ -104,7 +104,7 @@ Use the included utility classes to recreate the small secondary heading text fr
 
 ## Display headings
 
-Traditional heading elements are designed to work best in the meat of your page content. When you need a heading to stand out, consider using a **display heading**—a larger, slightly more opinionated heading style.
+Traditional heading elements are designed to work best in the meat of your page content. When you need a heading to stand out, consider using a **display heading**—a larger, slightly more opinionated heading style. Keep in mind these headings are not responsive by default, but it's possible to enable [responsive font sizes](#responsive-font-sizes).
 
 <div class="bd-example bd-example-type">
   <table class="table">
@@ -294,32 +294,8 @@ Align terms and descriptions horizontally by using our grid system's predefined
 {% endcapture %}
 {% include example.html content=example %}
 
-## Responsive typography
+## Responsive font sizes
 
-*Responsive typography* refers to scaling text and components by simply adjusting the root element's `font-size` within a series of media queries. Bootstrap doesn't do this for you, but it's fairly easy to add if you need it.
+Bootstrap v4.3 ships with the option to enable responsive font sizes, allowing text to scale more naturally across device and viewport sizes. <abbr title="Responsive font sizes">RFS</abbr> can be enabled by changing the `$enable-responsive-font-sizes` Sass variable to `true` and recompiling Bootstrap.
 
-Here's an example of it in practice. Choose whatever `font-size`s and media queries you wish.
-
-{% highlight scss %}
-html {
-  font-size: 1rem;
-}
-
-@include media-breakpoint-up(sm) {
-  html {
-    font-size: 1.2rem;
-  }
-}
-
-@include media-breakpoint-up(md) {
-  html {
-    font-size: 1.4rem;
-  }
-}
-
-@include media-breakpoint-up(lg) {
-  html {
-    font-size: 1.6rem;
-  }
-}
-{% endhighlight %}
+To support <abbr title="Responsive font sizes">RFS</abbr>, we use a Sass mixin to replace our normal `font-size` properties. Responsive font sizes will be compiled into `calc()` functions with a mix of `rem` and viewport units to enable the responsive scaling behavior. More about <abbr title="Responsive font sizes">RFS</abbr> and its configuration can be found on its [GitHub repository](https://github.com/twbs/rfs).
diff --git a/site/docs/4.2/getting-started/theming.md b/site/docs/4.2/getting-started/theming.md
index a40b6395ac..8e3339c15d 100644
--- a/site/docs/4.2/getting-started/theming.md
+++ b/site/docs/4.2/getting-started/theming.md
@@ -242,6 +242,7 @@ You can find and customize these variables for key global options in Bootstrap's
 | `$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-print-styles`                       | `true` (default) or `false`        | Enables styles for optimizing printing. |
+| `$enable-responsive-font-sizes`              | `true` or `false` (default)        | Enables [responsive font sizes]({{ site.baseurl }}/docs/{{ site.docs_version }}/content/typography/#responsive-font-sizes). |
 | `$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`. |