Refactor spacing to use CSS custom properties (#982) by stephaniehobson · Pull Request #1114 · mozilla/protocol

stephaniehobson · 2026-01-21T23:14:01Z

Description

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 (#1109) refactors. Introduces --theme-spacing-between-block and --theme-spacing-between-inline for responsive layout spacing while retaining Sass $spacing-* variables for component-internal spacing. (We do need to standardize that but it's not nearly as straight forward)

Modernization:
- Default to CSS vars for layout spacing (block and inline)
- Removed float fallbacks in callout, split and card layout
- 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)
- Removed max-width restrictions from cards, they will always fill the available space now
  - moved image size recommendations off individual card sizes and onto the parent
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

Issue

#982

Testing

Spot-check.

There are some expected visual regressions in section headings and the card documentation (but not the cards themselves). And the layout spacing has changed in some places where it needed standardization.

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

stephaniehobson · 2026-01-21T23:14:29Z

This will address some of what's in #1099 (comment) too.

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 · 2026-01-21T23:23:50Z

 margin: 0 auto;
 max-width: $content-max;
- padding: 0 $h-grid-xs;
+ padding: 0 $layout-xs;


❄️ 🤷‍♀️

stephaniehobson · 2026-01-21T23:29:39Z

- --h-grid-xl: 80px;
+ @media #{tokens.$mq-xl} {
+ --theme-spacing-between-block: #{tokens.$layout-xl}; // 96px
+ --theme-spacing-between-inline: 80px;


❄️ 🤷‍♀️

stephaniehobson · 2026-01-21T23:31:06Z

Can I remove floats from hero layout?

Edit: No, there's no grid based fallback so I'm going to consider this one out of scope.

Copilot

Pull request overview

This PR refactors the spacing system to use CSS custom properties (--theme-spacing-between-block and --theme-spacing-between-inline) for responsive layout spacing, following previous typography and color refactors. It modernizes the codebase by removing legacy fallbacks and deprecated variables while simplifying component implementations.

Changes:

Introduced new CSS custom properties for spacing that are responsive across breakpoints
Renamed card size classes (mzp-c-card-extra-small → mzp-c-card-small) and removed mzp-c-card-medium as the default
Removed legacy Sass spacing variables, float-based fallbacks, and deprecated grid-gap shorthand

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
theme/assets/sass/components/_grid-list.scss	Updated `grid-gap` to standard `gap` property
theme/assets/sass/components/_color.scss	Updated `grid-gap` to standard `gap` property
docs/02-usage/migration.md	Added migration guide for card component changes
components/section-heading/readme.md	Documented new `mzp-t-section-heading-nospace` theme class
components/navigation/02-menu/readme.md	Updated reference from Extra Small Card to Small Card
components/navigation/02-menu/menu.html	Updated card class from `mzp-c-card-extra-small` to `mzp-c-card-small`
components/layout/03-card-layout/card-layout.config.yml	Updated card size recommendations in layout documentation
components/layout/03-card-layout/03-card-layout--quarter.html	Updated card renders to use `@card--small` instead of `@card--extra-small`
components/card/readme.md	Updated card size documentation and image size recommendations
components/card/card.config.yml	Removed extra-small variant, updated medium variant to be default
components/_preview-card.html	Added new preview template for card components
components/_preview-card-dark.html	Added new dark theme preview template for card components
assets/sass/protocol/templates/_multi-column.scss	Migrated to new spacing CSS variables and removed legacy fallbacks
assets/sass/protocol/templates/_card-layout.scss	Migrated to new spacing CSS variables and removed max-width restrictions
assets/sass/protocol/root/_spacing.scss	Replaced legacy grid variables with new theme spacing variables
assets/sass/protocol/includes/mixins/_utils.scss	Removed unused import of `themes-sass`
assets/sass/protocol/includes/_themes-sass.scss	Deleted file containing legacy Sass spacing variables
assets/sass/protocol/includes/_lib.scss	Removed forward of deleted `themes-sass` module
assets/sass/protocol/components/_split.scss	Migrated to new spacing variables and removed float-based fallbacks
assets/sass/protocol/components/_section-heading.scss	Migrated to new spacing variables and added nospace theme class
assets/sass/protocol/components/_newsletter-form.scss	Migrated to new spacing variables and removed float-based fallbacks
assets/sass/protocol/components/_navigation.scss	Simplified spacing with new CSS variables
assets/sass/protocol/components/_card.scss	Renamed extra-small to small, removed medium class, removed max-width restrictions
assets/sass/protocol/components/_callout.scss	Migrated to new spacing variables and removed float-based fallbacks
assets/sass/protocol/components/_breadcrumb.scss	Migrated to new spacing variables
assets/sass/protocol/base/elements/_containers.scss	Migrated to new spacing variables and removed legacy fallbacks
assets/sass/protocol/base/elements/_common.scss	Migrated hr element spacing to new CSS variables
CHANGELOG.md	Documented spacing system changes and card component updates
.stylelintrc.json	Removed deprecated `grid-gap` from ignored shorthands list

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

maureenlholland

r+wc 💫

Non-blocking stuff, doesn't affect actual styles

It's unclear from comments whether we removed the float fallback in Split component

Card demo/docs still has places where it assumes small is default

maureenlholland · 2026-01-22T14:55:42Z

+ padding: var(--theme-spacing-between-block) var(--theme-spacing-between-inline);
 position: relative;

- @media #{$mq-md} {


🧹 🧹 🧹

maureenlholland · 2026-01-22T14:58:30Z


 .mzp-l-split-reversed & {
-@include bidi(((float, right, left),));
+grid-template-areas: 'media body';


stephaniehobson force-pushed the spacing-vars branch from d77602f to f566a57Compare January 21, 2026 23:21

stephaniehobson commented Jan 21, 2026
View reviewed changes

stephaniehobson requested a review from Copilot January 21, 2026 23:30

CopilotAI reviewed Jan 21, 2026
View reviewed changes

stephaniehobson marked this pull request as draft January 21, 2026 23:31

stephaniehobson marked this pull request as ready for review January 22, 2026 00:11

stephaniehobson requested a review from maureenlholland January 22, 2026 00:12

maureenlholland self-assigned this Jan 22, 2026

maureenlholland approved these changes Jan 22, 2026
View reviewed changes

review fixes
50a11e1

stephaniehobson merged commit fcf9016 into mainJan 23, 2026
1 check passed

stephaniehobson deleted the spacing-vars branch January 23, 2026 16:31

stephaniehobson mentioned this pull request Jan 23, 2026
Protocol v23 #1084
Open

Navigation Menu

Uh oh!

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

Refactor spacing to use CSS custom properties (#982)#1114
stephaniehobson merged 2 commits into
mainfrom
spacing-vars

stephaniehobson commented Jan 21, 2026•
edited
Loading

Uh oh!

stephaniehobson commented Jan 21, 2026

Uh oh!

stephaniehobsonJan 21, 2026

Uh oh!

stephaniehobsonJan 21, 2026

Uh oh!

stephaniehobson commented Jan 21, 2026•
edited
Loading

Uh oh!

CopilotAI left a comment

Uh oh!

maureenlholland left a comment

Uh oh!

maureenlhollandJan 22, 2026

Uh oh!

maureenlhollandJan 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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

Uh oh!

Description

Issue

Testing

Uh oh!

stephaniehobson commented Jan 21, 2026

Uh oh!

stephaniehobsonJan 21, 2026

Choose a reason for hiding this comment

Uh oh!

stephaniehobsonJan 21, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

maureenlholland left a comment

Choose a reason for hiding this comment

Uh oh!

maureenlhollandJan 22, 2026

Choose a reason for hiding this comment

Uh oh!

maureenlhollandJan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stephaniehobson commented Jan 21, 2026•
edited
Loading

stephaniehobson commented Jan 21, 2026•
edited
Loading