DSE-379 :: Typography hard cut and migration guide by diogo-filipe-costa · Pull Request #183 · ourfuturehealth/design-system-toolkit

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

Description

This PR delivers DSE-379 typography alignment across the toolkit and docs site.

It goes beyond a simple alignment with Figma. This branch removes the legacy direct typography aliases, removes the old direct heading class surface, updates utilities and docs to use only the newer Figma-aligned scale names, and adds migration guidance for consumers upgrading to the new typography and token model.

Ticket: DSE-379

Scope

This is PR 2 of 2 in the spacing and typography migration.
This PR is stacked on top of DSE-378 :: Spacing hard cut and token alignment #182.
The Figma token sync automation workflow is intentionally out of scope for this PR.
This PR carries the toolkit v4.5.0 migration guidance for the spacing, typography, and token changes in this migration track.

Breaking Changes

Removed legacy direct key support from:
- ofh-typography-responsive(...)
- ofh-font(...)
Direct typography keys now use the Figma-aligned names:
- heading-xl, heading-lg, heading-md, heading-sm, heading-xs
- lead-md, paragraph-md, paragraph-sm, list-md, list-sm
Renamed direct heading classes:
- ofh-heading-l -> ofh-heading-lg
- ofh-heading-m -> ofh-heading-md
- ofh-heading-s -> ofh-heading-sm
Renamed the direct typography utility class surface to match the new key names
Removed the internal-only ofh-heading-xxs alias and routed h6 straight to heading-xs

The remaining semantic typography APIs are intentionally unchanged in this PR:

ofh-body-l
ofh-body-m
ofh-body-s
ofh-caption-*
ofh-lede-text*

Key Changes

1) Hard cut of the legacy direct typography API

Replaced the old direct mixin keys across toolkit and site with the Figma-aligned key names
Removed direct alias support from the typography helpers and utilities
Renamed the direct heading classes from l/m/s to lg/md/sm
Removed the internal-only ofh-heading-xxs alias and routed h6 straight to heading-xs
Updated toolkit and site call sites so the public direct typography surface now matches the current Figma scale

2) Consumer migration guidance for the full v4.5.0 change set

Added a standalone migration guide for the v4.5.0 spacing, typography, and token changes
Covered both upgrade tracks:
- monorepo v4.4.x -> v4.5.0
- pre-monorepo v3.4.2 -> v4.5.0
Included the older numeric typography utility classes from v3.4.2, such as:
- ofh-u-font-size-64
- ofh-u-font-size-48
- ofh-u-font-size-32
- ofh-u-font-size-24
- ofh-u-font-size-22
- ofh-u-font-size-19
- ofh-u-font-size-16
- ofh-u-font-size-14
Reduced the top-level upgrading guide to a concise summary that points consumers to the standalone guide as the authoritative reference

3) Docs and examples refined as a real QA surface

Updated typography docs/examples to stop teaching removed direct aliases
Corrected stale ofh-body examples and typography utility examples that were masking real regressions
Refreshed docs metadata on the pages touched in this migration
Removed repeated showcase blocks so the typography examples are easier to validate and review

Validation

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

Reviewer Focus

Completeness of the direct typography alias removal
Correctness of the renamed heading class and typography utility surface
Accuracy and usefulness of the standalone consumer migration guide
Site/docs examples remaining reliable after the typography hard cut

Add a repo-local typography alias audit command that inventories semantic and legacy typography APIs, their current token basis, and local usage grouped by toolkit, site, and docs examples. Support optional org-wide GitHub code search via gh so maintainers can enrich the report with external consumer usage when rate limits allow. Extend the root lint script so the new audit tooling is checked alongside the existing Figma scripts.

Replace direct legacy typography mixin keys and direct heading classes across the toolkit and site with the Figma-aligned names. Remove direct alias support from the typography tools and utilities while keeping semantic typography APIs in place pending audit and design review. Bump @ourfuturehealth/toolkit to 4.5.0 and document the migration path in the changelog and upgrading guide.

Update the typography alias audit metadata to match the current Figma-aligned scale names. Align the recorded token basis and internal dependency descriptions with the renamed heading and body keys so the generated audit report reflects the real toolkit API.

Add a standalone migration guide for the v4.5.0 spacing, typography, and token changes. Cover both the monorepo and pre-monorepo upgrade tracks, including numeric typography utilities from v3.4.2 and the exact or intent-based replacements they require. Reduce the top-level upgrading section to a short summary and point consumers to the standalone guide as the authoritative reference.

Carry the QA-driven site example and docs fixes onto the stacked typography branch. Keep the spacing demo legible, fix stale typography examples and copy, refresh updated dates, and remove repeated showcase blocks so the docs remain a reliable validation surface.

Remove the internal-only ofh-heading-xxs alias and route h6 directly to the heading-xs styles. Clean up the typography examples, migration guide, and alias audit so the remaining semantic typography inventory no longer includes the removed alias.

Remove the temporary typography alias audit script and root package hooks from the typography migration branch. Keep the semantic typography APIs unchanged, and narrow the PR scope to the direct typography hard cut plus consumer migration guidance.

Copilot

Pull request overview

This PR completes the DSE-379 typography “hard cut” by removing legacy direct typography aliases/classes across the toolkit and docs site, aligning all usage to the Figma-scale key names, and adding a comprehensive v4.5.0 consumer migration guide covering spacing, typography, and token changes.

Changes:

Removed legacy direct typography alias support (mixin keys + utility aliases) and migrated toolkit/component SCSS to Figma-aligned typography keys.
Renamed direct heading class surface (ofh-heading-l/m/s → ofh-heading-lg/md/sm) and updated site/docs examples accordingly.
Added a standalone v4.5.0 migration guide and updated UPGRADING/CHANGELOG to reflect the new migration track.

Reviewed changes

Copilot reviewed 88 out of 88 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/toolkit/package.json	Bumps toolkit version to 4.5.0.
packages/toolkit/core/utilities/_typography.scss	Removes legacy numeric utility alias generation; utilities now follow typography scale keys.
packages/toolkit/core/tools/_typography.scss	Removes legacy size aliases and updates docs/examples for new key names.
packages/toolkit/core/tools/_mixins.scss	Updates mixin usage to new typography key (`heading-md`).
packages/toolkit/core/styles/_typography.scss	Renames heading placeholders/classes and updates internal typography mixin keys; removes `ofh-heading-xxs`.
packages/toolkit/core/styles/_lists.scss	Updates list typography key to `list-md`.
packages/toolkit/core/elements/_table.scss	Updates paragraph key and caption heading key.
packages/toolkit/components/textarea/_textarea.scss	Updates to `paragraph-md`.
packages/toolkit/components/task-list/_task-list.scss	Updates to `paragraph-md`.
packages/toolkit/components/tag/_tag.scss	Updates to `paragraph-sm`.
packages/toolkit/components/summary-list/_summary-list.scss	Updates to `paragraph-md`.
packages/toolkit/components/summary-list/README.md	Updates examples to semantic body class `ofh-body-m`.
packages/toolkit/components/status-flag/_status-flag.scss	Updates heading/body font keys.
packages/toolkit/components/select/_select.scss	Updates to `paragraph-md`.
packages/toolkit/components/radios/_radios.scss	Updates to `paragraph-md` for items/divider.
packages/toolkit/components/pagination/_pagination.scss	Updates lead/paragraph-small keys to `lead-md`/`paragraph-sm`.
packages/toolkit/components/label/_label.scss	Updates label and heading modifiers to new heading keys.
packages/toolkit/components/input/_input.scss	Updates input font key to `paragraph-md`.
packages/toolkit/components/images/_images.scss	Updates caption key to `paragraph-sm`.
packages/toolkit/components/hint/_hint.scss	Updates to `paragraph-md`.
packages/toolkit/components/header/_header.scss	Updates navigation/service-name font keys.
packages/toolkit/components/footer/_footer.scss	Updates footer font keys to `paragraph-sm`.
packages/toolkit/components/fieldset/_fieldset.scss	Updates legend font keys and heading modifier sizes.
packages/toolkit/components/error-summary/_error-summary.scss	Updates title/body font keys.
packages/toolkit/components/error-message/_error-message.scss	Updates error message font key.
packages/toolkit/components/details/_details.scss	Updates body typography key and contextual heading placeholder reference.
packages/toolkit/components/checkboxes/_checkboxes.scss	Updates item/divider font keys to `paragraph-md`.
packages/toolkit/components/card/card.scss	Updates heading adjacency selectors and card heading font key.
packages/toolkit/components/card/README.md	Updates heading classes and replaces old numeric font-size utilities with new key-based utilities.
packages/toolkit/components/button/_button.scss	Updates button typography key to `heading-xs`.
packages/toolkit/components/breadcrumb/_breadcrumb.scss	Updates breadcrumb font key to `paragraph-sm`.
packages/toolkit/components/back-link/_back-link.scss	Updates back-link key to `paragraph-sm`.
packages/toolkit/components/action-link/_action-link.scss	Updates action-link font key to `heading-sm`.
packages/site/views/index.njk	Updates homepage card headings to `ofh-heading-md`.
packages/site/views/get-started/index.njk	Updates card heading classes to `ofh-heading-md`.
packages/site/views/examples/components/typography.njk	Updates typography example surface to new heading classes/keys; removes repeated blocks.
packages/site/views/examples/components/card/feature-card.njk	Updates heading class to `ofh-heading-md`.
packages/site/views/examples/components/card/clickable-card.njk	Updates heading class to `ofh-heading-md`.
packages/site/views/examples/components/card/card-with-image.njk	Updates heading class to `ofh-heading-md`.
packages/site/views/examples/components/card/card-group.njk	Updates heading classes and font-size utility classes to new key-based utilities.
packages/site/views/examples/components/all.njk	Updates all-component examples to new heading classes and font-size utility classes.
packages/site/views/design-system/styles/typography/sizes/index.njk	Replaces numeric font-size utilities with key-based typography utilities.
packages/site/views/design-system/styles/typography/index.njk	Updates typography guidance text and reflects new utility naming and scale values.
packages/site/views/design-system/styles/typography/headings/index.njk	Updates heading class examples to `lg/md/sm` surface.
packages/site/views/design-system/styles/typography/body-m/index.njk	Updates example from deprecated `ofh-body` to `ofh-body-m`.
packages/site/views/design-system/styles/spacing/width/index.njk	Updates headings to `ofh-heading-md`.
packages/site/views/design-system/styles/page-template/transactional/index.njk	Updates transactional template heading class to `ofh-heading-lg`.
packages/site/views/design-system/styles/page-template/index.njk	Updates guidance text to reference `ofh-heading-lg`.
packages/site/views/design-system/styles/colour/index.njk	Updates section headings to `ofh-heading-md`.
packages/site/views/design-system/patterns/a-to-z-page/panel/index.njk	Updates card heading utility from numeric to key-based (`heading-md`).
packages/site/views/design-system/patterns/a-to-z-page/navigation/index.njk	Updates A–Z navigation item font utility from numeric to key-based (`heading-sm`).
packages/site/views/design-system/patterns/a-to-z-page/default/index.njk	Updates A–Z pattern default template to key-based font utilities.
packages/site/views/design-system/components/skip-link/default/index.njk	Updates body class to `ofh-body-m`.
packages/site/views/design-system/components/error-summary/placement-multiple/index.njk	Updates page heading class to `ofh-heading-lg`.
packages/site/views/design-system/components/error-summary/placement-input/index.njk	Updates page heading class to `ofh-heading-lg`.
packages/site/views/design-system/components/error-summary/multiple-errors/index.njk	Updates page heading class to `ofh-heading-lg`.
packages/site/views/design-system/components/error-summary/link-input/index.njk	Updates page heading class to `ofh-heading-lg`.
packages/site/views/design-system/components/error-message/error-summary-placement-multiple/index.njk	Updates page heading class to `ofh-heading-lg`.
packages/site/views/design-system/components/error-message/error-summary-placement-input/index.njk	Updates page heading class to `ofh-heading-lg`.
packages/site/views/design-system/components/card/with-image/index.njk	Updates headingClasses to `ofh-heading-md`.
packages/site/views/design-system/components/card/index.njk	Updates docs text to reference `ofh-heading-sm`.
packages/site/views/design-system/components/card/heading-size/index.njk	Updates headingClasses to `ofh-heading-sm`.
packages/site/views/design-system/components/card/group-third/index.njk	Updates card groups to `ofh-heading-md`.
packages/site/views/design-system/components/card/group-quarter/index.njk	Updates quarter group heading HTML to key-based font-size utilities.
packages/site/views/design-system/components/card/group-half/index.njk	Updates card groups to `ofh-heading-md`.
packages/site/views/design-system/components/card/clickable/index.njk	Updates headingClasses to `ofh-heading-md`.
packages/site/views/design-principles.njk	Updates featured list heading classes to `ofh-heading-lg`.
packages/site/views/content/writing-for-readability.njk	Updates featured list heading class to `ofh-heading-lg`.
packages/site/views/content/standard-for-creating-health-content.njk	Updates featured list heading class to `ofh-heading-lg`.
packages/site/views/content/formatting-and-punctuation.njk	Updates “Research insight” heading class to `ofh-heading-md`.
packages/site/views/content/a-to-z-of-nhs-health-writing.njk	Updates date and A–Z navigation font utilities to key-based classes.
packages/site/views/_includes/_feedback-banner.njk	Updates feedback banner heading class to `ofh-heading-md`.
packages/site/styles/design-example/_design-example.scss	Updates design example pop-out typography key.
packages/site/styles/app/_side-nav.scss	Updates side-nav typography keys to Figma-aligned names.
packages/site/styles/app/_related-nav.scss	Updates related-nav typography keys to Figma-aligned names.
packages/site/styles/app/_page-contents.scss	Updates page contents typography keys.
packages/site/styles/app/_meta-data.scss	Updates meta-data typography key.
packages/site/styles/app/_lede-text.scss	Updates heading adjacency selectors to new heading classes.
packages/site/styles/app/_footer.scss	Updates footer typography key.
packages/site/styles/app/_contact-panel.scss	Updates contact panel heading key.
packages/site/styles/app/_colour-swatch.scss	Updates table typography key to `paragraph-sm`.
packages/site/styles/app/_beta-banner.scss	Updates beta banner typography key to `paragraph-sm`.
packages/site/components/header/_header.scss	Updates design-site header typography keys.
packages/site/components/footer/_footer.scss	Updates design-site footer typography keys.
packages/site/components/card/_card.scss	Updates design-site card typography keys and adjacency selectors.
docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md	Adds the standalone, detailed v4.5.0 consumer migration guide.
UPGRADING.md	Replaces detailed steps with a summary and link to the standalone migration guide.
CHANGELOG.md	Updates changelog entries to include typography hard cut + removals.

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

Copilot · 2026-03-20T16:38:29Z

UPGRADING.md

- `all` spacing uses the vertical scale for top and bottom and the horizontal scale for left and right
-
-### Migration Steps
+**Authoritative migration guide:** [Toolkit v4.5.0 spacing, typography, and token migration guide](/Users/diogo.costa/.codex/worktrees/5dbf/design-system-toolkit/docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md)


The migration guide link is an absolute local filesystem path, so it will be broken for anyone reading UPGRADING.md in GitHub. Replace it with a repo-relative link (e.g. docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md) or a full https GitHub URL.

Suggested change

**Authoritative migration guide:** [Toolkit v4.5.0 spacing, typography, and token migration guide](/Users/diogo.costa/.codex/worktrees/5dbf/design-system-toolkit/docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md)

**Authoritative migration guide:** [Toolkit v4.5.0 spacing, typography, and token migration guide](docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md)

Copilot · 2026-03-20T16:38:30Z

packages/site/views/get-started/index.njk

          "heading": "Dev toolkit (Github)",
-          "headingClasses": "ofh-heading-m",
+          "headingClasses": "ofh-heading-md",


Brand capitalization: “Github” should be “GitHub”.

Copilot · 2026-03-20T16:38:30Z

packages/site/views/design-system/styles/page-template/index.njk

  }) }}

-  <p>Vertical padding is reduced on transactional services using the <code>.ofh-main-wrapper--s</code> modifier class. We also recommended you use a smaller page heading size using the <code>.ofh-heading-l</code> modifier class.</p>
+  <p>Vertical padding is reduced on transactional services using the <code>.ofh-main-wrapper--s</code> modifier class. We also recommended you use a smaller page heading size using the <code>.ofh-heading-lg</code> modifier class.</p>


Grammar: “We also recommended you use …” should be “We also recommend you use …”.

Copilot · 2026-03-20T16:38:30Z

packages/site/views/design-system/styles/typography/index.njk

  <p>Only use these font size overrides with <code>p</code> tags.
  {{ designExample({


The <p> opened here is not closed before the designExample(...) block, which produces invalid HTML and can break page layout/styling. Close the paragraph before the Nunjucks block (or restructure so the paragraph fully wraps only text).

diogo-filipe-costa added 5 commits March 20, 2026 15:25

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

diogo-filipe-costa force-pushed the codex/typography-cut branch from 4b69b24 to 28fef64 Compare March 20, 2026 15:39

diogo-filipe-costa changed the title ~~codex/typography cut~~ DSE-379 :: Typography hard cut, alias audit, and migration guide Mar 20, 2026

diogo-filipe-costa added 2 commits March 20, 2026 16:14

diogo-filipe-costa changed the title ~~DSE-379 :: Typography hard cut, alias audit, and migration guide~~ DSE-379 :: Typography hard cut and migration guide Mar 20, 2026

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

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

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

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

Copilot AI reviewed Mar 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

DSE-379 :: Typography hard cut and migration guide#183
diogo-filipe-costa wants to merge 7 commits intocodex/spacing-cutfrom
codex/typography-cut

diogo-filipe-costa commented Mar 20, 2026 •

edited by atlassian bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Copilot AI Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

	Authoritative migration guide: [Toolkit v4.5.0 spacing, typography, and token migration guide](/Users/diogo.costa/.codex/worktrees/5dbf/design-system-toolkit/docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md)
	Authoritative migration guide: [Toolkit v4.5.0 spacing, typography, and token migration guide](docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md)

		<p>Only use these font size overrides with <code>p</code> tags.
		{{ designExample({

Conversation

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

Uh oh!

Description

Scope

Breaking Changes

Key Changes

1) Hard cut of the legacy direct typography API

2) Consumer migration guidance for the full v4.5.0 change set

3) Docs and examples refined as a real QA surface

Validation

Reviewer Focus

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

diogo-filipe-costa commented Mar 20, 2026 •

edited by atlassian bot

Loading