Refactor typography system to use CSS custom properties

- Switch from pixel-based font sizes to rem units only, removing px fallbacks
- Remove deprecated `text-display-*` mixins (see migration notes for v11.0.2)
- Refactor typography mixins to use CSS custom properties instead of Sass variables
  - `text-title-*` and `text-body-*` mixins now use `--theme-*` variables
- Rename CSS variables to use `--token-` prefix for consistency:
  - `--body-text-color` → `--token-body-text-color`
  - `--title-text-color` → `--token-title-text-color`
  - `--body-font-family` → `--token-body-font-family`
  - `--title-font-family` → `--token-title-font-family`
- Remove redundant `@supports (--css: variables)` blocks for font properties
- Clean up font-family declarations now handled by typography mixins
- Update Firefox and Mozilla theme files with new variable naming
- Update CHANGELOG with breaking changes

BREAKING CHANGE: Font sizes no longer include px fallbacks. All typography
now requires CSS custom property support (browsers without support are
effectively unsupported as of this change).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: stephaniehobson

CHANGELOG.md

@@ -1,3 +1,58 @@
+# HEAD
+
+This version introduces some major modernization changes around CSS and drops browser support for XXXX.
+
+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.
+
+## Modernization
+
+### Typography
+
+* Transition from Sass variables to CSS variables for typography. (#982)
+* Renamed existing CSS variables to use `--token-` prefix.
+* Introduced CSS variables with the `--theme-` prefix for values that adjust based on media queries.
+
+### Color
+
+* To come in follow up PR.
+
+## Migration Tips
+
+* Browser support
+  * If you require support for older browsers we recommend adding some post-processing to your work flow for css variables and font sizes in pixels.
+* `text-title-*` 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 heading font).
+* Update Sass variables to use CSS variables:
+  * `$body-text-color` → `var(--token-body-text-color)`
+  * `$body-text-color-inverse` → `var(--token-body-text-color-inverse)`
+  * `$body-text-color-secondary` → `var(--token-body-text-color-secondary)`
+  * `$body-text-color-secondary-inverse` → `var(--token-body-text-color-secondary-inverse)`
+  * `$title-text-color` → `var(--token-title-text-color)`
+  * `$title-text-color-inverse` → `var(--token-title-text-color-inverse)`
+  * `$body-font-family` → `var(--token-body-font-family)`
+  * `$title-font-family` → `var(--token-title-font-family)`
+  * `$body-line-height` → `var(--token-body-line-height)`
+* Rename CSS variables:
+  * `--body-text-color` → `--token-body-text-color`
+  * `--body-text-color-inverse` → `--token-body-text-color-inverse`
+  * `--body-text-color-secondary` → `--token-body-text-color-secondary`
+  * `--body-text-color-secondary-inverse` → `--token-body-text-color-secondary-inverse`
+  * `--title-text-color` → `--token-title-text-color`
+  * `--title-text-color-inverse` → `--token-title-text-color-inverse`
+  * `--body-font-family` → `--token-body-font-family`
+  * `--title-font-family` → `--token-title-font-family`
+  * `--body-line-height` → `--token-body-line-height`
+* Replace any remaining `text-display-*` usage with the equivalent `text-title-*` mixin (see migration notes for version 11.0.2.):
+  * `text-display-xxl` → `text-title-2xl`
+  * `text-display-xl` → `text-title-xl`
+  * `text-display-lg` → `text-title-lg`
+  * `text-display-md` → `text-title-md`
+  * `text-display-sm` → `text-title-sm`
+  * `text-display-xs` → `text-title-xs`
+  * `text-display-xxs` → `text-title-2xs`
+
 # 22.0.0
 
 ## Features
@@ -199,8 +254,8 @@ 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);
+    color: var(--token-body-text-color-inverse);
+    line-height: var(--token-body-line-height);
   }
 }
 ```

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

@@ -13,16 +13,12 @@ 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;
 
     @supports (--css: variable) {
         background: var(--background-color);
-        color: var(--body-text-color);
-        font-family: var(--body-font-family);
-        line-height: var(--body-line-height);
+        color: var(--token-body-text-color);
     }
 }
 

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

@@ -32,13 +32,9 @@ legend {
         @include forms.field-label;
     }
     @include text-body-lg;
-    font-family: $body-font-family;
+    font-family: var(--token-body-font-family);
     font-weight: bold;
     margin-bottom: forms.$field-v-spacing;
-
-    @supports (--css: variables) {
-        font-family: var(--body-font-family);
-    }
 }
 
 button,

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

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

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

@@ -10,7 +10,6 @@ blockquote {
     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;
@@ -29,11 +28,10 @@ blockquote {
     }
 
     @supports (--css: variables) {
-        color: var(--title-text-color);
-        font-family: var(--title-font-family);
+        color: var(--token-title-text-color);
 
         cite {
-            color: var(--body-text-color-secondary);
+            color: var(--token-body-text-color-secondary);
         }
     }
 }

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

@@ -12,10 +12,9 @@ h3,
 h4,
 h5,
 h6 {
-    $default-font-weight: bold;
-    font-family: $title-font-family;
+    font-family: var(--token-title-font-family);
+    font-variant-ligatures: var(--token-title-font-ligatures);
     color: $title-text-color;
-    font-weight: $default-font-weight;
     text-wrap: balance;
     margin: 0 0 0.5em;
 
@@ -24,14 +23,10 @@ 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(--token-title-text-color);
 
         .mzp-t-dark & {
-            color: var(--title-text-color-inverse);
+            color: var(--token-title-text-color-inverse);
         }
     }
 }

assets/sass/protocol/base/utilities/_backgrounds.scss

@@ -28,7 +28,7 @@
 
     @supports (--css: variables) {
         background-color: var(--background-color-inverse);
-        color: var(--body-text-color-inverse);
+        color: var(--token-body-text-color-inverse);
     }
 }
 

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

@@ -18,7 +18,7 @@
 
     h4 {
         @include text-body-lg;
-        font-family: var(--body-font-family);
+        font-family: var(--token-body-font-family);
         margin-bottom: $layout-xs;
         margin-top: $layout-xs;
     }

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

@@ -9,74 +9,34 @@
 
 .mzp-u-title-2xl {
     @include text-title-2xl;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 .mzp-u-title-xl {
     @include text-title-xl;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 .mzp-u-title-lg {
     @include text-title-lg;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 .mzp-u-title-md {
     @include text-title-md;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 .mzp-u-title-sm {
     @include text-title-sm;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 .mzp-u-title-xs {
     @include text-title-xs;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 .mzp-u-title-2xs {
     @include text-title-2xs;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 .mzp-u-title-3xs {
     @include text-title-3xs;
-    font-family: $title-font-family;
-
-    @supports (--css: variables) {
-        font-family: var(--title-font-family);
-    }
 }
 
 // Utility class for centered text.

assets/sass/protocol/components/_button.scss

@@ -16,7 +16,7 @@
     border: 2px solid transparent;
     cursor: pointer;
     display: inline-block;
-    font-family: $button-font-family;
+    font-family: var(--button-font-family);
     font-weight: bold;
     line-height: $body-line-height;
     padding: $spacing-sm $spacing-md;
@@ -44,7 +44,7 @@
 
     @supports (--css: variables) {
         font-family: var(--button-font-family);
-        line-height: var(--body-line-height);
+        line-height: var(--token-body-line-height);
     }
 }