Skip to content

Refactor typography system to use CSS custom properties - #1107

Merged
maureenlholland merged 1 commit into
mainfrom
font-vars
Jan 12, 2026
Merged

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

Conversation

@stephaniehobson

@stephaniehobson stephaniehobson commented Jan 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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 AI reviewed Jan 7, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread assets/sass/protocol/includes/themes/_index.scss Outdated
Comment thread assets/sass/protocol/includes/themes/_index.scss Outdated
Comment thread assets/sass/protocol/includes/themes/_index.scss Outdated
Comment thread assets/sass/protocol/includes/themes/_index.scss Outdated
Comment thread assets/sass/protocol/includes/themes/_index.scss Outdated
Comment thread assets/sass/protocol/includes/mixins/_typography.scss
Comment thread assets/sass/protocol/includes/mixins/_typography.scss
Comment thread assets/sass/protocol/includes/mixins/_typography.scss
Comment thread assets/sass/protocol/includes/mixins/_typography.scss
Comment thread CHANGELOG.md Outdated
stephaniehobson
stephaniehobson commented Jan 7, 2026
View reviewed changes
Comment thread assets/sass/protocol/includes/themes/_index.scss Outdated
@stephaniehobson stephaniehobson mentioned this pull request Jan 7, 2026
Open
4 of 8 tasks
@stephaniehobson

stephaniehobson commented Jan 9, 2026

Copy link
Copy Markdown
Contributor Author

No visual regressions found running #1106 locally.

stephaniehobson
stephaniehobson commented Jan 9, 2026
View reviewed changes
Comment thread assets/sass/protocol/components/_language-switcher.scss Outdated
stephaniehobson
stephaniehobson commented Jan 9, 2026
View reviewed changes
Comment thread 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)

@stephaniehobson stephaniehobson Jan 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

stephaniehobson
stephaniehobson commented Jan 9, 2026
View reviewed changes
Comment thread claude.md Outdated
@stephaniehobson
stephaniehobson force-pushed the font-vars branch 3 times, most recently from 1599e07 to 0ec134f Compare January 9, 2026 17:54
stephaniehobson
stephaniehobson commented Jan 9, 2026
View reviewed changes
Comment thread assets/sass/protocol/includes/forms/_index.scss
line-height: $text-body-line-height;
margin: 0;
padding-bottom: $label-v-spacing;
@include text-body-sm;

@stephaniehobson stephaniehobson Jan 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@stephaniehobson
stephaniehobson force-pushed the font-vars branch 10 times, most recently from ed88390 to 19ab519 Compare January 9, 2026 20:04
@stephaniehobson
stephaniehobson marked this pull request as ready for review January 9, 2026 20:06
@stephaniehobson
Refactor typography system to use CSS custom properties
b3d5a33 
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 maureenlholland self-assigned this Jan 12, 2026
maureenlholland
maureenlholland approved these changes Jan 12, 2026
View reviewed changes

@maureenlholland maureenlholland left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

r+ 📏

@maureenlholland
maureenlholland merged commit 865863d into main Jan 12, 2026
1 check passed
@maureenlholland
maureenlholland deleted the font-vars branch January 12, 2026 15:17
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
b853162 
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
@stephaniehobson stephaniehobson mentioned this pull request Jan 15, 2026
Merged
2 tasks done
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
1a9bc74 
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
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
12fb0b8 
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
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
24b0eda 
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
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
c061251 
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
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
4d0cd19 
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
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
9934957 
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
stephaniehobson added a commit that referenced this pull request Jan 15, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
81337f1 
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
stephaniehobson added a commit that referenced this pull request Jan 16, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
5993295 
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
stephaniehobson added a commit that referenced this pull request Jan 20, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
8cc84e9 
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
stephaniehobson added a commit that referenced this pull request Jan 20, 2026
@stephaniehobson
Refactor color to use CSS custom properties (#982)
1794a46 
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
stephaniehobson added a commit that referenced this pull request Jan 21, 2026
@stephaniehobson @claude
Refactor spacing to use CSS custom properties (#982)
082affd 
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>
stephaniehobson added a commit that referenced this pull request Jan 21, 2026
@stephaniehobson @claude
Refactor spacing to use CSS custom properties (#982)
d77602f 
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>
@stephaniehobson stephaniehobson mentioned this pull request Jan 21, 2026
Merged
2 tasks done
stephaniehobson added a commit that referenced this pull request Jan 21, 2026
@stephaniehobson @claude
Refactor spacing to use CSS custom properties (#982)
f566a57 
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>
stephaniehobson added a commit that referenced this pull request Jan 23, 2026
@stephaniehobson @claude
Refactor spacing to use CSS custom properties (#982) (#1114)
fcf9016 
* 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 stephaniehobson mentioned this pull request Sep 9, 2026
Merged
2 tasks done
stephaniehobson added a commit that referenced this pull request Sep 16, 2026
@stephaniehobson
Rename component -title/-subtitle classes to -heading/-subheading (#668)
0ba7189 
Finishes the component-class half of the title -> heading rename that
PR") -- the branch that originally held this work no longer exists,
so this redoes it against current main.

Mixins, utility classes, and CSS vars were already renamed in #1107;
this covers the remaining 12 component-level BEM classes across
Article, Billboard, Callout, Card, Form, Menu, Menu Item, Menu List,
Newsletter, Sidebar Menu, and Sticky Promo:

  mzp-c-menu-title           -> mzp-c-menu-heading
  mzp-c-form-title           -> mzp-c-form-heading
  mzp-c-form-subtitle        -> mzp-c-form-subheading
  mzp-c-card-title           -> mzp-c-card-heading
  mzp-c-menu-item-title      -> mzp-c-menu-item-heading
  mzp-c-callout-title        -> mzp-c-callout-heading
  mzp-c-sticky-promo-title   -> mzp-c-sticky-promo-heading
  mzp-c-newsletter-title     -> mzp-c-newsletter-heading
  mzp-c-menu-list-title      -> mzp-c-menu-list-heading
  mzp-c-sidemenu-title       -> mzp-c-sidemenu-heading
  mzp-c-billboard-title      -> mzp-c-billboard-heading
  mzp-c-article-title        -> mzp-c-article-heading

Clean break, no aliases, per the naming issue's own note that this is
a breaking rename (#668).

Also:
- Renamed the two already-heading-only-content files that still had
  the stale filename: base/elements/_titles.scss and
  base/utilities/_titles.scss -> _headings.scss (updated their @use
  sites and kept the alphabetical @use ordering in _elements.scss and
  protocol.scss)
- Renamed the forms/07-titles component directory and titles.html to
  07-headings/headings.html; reworded its readme, which still said
  "titles (aka headings)"
- Updated the 8 .mzp-c-menu-title selectors in assets/js/protocol/menu.js
- Fixed tests/unit/menu.js's fixture markup, which still built a
  .mzp-c-menu-title element -- missed by a first pass that only
  searched assets/ and components/
- Extended docs/02-usage/migration.md with find/replace recipes for
  this rename, matching the existing style

docs/03-contributing/02-naming.md's example already used -heading/-desc
and needed no change here.

Verified: npm run lint, npm test (47 specs, Firefox + Chrome),
npm run build-docs (523 items, no errors -- confirmed the renamed
forms/headings component renders with the new classes), and
npm run build-package all pass.
stephaniehobson added a commit that referenced this pull request Sep 29, 2026
@stephaniehobson
Rename component -title/-subtitle classes to -heading/-subheading (#668…
472f050 
…) (#1136)

* Rename component -title/-subtitle classes to -heading/-subheading (#668)

Finishes the component-class half of the title -> heading rename that
PR") -- the branch that originally held this work no longer exists,
so this redoes it against current main.

Mixins, utility classes, and CSS vars were already renamed in #1107;
this covers the remaining 12 component-level BEM classes across
Article, Billboard, Callout, Card, Form, Menu, Menu Item, Menu List,
Newsletter, Sidebar Menu, and Sticky Promo:

  mzp-c-menu-title           -> mzp-c-menu-heading
  mzp-c-form-title           -> mzp-c-form-heading
  mzp-c-form-subtitle        -> mzp-c-form-subheading
  mzp-c-card-title           -> mzp-c-card-heading
  mzp-c-menu-item-title      -> mzp-c-menu-item-heading
  mzp-c-callout-title        -> mzp-c-callout-heading
  mzp-c-sticky-promo-title   -> mzp-c-sticky-promo-heading
  mzp-c-newsletter-title     -> mzp-c-newsletter-heading
  mzp-c-menu-list-title      -> mzp-c-menu-list-heading
  mzp-c-sidemenu-title       -> mzp-c-sidemenu-heading
  mzp-c-billboard-title      -> mzp-c-billboard-heading
  mzp-c-article-title        -> mzp-c-article-heading

Clean break, no aliases, per the naming issue's own note that this is
a breaking rename (#668).

Also:
- Renamed the two already-heading-only-content files that still had
  the stale filename: base/elements/_titles.scss and
  base/utilities/_titles.scss -> _headings.scss (updated their @use
  sites and kept the alphabetical @use ordering in _elements.scss and
  protocol.scss)
- Renamed the forms/07-titles component directory and titles.html to
  07-headings/headings.html; reworded its readme, which still said
  "titles (aka headings)"
- Updated the 8 .mzp-c-menu-title selectors in assets/js/protocol/menu.js
- Fixed tests/unit/menu.js's fixture markup, which still built a
  .mzp-c-menu-title element -- missed by a first pass that only
  searched assets/ and components/
- Extended docs/02-usage/migration.md with find/replace recipes for
  this rename, matching the existing style

docs/03-contributing/02-naming.md's example already used -heading/-desc
and needed no change here.

Verified: npm run lint, npm test (47 specs, Firefox + Chrome),
npm run build-docs (523 items, no errors -- confirmed the renamed
forms/headings component renders with the new classes), and
npm run build-package all pass.

* review fixes
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
+1 more reviewer
@maureenlholland maureenlholland maureenlholland approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

@maureenlholland maureenlholland

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@stephaniehobson @maureenlholland