Refactor typography system to use CSS custom properties by stephaniehobson · Pull Request #1107 · mozilla/protocol

stephaniehobson · 2026-01-07T21:18:10Z

Description

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

Issue

#982

Testing

See if it compiles
Spot check for visual regressions
Do not worry about older browser support fallbacks right now

I have documented this change in the design system.
I have recorded this change in CHANGELOG.md.

Copilot

Pull request overview

This PR refactors the typography system to use CSS custom properties instead of Sass variables, improving maintainability and enabling responsive typography through theme-based CSS variables. The changes include renaming variables with a --token- prefix for consistency, removing deprecated mixins, and eliminating pixel-based font size fallbacks.

Introduces --theme-* CSS variables that adjust based on media queries for responsive typography
Refactors typography mixins to use CSS custom properties and removes pixel fallbacks
Updates all component styles to use the new variable naming convention

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
assets/sass/protocol/includes/mixins/_typography.scss	Core typography mixin refactoring to use CSS variables and remove deprecated mixins
assets/sass/protocol/includes/themes/_mozilla.scss	Mozilla theme updates with `--token-` prefix for all typography variables
assets/sass/protocol/includes/themes/_firefox.scss	Firefox theme updates with `--token-` prefix for all typography variables
assets/sass/protocol/includes/themes/_index.scss	Introduces `--theme-*` variables that map to token variables for responsive behavior
assets/sass/protocol/includes/_themes-sass.scss	Removes Sass variable definitions for fonts and type scale, now handled by CSS variables
Multiple component files	Updates to use new `--token-*` variable naming throughout the codebase
CHANGELOG.md	Documents breaking changes and migration guide

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

assets/sass/protocol/includes/themes/_index.scss

assets/sass/protocol/includes/mixins/_typography.scss

CHANGELOG.md

assets/sass/protocol/includes/themes/_index.scss

stephaniehobson · 2026-01-09T17:12:06Z

No visual regressions found running #1106 locally.

assets/sass/protocol/components/_language-switcher.scss

stephaniehobson · 2026-01-09T17:31:49Z

assets/sass/protocol/includes/_themes-sass.scss

-// This file contains all the theme variables for both the Firefox and Mozilla
-//  Mixins and functions can draw from these variable maps, swapping to
-// a different map based on the value of the global $brand-theme variable.
+// Default theme variables for legacy browsers (IE 11 etc)


Note for reviewer: I'm working on removing these. Colour and grid changes will follow.

claude.md

stephaniehobson · 2026-01-09T17:57:19Z

assets/sass/protocol/includes/forms/_index.scss

-    line-height: $text-body-line-height;
    margin: 0;
    padding-bottom: $label-v-spacing;
+    @include text-body-sm;


Note for reviewer: Line-height is included in mixin now.

@includes

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

maureenlholland

r+ 📏

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

@includes

Refactor color system to use CSS custom properties. This is the second PR in a refactor of how we use CSS variables (#982), following the typography refactor (#1107). Some kind of basic fallback support for older browsers will be added back in a later 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 colors, backgrounds, and borders Removed @supports declarations if they only had color declarations Color mixins now use CSS vars Reorganization: Added --theme- prefix to variables expected to morph Added --token- prefix to unchanging variables Created root/_color.scss for color token definitions Created root/_theme.scss for theme color mappings Created root/_spacing.scss for spacing tokens Moved theme definitions to includes/themes/ Bug fixes: Moved @include statements to end of declarations

Refactor spacing system to use CSS custom properties. This is the third PR in a refactor of how we use CSS variables (#982), following the typography (#1107) and color refactors. Introduces --theme-spacing-between-block and --theme-spacing-between-inline for responsive layout spacing while retaining Sass $spacing-* variables for component-internal spacing. Modernization: Default to CSS vars for layout spacing (block and inline) Responsive breakpoints defined in root/_spacing.scss Updated components to use new spacing vars: containers, card, callout, split, breadcrumb, navigation, newsletter-form, section-heading, card-layout, multi-column Reorganization: Removed includes/_themes-sass.scss (no longer needed) Removed bidi-grid-spacing() mixin Removed deprecated grid-gap from stylelint ignored shorthands Simplification: Simplified split component (removed pop and overflow options in separate PR) Simplified card-layout and multi-column templates Reduced newsletter-form complexity Documentation: Added section-heading mzp-t-section-heading-nospace theme class Added spacing migration guide to docs/02-usage/migration.md Updated CHANGELOG with spacing system changes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Refactor spacing to use CSS custom properties (#982) Refactor spacing system to use CSS custom properties. This is the third PR in a refactor of how we use CSS variables (#982), following the typography (#1107) and color refactors. Introduces --theme-spacing-between-block and --theme-spacing-between-inline for responsive layout spacing while retaining Sass $spacing-* variables for component-internal spacing. Modernization: Default to CSS vars for layout spacing (block and inline) Responsive breakpoints defined in root/_spacing.scss Updated components to use new spacing vars: containers, card, callout, split, breadcrumb, navigation, newsletter-form, section-heading, card-layout, multi-column Reorganization: Removed includes/_themes-sass.scss (no longer needed) Removed bidi-grid-spacing() mixin Removed deprecated grid-gap from stylelint ignored shorthands Simplification: Simplified split component (removed pop and overflow options in separate PR) Simplified card-layout and multi-column templates Reduced newsletter-form complexity Documentation: Added section-heading mzp-t-section-heading-nospace theme class Added spacing migration guide to docs/02-usage/migration.md Updated CHANGELOG with spacing system changes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * review fixes --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

stephaniehobson requested a review from Copilot January 7, 2026 21:18

Copilot AI reviewed Jan 7, 2026

View reviewed changes

stephaniehobson commented Jan 7, 2026

View reviewed changes

assets/sass/protocol/includes/themes/_index.scss Outdated Show resolved Hide resolved

stephaniehobson mentioned this pull request Jan 7, 2026

Protocol v23 #1084

Open

8 tasks

stephaniehobson force-pushed the font-vars branch from 08bea80 to 5f6d322 Compare January 9, 2026 16:57

stephaniehobson commented Jan 9, 2026

View reviewed changes

assets/sass/protocol/components/_language-switcher.scss Outdated Show resolved Hide resolved

stephaniehobson commented Jan 9, 2026

View reviewed changes

claude.md Outdated Show resolved Hide resolved

stephaniehobson force-pushed the font-vars branch 3 times, most recently from 1599e07 to 0ec134f Compare January 9, 2026 17:54

stephaniehobson commented Jan 9, 2026

View reviewed changes

stephaniehobson force-pushed the font-vars branch 10 times, most recently from ed88390 to 19ab519 Compare January 9, 2026 20:04

stephaniehobson marked this pull request as ready for review January 9, 2026 20:06

stephaniehobson force-pushed the font-vars branch from 19ab519 to b3d5a33 Compare January 10, 2026 05:00

maureenlholland self-assigned this Jan 12, 2026

maureenlholland approved these changes Jan 12, 2026

View reviewed changes

maureenlholland merged commit 865863d into main Jan 12, 2026
1 check passed

maureenlholland deleted the font-vars branch January 12, 2026 15:17

stephaniehobson mentioned this pull request Jan 15, 2026

Refactor color to use CSS custom properties (#982) #1109

Merged

2 tasks

stephaniehobson mentioned this pull request Jan 21, 2026

Refactor spacing to use CSS custom properties (#982) #1114

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor typography system to use CSS custom properties#1107

Refactor typography system to use CSS custom properties#1107
maureenlholland merged 1 commit intomainfrom
font-vars

stephaniehobson commented Jan 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stephaniehobson commented Jan 9, 2026

Uh oh!

Uh oh!

stephaniehobson Jan 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

stephaniehobson Jan 9, 2026 •

edited

Loading

Uh oh!

maureenlholland left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

stephaniehobson commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stephaniehobson commented Jan 9, 2026

Uh oh!

Uh oh!

stephaniehobson Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

stephaniehobson Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maureenlholland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

stephaniehobson commented Jan 7, 2026 •

edited

Loading

stephaniehobson Jan 9, 2026 •

edited

Loading

stephaniehobson Jan 9, 2026 •

edited

Loading