Refactor typography system to use CSS custom properties (#1107)

Refactor typography system to use CSS custom properties. This is the first PR in a refactor of how we use CSS variables (#982) and renaming title to heading (#668). Some kind of basic fallback support for older browsers will be added back in a latter PR once we can get a clear picture of how broken things are.

I know this looks big but for the most part it's just a straight find/replace on variable names or moving @includes to the end of declarations.

    Modernization:
        Default to CSS vars for font family, size, and line-height
        Removed @supports declarations if they only had font declarations
        @include text-body-* and @include text-heading-* mixins use CSS vars now
        Edited @mixin font-size() to stop outputting a pixel fallback
    Reorganization:
        Renamed -title- to -heading- in mixins and CSS vars
            and mzp-u-heading-* utility classes
            component HTML/CSS classes will follow in a separate PR
        Added font-family declaration to @include text-body-* mixins
        Added --theme- prefix to variables expected to morph
        Added --token- prefix to unchanging variables
            Re-name font-size tokens to use a scale instead of tshirt sizes for names
        Added --theme-button-line-height var
    Bug fixes:
        Moved @include text-* to end of declarations

Author: stephaniehobson

CHANGELOG.md

@@ -1,3 +1,71 @@
+# HEAD
+
+This version introduces some major modernization changes around CSS and drops browser support for XXXX ( to be defined before V23 is published).
+
+The good news is we don't expect any visible changes in modern browsers and you should be able to do some automated visual regression testing to help with the migration.
+
+Introducing theme variables! CSS variables beginning with `--theme-` will adjust based on media queries.
+
+
+## Typography
+
+* Modernization:
+  *  Default to CSS vars for font family, size, and line-height (#982)
+    * Removed `@supports` declarations if they only had font declarations
+    * `@include text-body-*` and `@include text-heading-*` mixins use CSS vars now
+  * Edited `@mixin font-size()` to stop outputting a pixel fallback
+* Reorganization:
+  * Renamed `-title-` to `-heading-` in mixins and CSS vars
+    * and `mzp-u-heading-*` utility classes
+    * component HTML/CSS classes will follow in a separate PR
+  * Added font-family declaration to `@include text-body-*` mixins
+  * Added `--theme-` prefix to variables expected to morph
+  * Added `--token-` prefix to unchanging variables
+    * Re-name font-size tokens to use a scale instead of tshirt sizes for names
+  * Added `--theme-button-line-height` var
+* Bug fixes:
+  * Moved `@include text-*` to end of declarations
+
+## Color
+
+* To come in follow up PR.
+
+## Migration Tips
+
+See the [Migration Guide](https://protocol.mozilla.org/docs/usage/migration) for automated scripts (VS Code find/replace and terminal commands) to help with these changes.
+
+* Browser support
+  * If you require support for older browsers we recommend adding some post-processing to your workflow for CSS variables and font sizes in pixels.
+* Rename typography mixins `text-title-(2xs|3xs|xs|sm|md|lg|xl|2xl)` → `text-heading-$1`
+* Rename utility classes `mzp-u-title-(2xs|3xs|xs|sm|md|lg|xl|2xl)` → `mzp-u-heading-$1`
+* Replace any remaining `text-display-*` usage with the equivalent `text-heading-*` mixin:
+  * `text-display-xx([sl])` → `text-heading-2x$1`
+  * `text-display-(xs|sm|md|lg|xl)` → `text-heading-$1`
+* Rename CSS variables to use pattern `--theme-<component>-<property>-<scale>`:
+  * `--body-font-family` → `--theme-body-font-family`
+  * `--title-font-family` → `--theme-heading-font-family`
+  * `--body-line-height` → `--theme-body-line-height`
+  * `--title-(2xs|3xs|xs|sm|md|lg|xl|2xl)-size` → `--theme-heading-font-size-$1`
+  * `--body-(xs|sm|md|lg|xl)-size` → `--theme-body-font-size-$1`
+  * `--title-(2xs|3xs|xs|sm|md|lg|xl|2xl)-line-height` → `--theme-heading-line-height-$1`
+* Removed Sass variables (use CSS variables instead):
+  * `$title-(2xs|3xs|xs|sm|md|lg|xl|2xl)-size` → `var(--theme-heading-font-size-$1)`
+  * `$title-(2xs|3xs|xs|sm|md|lg|xl|2xl)-line-height` → `var(--theme-heading-line-height-$1)`
+  * `$body-line-height` → `var(--theme-body-line-height)`
+  * `$body-(xs|sm|md|lg|xl)-size` → `var(--theme-body-font-size-$1)`
+  * `$body-font-family` → `var(--theme-body-font-family)`
+  * `$title-font-family` → `var(--theme-heading-font-family)`
+  * `$button-font-family` → `var(--theme-button-font-family)`
+  * `$text-body-line-height` → `var(--theme-body-line-height)`
+  * `$text-title-line-height` → `var(--theme-heading-line-height)`
+  * `$text-display-line-height`→ `var(--theme-body-line-height)`
+* `text-body-*` mixins now declare `font-family`.
+  * You can remove any `font-family` declarations from places which use these mixins (unless you don't want the default font).
+* Removed mixins and functions:
+  * `type-scale()` function and associated lookup tables
+  * `text-body-cta` mixin (use `text-body-md` instead)
+* You can remove `@supports (--css: variables)` blocks that only contain font declarations, as CSS custom properties are now required.
+
 # 22.0.0
 
 ## Features
@@ -200,7 +268,7 @@ stating variables explicitly, like this:
   @supports (--css: variables) {
     background-color: var(--background-color-inverse);
     color: var(--body-text-color-inverse);
-    line-height: var(--body-line-height);
+    line-height: var(--token-body-line-height);
   }
 }
 ```

assets/sass/protocol/base/elements/_document.scss

@@ -10,19 +10,15 @@ html {
 }
 
 body {
-    @include text-body-md;
     background: $background-color;
     color: $body-text-color;
-    font-family: $body-font-family;
-    line-height: $body-line-height;
     -moz-osx-font-smoothing: grayscale;
     -webkit-font-smoothing: antialiased;
+    @include text-body-md;
 
     @supports (--css: variable) {
         background: var(--background-color);
         color: var(--body-text-color);
-        font-family: var(--body-font-family);
-        line-height: var(--body-line-height);
     }
 }
 

assets/sass/protocol/base/elements/_forms.scss

@@ -28,16 +28,12 @@ legend {
     max-width: 100%; // 1
     padding: 0; // 3
     white-space: normal; // 1
-    .mzp-u-inline & {
-        @include forms.field-label;
-    }
-    @include text-body-lg;
-    font-family: $body-font-family;
-    font-weight: bold;
     margin-bottom: forms.$field-v-spacing;
+    font-weight: bold;
+    @include text-body-lg;
 
-    @supports (--css: variables) {
-        font-family: var(--body-font-family);
+    .mzp-u-inline & {
+        @include forms.field-label;
     }
 }
 
@@ -46,9 +42,14 @@ input,
 select,
 optgroup,
 textarea {
-    @include font-base;
     @include text-body-md;
-    line-height: 1.25;
+    @include font-base;
+
+    /* stylelint-disable-next-line no-duplicate-selectors */
+    & {
+        // needs to come after @includes to over-ride value
+        line-height: var(--theme-button-line-height);
+    }
 }
 
 button,
@@ -249,7 +250,7 @@ input[type='file'] {
     background: $color-white;
     border-radius: forms.$field-border-radius;
     border: forms.$field-border;
-    line-height: 1.25;
+    line-height: var(--theme-button-line-height);
     margin: 0 0 forms.$field-v-spacing;
 
     &:hover {

assets/sass/protocol/base/elements/_links.scss

@@ -48,13 +48,9 @@ a {
 }
 
 .mzp-c-cta-link {
-    font-family: $button-font-family;
+    font-family: var(--theme-button-font-family);
     font-weight: bold;
 
-    @supports (--css: variables) {
-        font-family: var(--button-font-family);
-    }
-
     &.mzp-t-xs {
         @include text-body-sm;
     }
@@ -68,30 +64,15 @@ a {
     }
 
     &.mzp-t-lg {
-        @include text-title-xs;
-        font-family: $title-font-family;
-
-        @supports (--css: variables) {
-            font-family: var(--title-font-family);
-        }
+        @include text-heading-xs;
     }
 
     &.mzp-t-xl {
-        @include text-title-sm;
-        font-family: $title-font-family;
-
-        @supports (--css: variables) {
-            font-family: var(--title-font-family);
-        }
+        @include text-heading-sm;
     }
 
     &.mzp-t-2xl {
-        @include text-title-lg;
-        font-family: $title-font-family;
-
-        @supports (--css: variables) {
-            font-family: var(--title-font-family);
-        }
+        @include text-heading-lg;
     }
 
     // Icon support

assets/sass/protocol/base/elements/_quotes.scss

@@ -6,17 +6,16 @@
 
 blockquote {
     @include bidi(((border-width, 0 0 0 5px, 0 5px 0 0),));
-    @include text-title-sm;
+    @include text-heading-sm;
     border-color: $color-marketing-gray-20;
     border-style: solid;
     color: $title-text-color;
-    font-family: $title-font-family;
     font-weight: bold;
     margin: $spacing-lg auto;
     padding: $spacing-sm $spacing-lg;
 
     cite {
-        @include text-title-xs;
+        @include text-heading-xs;
         color: $body-text-color-secondary;
 
         &::before {
@@ -29,8 +28,7 @@ blockquote {
     }
 
     @supports (--css: variables) {
-        color: var(--title-text-color);
-        font-family: var(--title-font-family);
+        color: var(--heading-text-color);
 
         cite {
             color: var(--body-text-color-secondary);

assets/sass/protocol/base/elements/_titles.scss

@@ -12,10 +12,10 @@ h3,
 h4,
 h5,
 h6 {
-    $default-font-weight: bold;
-    font-family: $title-font-family;
     color: $title-text-color;
-    font-weight: $default-font-weight;
+    font-family: var(--theme-heading-font-family);
+    font-variant-ligatures: var(--theme-heading-font-ligatures);
+    letter-spacing: var(--theme-heading-letter-spacing);
     text-wrap: balance;
     margin: 0 0 0.5em;
 
@@ -24,40 +24,36 @@ h6 {
     }
 
     @supports (--css: variables) {
-        font-family: var(--title-font-family);
-        font-variant-ligatures: var(--title-font-ligatures);
-        font-weight: var(--title-font-weight, #{$default-font-weight});
-        letter-spacing: var(--title-letter-spacing);
-        color: var(--title-text-color);
+        color: var(--heading-text-color);
 
         .mzp-t-dark & {
-            color: var(--title-text-color-inverse);
+            color: var(--heading-text-color-inverse);
         }
     }
 }
 
 // Type scale mixins can be found in includes/mixins/_typography.scss
 // Sizes are defined in includes/_themes.scss
 h1 {
-    @include text-title-lg;
+    @include text-heading-lg;
 }
 
 h2 {
-    @include text-title-md;
+    @include text-heading-md;
 }
 
 h3 {
-    @include text-title-sm;
+    @include text-heading-sm;
 }
 
 h4 {
-    @include text-title-xs;
+    @include text-heading-xs;
 }
 
 h5 {
-    @include text-title-2xs;
+    @include text-heading-2xs;
 }
 
 h6 {
-    @include text-title-3xs;
+    @include text-heading-3xs;
 }

assets/sass/protocol/base/utilities/_rich-text.scss

@@ -3,7 +3,7 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 @use '../../includes/lib' as *;
-@import '../../base/elements/tables';
+@use '../../base/elements/tables' as *;
 
 .mzp-u-rich-text {
     h2 {
@@ -17,10 +17,9 @@
     }
 
     h4 {
-        @include text-body-lg;
-        font-family: var(--body-font-family);
         margin-bottom: $layout-xs;
         margin-top: $layout-xs;
+        @include text-body-lg;
     }
 
     @media #{$mq-md} {