From e5fa7084910c3ad68232c4580f4e2dd5a4c3fad1 Mon Sep 17 00:00:00 2001
From: Mark Otto <markd.otto@gmail.com>
Date: Mon, 26 Oct 2020 16:42:07 -0700
Subject: [PATCH] v5: Add .fs-* utilities for font-size and rename
 font-weight/-style utilities (#30571)

* v5: Add .fs-* utilities for font-size

- Adds new font-sizes Sass map
- Generates six new classes for setting only font-size
- Updates docs to mention this, including a scss-docs reference

* Update font utilities

- Make .fs-* utils for font-size use RFS
- Rename .font-weight-* utils to .fw-*
- Rename .font-style-* utils to .f-*
- Update order of utilities a bit
- Update docs to match

* Update migration docs to make note of these changes

* Be more specific in font-size docs about scale

* Update font-style abbreviation to .fst

* Fix font-weight property

* Formatting & font style utility fix

* Move to Alpha 3 migration section

* Update migration guide for more details, splitting alpha 2 stuff back to the appropriate section in Migration guide

* Tweak language on example

Co-authored-by: Martijn Cuppens <martijn.cuppens@gmail.com>
---
 scss/_utilities.scss                    | 16 +++++++----
 scss/_variables.scss                    | 11 ++++++++
 site/content/docs/5.0/migration.md      | 24 ++++++++++++++---
 site/content/docs/5.0/utilities/text.md | 35 ++++++++++++++++++-------
 4 files changed, 68 insertions(+), 18 deletions(-)

diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 226c9143a1..21ff560665 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -387,6 +387,17 @@ $utilities: map-merge(
       values: $spacers
     ),
     // Text
+    "font-size": (
+      rfs: true,
+      property: font-size,
+      class: fs,
+      values: $font-sizes
+    ),
+    "font-style": (
+      property: font-style,
+      class: fst,
+      values: italic normal
+    ),
     "font-weight": (
       property: font-weight,
       values: (
@@ -462,11 +473,6 @@ $utilities: map-merge(
       property: text-decoration,
       values: none underline line-through
     ),
-    "font-style": (
-      property: font-style,
-      class: font,
-      values: italic normal
-    ),
     "word-wrap": (
       property: word-wrap word-break,
       class: text,
diff --git a/scss/_variables.scss b/scss/_variables.scss
index c15ceb68ac..6fba4d8352 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -425,6 +425,17 @@ $h4-font-size:                $font-size-base * 1.5 !default;
 $h5-font-size:                $font-size-base * 1.25 !default;
 $h6-font-size:                $font-size-base !default;
 
+// scss-docs-start font-sizes
+$font-sizes: (
+  1: $h1-font-size,
+  2: $h2-font-size,
+  3: $h3-font-size,
+  4: $h4-font-size,
+  5: $h5-font-size,
+  6: $h6-font-size
+) !default;
+// scss-docs-end font-sizes
+
 $headings-margin-bottom:      $spacer / 2 !default;
 $headings-font-family:        null !default;
 $headings-font-style:         null !default;
diff --git a/site/content/docs/5.0/migration.md b/site/content/docs/5.0/migration.md
index 2d30ee004e..6e252b8e51 100644
--- a/site/content/docs/5.0/migration.md
+++ b/site/content/docs/5.0/migration.md
@@ -21,10 +21,22 @@ toc: true
 
 - Introduce `$enable-smooth-scroll`, which applies `scroll-behavior: smooth` globally—except for users asking for reduced motion through `prefers-reduced-motion` media query. [See #31877](https://github.com/twbs/bootstrap/pull/31877)
 
+<<<<<<< HEAD
 ### Forms
 
 - The longstanding [Missing border radius on input group with validation feedback bug](https://github.com/twbs/bootstrap/issues/25110) is finally fixed by adding an additional `.has-validation` class to input groups with validation.
 
+### Utilities
+
+=======
+### Utilities
+
+>>>>>>> Update migration guide for more details, splitting alpha 2 stuff back to the appropriate section in Migration guide
+- **Text utilities:**
+  - Added `.fs-*` utilities for `font-size` utilities (with RFS enabled). These use the same scale as HTML's default headings (1-6, large to small), and can be modified via Sass map.
+  - Renamed `.font-weight-*` utilities as `.fw-*` for brevity and consistency.
+  - Renamed `.font-style-*` utilities as `.fst-*` for brevity and consistency.
+
 ## v5.0.0-alpha2
 
 ### Sass
@@ -138,6 +150,9 @@ toc: true
   - Some great examples have been added to the docs to show these off.
 - [#31484](https://github.com/twbs/bootstrap/pull/31484): Added new [`border-width` utility]({{< docsref "/utilities/borders#border-width" >}}).
 - [#31473](https://github.com/twbs/bootstrap/pull/31473): The `.d-none` utility was moved in our CSS to give it more weight over other display utilities.
+- Renamed `.text-monospace` to `.font-monospace`.
+- Removed `.text-hide` as it's an antiquated method for hiding text that shouldn't be used anymore.
+- New `line-height` utilities: `.lh-1`, `.lh-sm`, `.lh-base` and `.lh-lg`. See [here]({{< docsref "/utilities/text#line-height" >}}).
 
 ---
 
@@ -320,12 +335,13 @@ Badges were overhauled to better differentiate themselves from buttons and to be
 
 ### Utilities
 
-- Renamed `.text-monospace` to `.font-monospace`
+### Grid
+
 - Decreased the number of responsive order utilities per breakpoint. The highest order utility with a number now is `.order-5` instead of `.order-12`. [See #28874](https://github.com/twbs/bootstrap/pull/28874).
-- New `line-height` utilities: `.lh-1`, `.lh-sm`, `.lh-base` and `.lh-lg`. See [here]({{< docsref "/utilities/text#line-height" >}}).
+
+### Misc
+
 - Added `.bg-body` for quickly setting the `<body>`'s background to additional elements.
-- Drop `.text-hide` as it's an antiquated method for hiding text that shouldn't be used anymore
-- Split utilities into property-value utility classes and helpers
 - Negative margin utilities are disabled by default. You can re-enable them by setting `$enable-negative-margins: true`, but keep in mind this can increase the file size quite a lot.
 
 ### Docs
diff --git a/site/content/docs/5.0/utilities/text.md b/site/content/docs/5.0/utilities/text.md
index aad34a35de..a5defc6f19 100644
--- a/site/content/docs/5.0/utilities/text.md
+++ b/site/content/docs/5.0/utilities/text.md
@@ -63,18 +63,35 @@ Transform text in components with text capitalization classes.
 
 Note how `.text-capitalize` only changes the first letter of each word, leaving the case of any other letters unaffected.
 
-## Font weight and italics
+## Font size
 
-Quickly change the weight (boldness) of text or italicize text.
+Quickly change the `font-size` of text. While our heading classes (e.g., `.h1`–`.h6`) apply `font-size`, `font-weight`, and `line-height`, these utilities _only_ apply `font-size`. Sizing for these utilities matches HTML's heading elements, so as the number increases, their size decreases.
 
 {{< example >}}
-<p class="font-weight-bold">Bold text.</p>
-<p class="font-weight-bolder">Bolder weight text (relative to the parent element).</p>
-<p class="font-weight-normal">Normal weight text.</p>
-<p class="font-weight-light">Light weight text.</p>
-<p class="font-weight-lighter">Lighter weight text (relative to the parent element).</p>
-<p class="font-italic">Italic text.</p>
-<p class="font-normal">Text without font style</p>
+<p class="fs-1">.fs-1 text</p>
+<p class="fs-2">.fs-2 text</p>
+<p class="fs-3">.fs-3 text</p>
+<p class="fs-4">.fs-4 text</p>
+<p class="fs-5">.fs-5 text</p>
+<p class="fs-6">.fs-6 text</p>
+{{< /example >}}
+
+Customize your available `font-size`s by modifying the `$font-sizes` Sass map.
+
+{{< scss-docs name="font-sizes" file="scss/_variables.scss" >}}
+
+## Font weight and italics
+
+Quickly change the `font-weight` or `font-style` of text with these utilities. `font-style` utilities are abbreviated as `.fst-*` and `font-weight` utilities are abbreviated as `.fw-*`.
+
+{{< example >}}
+<p class="fw-bold">Bold text.</p>
+<p class="fw-bolder">Bolder weight text (relative to the parent element).</p>
+<p class="fw-normal">Normal weight text.</p>
+<p class="fw-light">Light weight text.</p>
+<p class="fw-lighter">Lighter weight text (relative to the parent element).</p>
+<p class="fst-italic">Italic text.</p>
+<p class="fst-normal">Text with normal font style</p>
 {{< /example >}}
 
 ## Line height