Redo display headings (#30568)

- Convert to Sass map
- Consolidate font-weights into single option (matching line-height for them)
- Add two new sizes and create a new scale
- Update migration docs

Co-authored-by: Martijn Cuppens <[email protected]>

4 files changed, 35 insertions, 30 deletions

diff --git a/scss/_type.scss b/scss/_type.scss
index 7726b7b21..efa2c8155 100644
--- a/scss/_type.scss
+++ b/scss/_type.scss
@@ -32,25 +32,12 @@
 }
 
 // Type display classes
-.display-1 {
-  @include font-size($display1-size);
-  font-weight: $display1-weight;
-  line-height: $display-line-height;
-}
-.display-2 {
-  @include font-size($display2-size);
-  font-weight: $display2-weight;
-  line-height: $display-line-height;
-}
-.display-3 {
-  @include font-size($display3-size);
-  font-weight: $display3-weight;
-  line-height: $display-line-height;
-}
-.display-4 {
-  @include font-size($display4-size);
-  font-weight: $display4-weight;
-  line-height: $display-line-height;
+@each $display, $font-size in $display-font-sizes {
+  .display-#{$display} {
+    @include font-size($font-size);
+    font-weight: $display-font-weight;
+    line-height: $display-line-height;
+  }
 }
 
 //
diff --git a/scss/_variables.scss b/scss/_variables.scss
index 6597e10ad..5539f3172 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -411,16 +411,19 @@ $headings-font-weight:        500 !default;
 $headings-line-height:        1.2 !default;
 $headings-color:              null !default;
 
-$display1-size:               6rem !default;
-$display2-size:               5.5rem !default;
-$display3-size:               4.5rem !default;
-$display4-size:               3.5rem !default;
-
-$display1-weight:             300 !default;
-$display2-weight:             300 !default;
-$display3-weight:             300 !default;
-$display4-weight:             300 !default;
-$display-line-height:         $headings-line-height !default;
+// scss-docs-start display-headings
+$display-font-sizes: (
+  1: 5rem,
+  2: 4.5rem,
+  3: 4rem,
+  4: 3.5rem,
+  5: 3rem,
+  6: 2.5rem
+) !default;
+
+$display-font-weight: 300 !default;
+$display-line-height: $headings-line-height !default;
+// scss-docs-end display-headings
 
 $lead-font-size:              $font-size-base * 1.25 !default;
 $lead-font-weight:            300 !default;
diff --git a/site/content/docs/4.3/content/typography.md b/site/content/docs/4.3/content/typography.md
index 5b6516609..7d4875e92 100644
--- a/site/content/docs/4.3/content/typography.md
+++ b/site/content/docs/4.3/content/typography.md
@@ -108,7 +108,9 @@ Traditional heading elements are designed to work best in the meat of your page
   <div class="display-1 pb-3 mb-3 border-bottom">Display 1</div>
   <div class="display-2 pb-3 mb-3 border-bottom">Display 2</div>
   <div class="display-3 pb-3 mb-3 border-bottom">Display 3</div>
-  <div class="display-4">Display 4</div>
+  <div class="display-4 pb-3 mb-3 border-bottom">Display 4</div>
+  <div class="display-5 pb-3 mb-3 border-bottom">Display 5</div>
+  <div class="display-6">Display 6</div>
 </div>
 
 {{< highlight html >}}
@@ -116,8 +118,14 @@ Traditional heading elements are designed to work best in the meat of your page
 <h1 class="display-2">Display 2</h1>
 <h1 class="display-3">Display 3</h1>
 <h1 class="display-4">Display 4</h1>
+<h1 class="display-5">Display 5</h1>
+<h1 class="display-6">Display 6</h1>
 {{< /highlight >}}
 
+Display headings are configured via the `$display-font-sizes` Sass map and two variables, `$display-font-weight` and `$display-line-height`.
+
+{{< scss-docs name="display-headings" file="scss/_variables.scss" >}}
+
 ## Lead
 
 Make a paragraph stand out by adding `.lead`.
diff --git a/site/content/docs/4.3/migration.md b/site/content/docs/4.3/migration.md
index 736115af2..fecf23d79 100644
--- a/site/content/docs/4.3/migration.md
+++ b/site/content/docs/4.3/migration.md
@@ -77,6 +77,13 @@ Changes to Reboot, typography, tables, and more.
 - `.text-*` utilities do not add hover and focus states to links anymore. `.link-*` helper classes can be used instead. [See #29267](https://github.com/twbs/bootstrap/pull/29267)
 - Drop `.text-justify` class. [See #229793](https://github.com/twbs/bootstrap/pull/29793)
 
+## Typography
+
+- Removed `$display-*` variables for a new `$display-font-sizes` Sass map.
+- Removed individiual `$display-*-weight` variables for a single `$display-font-weight`.
+- Added two new `.display-*` heading styles, `.display-5` and `.display-6`.
+- Resized existing display headings for a slightly more consistent set of `font-size`s.
+
 ## Forms
 
 - Rearranged form documentation under its own top-level section.