DSE-378 :: Spacing hard cut and token alignment by diogo-filipe-costa · Pull Request #182 · ourfuturehealth/design-system-toolkit

diogo-filipe-costa · 2026-03-20T15:20:09Z

Description

This PR delivers DSE-378 spacing alignment across the toolkit and docs site.

It goes beyond a simple Figma rename pass. This branch removes the legacy point-based spacing helpers, utility suffixes, and old unified responsive spacing map so the toolkit uses only the current Figma-aligned spacing scales and token model.

Ticket: DSE-378

Scope

This is PR 1 of 2 in the spacing and typography migration.
The stacked follow-up PR contains the typography hard cut and consumer migration guide.
The Figma token sync automation workflow is intentionally out of scope for this PR.

Breaking Changes

Removed ofh-spacing(...)
Removed $ofh-spacing-points
Removed $ofh-space-responsive-scale
ofh-responsive-margin(...) and ofh-responsive-padding(...) now use the Figma-aligned size keys instead of point indices
Spacing utility classes now use Figma-aligned size keys as their suffixes instead of point indices
all spacing now combines the vertical scale for top and bottom with the horizontal scale for left and right

Key Changes

1) Token groundwork for the spacing model

Aligned the toolkit token source files to the current Figma token model
Renamed the stale background neutral tokens to the current backgrounds-* naming
Corrected the blue-royal-4 token naming so the token source matches the active design tokens
Split the responsive spacing token model into:
- $ofh-space-horizontal-responsive-scale
- $ofh-space-vertical-responsive-scale
Updated site references that still pointed at pre-alignment token names

2) Hard cut of the legacy spacing API

Removed the legacy point-based ofh-spacing(...) helper from the toolkit core
Removed the old point-based spacing utility generation
Migrated toolkit and site spacing call sites to use:
- $ofh-size-* static tokens
- Figma-aligned responsive spacing keys
Preserved the responsive mixin names while changing them to the new spacing model
Updated the internal spacing helpers so horizontal, vertical, and all now reflect the real split scales from Figma

3) Docs and examples updated to teach the new spacing model only

Refreshed spacing documentation to stop teaching the removed point-based API
Updated the standalone spacing examples to use the new scale keys
Improved the spacing demo so the spacing examples are legible and useful during manual QA
Updated affected site examples and component examples so they validate the new spacing surface instead of legacy helpers

Validation

pnpm lint
npm test
Manual QA on local docs/examples for:
- spacing docs and standalone spacing examples
- card and page-template examples
- header and footer examples
- form and error-summary spacing surfaces

Reviewer Focus

Correctness of the token groundwork that the spacing hard cut depends on
Replacement of legacy point-based spacing helpers and utility suffixes
Behaviour changes for horizontal, vertical, and especially all
Site/docs examples teaching only the new spacing model

netlify · 2026-03-20T15:20:16Z

✅ Deploy Preview for ofh-design-system-docs ready!

Name	Link
🔨 Latest commit	`bdbd9e2`
🔍 Latest deploy log	https://app.netlify.com/projects/ofh-design-system-docs/deploys/69c264137a03a400087694b3
😎 Deploy Preview	https://deploy-preview-182--ofh-design-system-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Rename mismatched toolkit token names to the current Figma model and update breakpoint token definitions to match live variables. Split responsive spacing into horizontal and vertical scales and align typography and iconography token maps with the current design tokens. Prepare the toolkit helper and utility layers for the aligned token structure before the hard-cut migration work.

Update docs site styles that still referenced renamed toolkit tokens. Refresh the colour documentation to show the aligned token names. Keep the docs site output consistent with the toolkit token source changes.

Remove the legacy point-based spacing helper and legacy spacing utility generation from the toolkit core. Migrate toolkit and site spacing call sites to Figma-aligned responsive size keys and static -size-* tokens. Refresh spacing documentation and upgrade notes so consumers move to the new horizontal and vertical spacing scales.

Make the spacing demo legible on the docs site and explain what the standalone example is showing. Carry the spacing-specific QA refinements onto the spacing review branch without pulling in the later typography example cleanup.

Copilot

Pull request overview

Hard-cuts the toolkit and docs site over to Figma-aligned spacing (and related token/typography alignment), removing legacy point-based spacing helpers and updating utilities/mixins, source styles, and documentation/examples accordingly.

Changes:

Replaced legacy ofh-spacing(...) usage with $ofh-size-* tokens and updated responsive spacing to accept Figma-aligned size keys.
Split responsive spacing into horizontal/vertical scales and updated all spacing behavior to use vertical for top/bottom and horizontal for left/right.
Updated typography scale keys to Figma-aligned names while adding aliases + utility classes to preserve legacy size names.

Reviewed changes

Copilot reviewed 132 out of 132 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/toolkit/core/utilities/_typography.scss	Adds legacy typography size utility aliases alongside new scale keys.
packages/toolkit/core/utilities/_spacing.scss	Updates spacing utility generation to iterate Figma-aligned responsive size keys.
packages/toolkit/core/tools/_typography.scss	Adds typography size alias resolution to support legacy keys with new scale keys.
packages/toolkit/core/tools/_spacing.scss	Reworks responsive spacing to use separate horizontal/vertical scales and new `all` behavior.
packages/toolkit/core/tools/_mixins.scss	Migrates internal mixin spacing usage to size keys/tokens.
packages/toolkit/core/styles/_typography.scss	Updates core typography styles to new spacing keys/tokens.
packages/toolkit/core/styles/_section-break.scss	Updates section-break spacing to Figma-aligned size keys.
packages/toolkit/core/styles/_lists.scss	Updates list spacing to Figma-aligned size keys.
packages/toolkit/core/settings/_tokens-static.scss	Renames secondary background tokens to `backgrounds-*` naming.
packages/toolkit/core/settings/_tokens-core.scss	Corrects blue-royal token naming and renames background neutral tokens.
packages/toolkit/core/settings/_tokens-breakpoint.scss	Splits responsive spacing into horizontal/vertical scales; renames typography scale keys; updates other responsive tokens.
packages/toolkit/core/objects/_main-wrapper.scss	Updates wrapper padding to Figma-aligned size keys.
packages/toolkit/core/objects/_form-group.scss	Updates form-group spacing to new tokens/keys.
packages/toolkit/core/elements/_table.scss	Updates table spacing to new responsive size keys.
packages/toolkit/core/README.md	Updates spacing utility documentation examples to new suffix keys.
packages/toolkit/components/textarea/_textarea.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/toolkit/components/task-list/_task-list.scss	Updates component spacing to new tokens/keys.
packages/toolkit/components/tag/_tag.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/toolkit/components/tables/_tables.scss	Updates table component spacing to new tokens/keys.
packages/toolkit/components/summary-list/_summary-list.scss	Updates summary-list spacing to new tokens/keys.
packages/toolkit/components/status-flag/_status-flag.scss	Updates status-flag spacing to new responsive size keys.
packages/toolkit/components/skip-link/_skip-link.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/toolkit/components/select/_select.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/toolkit/components/radios/_radios.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/toolkit/components/pagination/_pagination.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/toolkit/components/label/_label.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/toolkit/components/inset-text/_inset-text.scss	Updates inset-text spacing to new responsive size keys.
packages/toolkit/components/input/_input.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/toolkit/components/images/_images.scss	Updates image spacing/padding to new tokens/keys.
packages/toolkit/components/hint/_hint.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/toolkit/components/hero/template.njk	Updates spacing utility class suffixes to size keys.
packages/toolkit/components/hero/_hero.scss	Migrates hero spacing to new tokens/keys.
packages/toolkit/components/hero/README.md	Updates hero docs examples to new spacing utility suffixes.
packages/toolkit/components/header/_header.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates related comments/math.
packages/toolkit/components/footer/_footer.scss	Updates footer padding/border spacing to new tokens/keys.
packages/toolkit/components/fieldset/_fieldset.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/toolkit/components/error-summary/_error-summary.scss	Updates error summary spacing to new responsive size keys.
packages/toolkit/components/error-message/_error-message.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/toolkit/components/details/_details.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/toolkit/components/date-input/_date-input.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/toolkit/components/contents-list/_contents-list.scss	Replaces `ofh-spacing` with `$ofh-size-*` token and updates responsive spacing keys.
packages/toolkit/components/checkboxes/_checkboxes.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/toolkit/components/character-count/_character-count.scss	Updates spacing to new tokens/keys.
packages/toolkit/components/card/template.njk	Updates spacing utility class suffix to size key.
packages/toolkit/components/card/card.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/toolkit/components/card/README.md	Updates examples to new spacing utility suffix keys.
packages/toolkit/components/button/_button.scss	Updates button spacing to new responsive size keys.
packages/toolkit/components/back-link/_back-link.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/toolkit/components/action-link/_action-link.scss	Updates action-link spacing to new responsive size keys.
packages/site/views/index.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/get-started/guidance-for-dev/index.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/examples/standalone/landing/index.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/examples/components/typography.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/examples/components/card/card-group.njk	Updates spacing utility class suffixes inside card examples.
packages/site/views/examples/components/all.njk	Updates spacing utility class suffixes inside aggregated examples.
packages/site/views/design-system/styles/typography/index.njk	Updates spacing utility class suffixes used in side nav/back link layout.
packages/site/views/design-system/styles/spacing/text/index.njk	Updates spacing demo text utilities to size keys.
packages/site/views/design-system/styles/spacing/index.njk	Rewrites spacing guidance/docs for new size-key model and split scales.
packages/site/views/design-system/styles/spacing/default/index.njk	Updates spacing example markup to size keys + adds labels for QA legibility.
packages/site/views/design-system/styles/page-template/transactional/index.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/design-system/styles/page-template/index.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/design-system/styles/layout/index.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/design-system/styles/icons/index.njk	Updates spacing utility class suffixes to size keys.
packages/site/views/design-system/styles/colour/index.njk	Updates spacing utilities and token names displayed in docs (backgrounds + blue-royal token).
packages/site/views/design-system/patterns/reassure-users-that-a-page-is-up-to-date/page/index.njk	Updates spacing utilities to size keys for review-date pattern page.
packages/site/views/design-system/patterns/reassure-users-that-a-page-is-up-to-date/index.njk	Updates spacing utilities to size keys for pattern content.
packages/site/views/design-system/patterns/reassure-users-that-a-page-is-up-to-date/default/index.njk	Updates spacing utilities to size keys in pattern example.
packages/site/views/design-system/patterns/mini-hub/index.njk	Updates spacing utilities to size keys in pattern guidance.
packages/site/views/design-system/patterns/mini-hub/example/index.njk	Updates spacing utilities to size keys in pattern example.
packages/site/views/design-system/patterns/mini-hub/example-symptoms/index.njk	Updates spacing utilities to size keys in pattern example.
packages/site/views/design-system/patterns/ask-users-for-their-nhs-number/filter/index.njk	Updates spacing utilities to size keys for hint spacing.
packages/site/views/design-system/patterns/ask-users-for-their-nhs-number/filter-third/index.njk	Updates spacing utilities to size keys for hint spacing.
packages/site/views/design-system/patterns/a-to-z-page/navigation/index.njk	Updates spacing utilities to size keys (margin/padding) for A–Z nav.
packages/site/views/design-system/patterns/a-to-z-page/default/index.njk	Updates spacing utilities to size keys in default pattern example.
packages/site/views/design-system/components/review-date/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/radios/with-hints/index.njk	Updates spacing utilities to size keys for hint spacing.
packages/site/views/design-system/components/images/index.njk	Updates spacing utilities to size keys in component docs.
packages/site/views/design-system/components/hint-text/radios/index.njk	Updates spacing utilities to size keys for hint spacing.
packages/site/views/design-system/components/error-summary/placement/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/error-summary/placement-multiple/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/error-summary/placement-input/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/error-message/error-summary-placement/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/error-message/error-summary-placement-multiple/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/error-message/error-summary-placement-input/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/care-cards/index.njk	Updates spacing utilities to size keys.
packages/site/views/design-system/components/card/group-quarter/index.njk	Updates spacing utilities to size keys inside card examples.
packages/site/views/design-principles.njk	Updates spacing utilities to size keys in principles page layout.
packages/site/views/content/writing-for-readability.njk	Updates spacing utilities to size keys for featured-list layout.
packages/site/views/content/standard-for-creating-health-content.njk	Updates spacing utilities to size keys for featured-list layout.
packages/site/views/content/how-we-write.njk	Updates spacing utilities to size keys for inset text blocks.
packages/site/views/content/how-to-write-good-questions-for-forms/write-the-supporting-content-for-your-form.njk	Updates spacing utilities to size keys for hints/inset text.
packages/site/views/content/how-to-write-good-questions-for-forms/use-filter-questions-to-route-users.njk	Updates spacing utilities to size keys for images/hints.
packages/site/views/content/how-to-write-good-questions-for-forms/get-the-questions-into-order.njk	Updates spacing utilities to size keys for images.
packages/site/views/content/formatting-and-punctuation.njk	Updates spacing utilities to size keys for inset text blocks.
packages/site/views/content/a-to-z-of-nhs-health-writing.njk	Updates spacing utilities to size keys for A–Z nav.
packages/site/views/accessibility/partials/use-alternative-text-for-images-in-content.njk	Updates spacing utilities to size keys for image layout.
packages/site/views/_includes/app-layout.njk	Updates spacing utilities to size keys for “Updated” meta spacing.
packages/site/views/_includes/app-layout-two-thirds.njk	Updates spacing utilities to size keys for “Updated” meta spacing.
packages/site/views/_includes/_side-nav.njk	Updates spacing utilities to size keys for back-link spacing.
packages/site/views/_includes/_feedback-banner.njk	Updates spacing utilities to size keys for banner spacing.
packages/site/views/_includes/_contact-panel.njk	Updates spacing utilities to size keys for contact panel layout.
packages/site/styles/main.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/site/styles/design-example/_design-example.scss	Updates example layout spacing to size keys/tokens.
packages/site/styles/design-example-overrides.scss	Updates spacing example styling for clearer QA with new example markup.
packages/site/styles/app/_side-nav.scss	Migrates side nav spacing to new tokens/keys.
packages/site/styles/app/_related-nav.scss	Migrates related nav spacing to new tokens/keys.
packages/site/styles/app/_promo-video.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/site/styles/app/_pane.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/site/styles/app/_page-contents.scss	Updates page-contents spacing to new responsive size keys.
packages/site/styles/app/_meta-data.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/site/styles/app/_lede-text.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/site/styles/app/_homepage.scss	Updates homepage section spacing to new responsive size keys.
packages/site/styles/app/_health-az.scss	Updates Health A–Z spacing to new tokens/keys.
packages/site/styles/app/_footer.scss	Updates footer spacing to new tokens/keys.
packages/site/styles/app/_featured-list.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/site/styles/app/_example-callout.scss	Updates example callout spacing to new responsive size keys.
packages/site/styles/app/_container.scss	Replaces `ofh-spacing` with `$ofh-size-*` token.
packages/site/styles/app/_contact-panel.scss	Updates contact-panel spacing to new responsive size keys.
packages/site/styles/app/_colour-swatch.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/site/styles/app/_code-highlight.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens and updates responsive spacing keys.
packages/site/styles/app/_code-block.scss	Updates code block margin spacing to new responsive size keys.
packages/site/styles/app/_beta-banner.scss	Replaces `ofh-spacing` with `$ofh-size-*` tokens.
packages/site/components/inset-text/_inset-text.scss	Updates DS inset-text spacing to new responsive size keys.
packages/site/components/hero/template.njk	Updates spacing utility class suffixes to size keys.
packages/site/components/hero/_hero.scss	Updates hero spacing + background token to `backgrounds-*` naming.
packages/site/components/hero/README.md	Updates hero docs examples to new spacing utility suffixes.
packages/site/components/header/_header.scss	Updates header spacing + background token to `backgrounds-*` naming.
packages/site/components/footer/_footer.scss	Updates footer spacing to new tokens/keys.
packages/site/components/card/_inset-text.scss	Updates card inset-text spacing to new responsive size keys.
packages/site/components/card/_card.scss	Updates card spacing to new tokens/keys.
UPGRADING.md	Adds v4.5.0 migration guidance for spacing API hard cut.
CHANGELOG.md	Documents toolkit v4.5.0 release and breaking spacing changes.

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

packages/toolkit/core/tools/_spacing.scss

Update the responsive spacing type error so it reports the expected map type and points maintainers to the current breakpoint token source.

Update the spacing reference tables to show Desktop, Tablet, and Mobile in the same order designers use as the main size reference. Correct the override class guidance so the docs explain the real horizontal and vertical scale behavior instead of implying fixed values. Tighten the width override docs so they match the responsive utility output on mobile and tablet-plus screens.

diogo-filipe-costa added 4 commits March 20, 2026 15:24

chore(site): update docs site token references

ac13c72

Update docs site styles that still referenced renamed toolkit tokens. Refresh the colour documentation to show the aligned token names. Keep the docs site output consistent with the toolkit token source changes.

docs(site): clarify spacing migration examples

3ee9289

Make the spacing demo legible on the docs site and explain what the standalone example is showing. Carry the spacing-specific QA refinements onto the spacing review branch without pulling in the later typography example cleanup.

diogo-filipe-costa force-pushed the codex/spacing-cut branch from 8ed1bb8 to 3ee9289 Compare March 20, 2026 15:38

diogo-filipe-costa changed the title ~~codex/spacing cut~~ DSE-378 :: Spacing hard cut and token alignment Mar 20, 2026

diogo-filipe-costa mentioned this pull request Mar 20, 2026

DSE-379 :: Typography hard cut and migration guide #183

Open

diogo-filipe-costa requested a review from Copilot March 20, 2026 16:34

diogo-filipe-costa self-assigned this Mar 20, 2026

Copilot started reviewing on behalf of diogo-filipe-costa March 20, 2026 16:34 View session

diogo-filipe-costa requested review from cfgreene, jpsanders101, rmds16, willmcb and wotton-software March 20, 2026 16:35

Copilot AI reviewed Mar 20, 2026

View reviewed changes

packages/toolkit/core/tools/_spacing.scss Show resolved Hide resolved

diogo-filipe-costa added 2 commits March 23, 2026 10:00

fix(spacing): clarify responsive scale error

50f9e14

Update the responsive spacing type error so it reports the expected map type and points maintainers to the current breakpoint token source.

diogo-filipe-costa marked this pull request as ready for review March 24, 2026 11:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DSE-378 :: Spacing hard cut and token alignment#182

DSE-378 :: Spacing hard cut and token alignment#182
diogo-filipe-costa wants to merge 6 commits intomainfrom
codex/spacing-cut

diogo-filipe-costa commented Mar 20, 2026 •

edited

Loading

Uh oh!

netlify bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Conversation

diogo-filipe-costa commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Scope

Breaking Changes

Key Changes

1) Token groundwork for the spacing model

2) Hard cut of the legacy spacing API

3) Docs and examples updated to teach the new spacing model only

Validation

Reviewer Focus

Uh oh!

netlify bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ofh-design-system-docs ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

diogo-filipe-costa commented Mar 20, 2026 •

edited

Loading

netlify bot commented Mar 20, 2026 •

edited

Loading