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

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

assets/sass/protocol/components/_breadcrumb.scss

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


❄️ 🤷‍♀️

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

assets/sass/protocol/root/_spacing.scss

-    --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

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

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

-    @media #{$mq-md} {


🧹 🧹 🧹

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

assets/sass/protocol/components/_split.scss


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


maureenlholland · 2026-01-22T15:02:25Z

assets/sass/protocol/components/_split.scss

-
-        .mzp-l-split-reversed & {
-            @include bidi(((float, left, right),));
+        .mzp-c-split-container & { // extra specificitly to over-ride the styles that make the float fall-back work


maintenance (non-blocking) is there still a float fallback here? we can remove float comments if fallback is fully removed

maureenlholland · 2026-01-22T15:05:27Z

assets/sass/protocol/components/_split.scss


 @media #{$mq-md} {
    .mzp-c-split {
        // horizontal alignment works with float fallbacks.


maintenance (non-blocking) remove float fallback comments (if we've removed the float fallback)

maureenlholland · 2026-01-22T15:50:36Z

components/card/readme.md

 - `mzp-has-audio`

 The default Card size with no other modifier classes is small:
 - Small sized cards can contain images with 16:9, 3:2 or 1:1 aspect ratios.


docs (non-blocking) Line above reads "The default Card size with no other modifier classes is small". Update default to medium.

maureenlholland · 2026-01-22T15:52:50Z

components/section-heading/readme.md

+### No Space: `mzp-t-section-heading-nospace`
+
+Use this theme class to remove vertical padding from the section heading. This is
+useful when you need tighter control over spacing in custom layouts or when the


👍 appreciate the "this is useful" detail

maureenlholland · 2026-01-22T16:15:32Z

components/card/card.config.yml

-        maximum of 150 characters.
  - name: Small
    context:
      class: 'mzp-has-aspect-1-1 mzp-has-audio'


docs (non-blocking): otherwise there's no difference in the small/medium demo cards

Suggested change

class: 'mzp-has-aspect-1-1 mzp-has-audio'

class: 'mzp-c-card-small mzp-has-aspect-1-1 mzp-has-audio'

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

stephaniehobson commented Jan 21, 2026

View reviewed changes

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

Copilot AI 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

	class: 'mzp-has-aspect-1-1 mzp-has-audio'
	class: 'mzp-c-card-small mzp-has-aspect-1-1 mzp-has-audio'

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

Are you sure you want to change the base?

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

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!

Choose a reason for hiding this comment

Uh oh!

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!

Copilot AI 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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