From 4de4874e722ad934bd3bf21f20a19475096c889a Mon Sep 17 00:00:00 2001
From: Matthieu Vignolle <vignolle.matthieu@gmail.com>
Date: Wed, 27 Nov 2019 07:43:49 +0100
Subject: [PATCH] Change deprecated html tags to text decoration classes
 (#29604)

---
 scss/_utilities.scss                        |  2 +-
 site/content/docs/4.3/content/typography.md | 18 +++++++++++++++---
 site/content/docs/4.3/utilities/text.md     |  6 ++++--
 3 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 1f3c7b4ac2a1..b7c38249aa96 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -426,7 +426,7 @@ $utilities: map-merge(
     ),
     "text-decoration": (
       property: text-decoration,
-      values: none
+      values: none underline line-through
     ),
     "font-style": (
       property: font-style,
diff --git a/site/content/docs/4.3/content/typography.md b/site/content/docs/4.3/content/typography.md
index d4daabdd033f..5b651660988c 100644
--- a/site/content/docs/4.3/content/typography.md
+++ b/site/content/docs/4.3/content/typography.md
@@ -143,13 +143,25 @@ Styling for common inline HTML5 elements.
 <p><em>This line rendered as italicized text.</em></p>
 {{< /example >}}
 
-`.mark` and `.small` classes are also available to apply the same styles as `<mark>` and `<small>` while avoiding any unwanted semantic implications that the tags would bring.
+Beware that those tags should be used for semantic purpose:
 
-While not shown above, feel free to use `<b>` and `<i>` in HTML5. `<b>` is meant to highlight words or phrases without conveying additional importance while `<i>` is mostly for voice, technical terms, etc.
+* `<mark>` represents text which is marked or highlighted for reference or notation purposes.
+* `<small>` represents side-comments and small print, like copyright and legal text.
+* `<s>` represents element that are no longer relevant or no longer accurate.
+* `<u>` represents a span of inline text which should be rendered in a way that indicates that it has a non-textual annotation.
+
+If you want to style your text, you should use the following classes instead:
+
+* `.mark` will apply the same styles as `<mark>`.
+* `.small` will apply the same styles as `<small>`.
+* `.text-decoration-underline` will apply the same styles as `<u>`.
+* `.text-decoration-line-through` will apply the same styles as `<s>`.
+
+While not shown above, feel free to use `<b>` and `<i>` in HTML5. `<b>` is meant to highlight words or phrases without conveying additional importance, while `<i>` is mostly for voice, technical terms, etc.
 
 ## Text utilities
 
-Change text alignment, transform, style, weight, line-height and color with our [text utilities]({{< docsref "/utilities/text" >}}) and [color utilities]({{< docsref "/utilities/colors" >}}).
+Change text alignment, transform, style, weight, line-height, decoration and color with our [text utilities]({{< docsref "/utilities/text" >}}) and [color utilities]({{< docsref "/utilities/colors" >}}).
 
 ## Abbreviations
 
diff --git a/site/content/docs/4.3/utilities/text.md b/site/content/docs/4.3/utilities/text.md
index 3ae40fabc970..f54020644cdd 100644
--- a/site/content/docs/4.3/utilities/text.md
+++ b/site/content/docs/4.3/utilities/text.md
@@ -109,8 +109,10 @@ Reset a text or link's color with `.text-reset`, so that it inherits the color f
 
 ## Text decoration
 
-Remove a text decoration with a `.text-decoration-none` class.
+Decorate text in components with text decoration classes.
 
 {{< example >}}
-<a href="#" class="text-decoration-none">Non-underlined link</a>
+<p class="text-decoration-underline">This text has a line underneath it.</p>
+<p class="text-decoration-line-through">This text has a line going through it.</p>
+<a href="#" class="text-decoration-none">This link has its text decoration removed</a>
 {{< /example >}}