From f271cd1e57ace1e5b48232a1f8ed01ba0e435bb6 Mon Sep 17 00:00:00 2001
From: Alex Gibson <alexgibson@users.noreply.github.com>
Date: Tue, 17 Oct 2023 14:23:21 +0100
Subject: [PATCH] Add CSS utility class for centered text and document existing
 title utility classes (Fixes #897)

---
 CHANGELOG.md                                  |  8 ++++
 .../sass/protocol/base/utilities/_titles.scss |  5 +++
 docs/01-fundamentals/03-typography.md         | 16 ++++++++
 docs/02-usage/02-framework.md                 | 38 +++++++++++++++++++
 4 files changed, 67 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 37bd20e5..a92b109d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # HEAD
+
+## Features
+
+* **css:** Add CSS utility class for centered text and document existing title utility classes (#897).
+
+## Bug Fixes
+
 * **css:** Fix incorrect value for `text-body-lg` in firefox theme.
+
 # 18.0.0
 
 ## Features
diff --git a/assets/sass/protocol/base/utilities/_titles.scss b/assets/sass/protocol/base/utilities/_titles.scss
index 2c49254e..041f26ac 100644
--- a/assets/sass/protocol/base/utilities/_titles.scss
+++ b/assets/sass/protocol/base/utilities/_titles.scss
@@ -78,3 +78,8 @@
         font-family: var(--title-font-family);
     }
 }
+
+// Utility class for centered text.
+.mzp-u-centered {
+    text-align: center;
+}
diff --git a/docs/01-fundamentals/03-typography.md b/docs/01-fundamentals/03-typography.md
index e966cb7a..1ed9d8cf 100644
--- a/docs/01-fundamentals/03-typography.md
+++ b/docs/01-fundamentals/03-typography.md
@@ -180,3 +180,19 @@ output, assuming a `16px` root size (the default in graphical browsers). Because
 we use `rem` for font sizing all of our declared sizes are really just suggestions
 and the end user can resize as they see fit. Text sizes are always variable so
 design accordingly.
+
+#### Title utility classes
+
+There are also a set of CSS utility class names available to use directly on HTML
+heading elements for convenience.
+
+```html
+<h1 class="mzp-u-title-2xl">Title 2XL</h1>
+<h2 class="mzp-u-title-xl">Title XL</h2>
+<h3 class="mzp-u-title-lg">Title LG</h3>
+<h4 class="mzp-u-title-md">Title MD</h4>
+<h5 class="mzp-u-title-sm">Title SM</h5>
+<h6 class="mzp-u-title-xs">Title XS</h6>
+<h6 class="mzp-u-title-2xs">Title 2XS</h6>
+<h6 class="mzp-u-title-3xs">Title 3XS</h6>
+```
diff --git a/docs/02-usage/02-framework.md b/docs/02-usage/02-framework.md
index e186ea77..45987798 100644
--- a/docs/02-usage/02-framework.md
+++ b/docs/02-usage/02-framework.md
@@ -141,3 +141,41 @@ Text sizes are also defined as theme variables, allowing different brands to hav
 slightly different type scales. Don’t use CSS Custom Properties for text
 sizing; use the text size mixins instead. The mixins already draw from the theme
 variables but come with baked-in responsive styling as well.
+
+### Utility classes
+
+Whilst Protocol tries to avoid reliance on utility classes, we do support a few well
+chosen use cases, where utility classes can allow for some very basic visual styling
+directly in HTML.
+
+These classes are purely presentational, so should only be used in situations where
+you're not already writing CSS for an element. A good example use case might be
+content delivered through a CMS, or when it would be more effort to write custom
+styles for something that requires only the most very basic layout.
+
+#### Centered text
+
+The `mzp-u-centered` utility class apply `text-align: center;` to an element's
+text content.
+
+```html
+<div class="mzp-u-centered">
+  The text content of this element is centered
+</div>
+```
+
+#### Title sizes
+
+A range of utility classes are available for title sizes. See the
+[typography page](/docs/fundamentals/typography) for more details.
+
+```html
+<h1 class="mzp-u-title-2xl">Title 2XL</h1>
+<h2 class="mzp-u-title-xl">Title XL</h2>
+<h3 class="mzp-u-title-lg">Title LG</h3>
+<h4 class="mzp-u-title-md">Title MD</h4>
+<h5 class="mzp-u-title-sm">Title SM</h5>
+<h6 class="mzp-u-title-xs">Title XS</h6>
+<h6 class="mzp-u-title-2xs">Title 2XS</h6>
+<h6 class="mzp-u-title-3xs">Title 3XS</h6>
+```