Skip to content

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

Open
diogo-filipe-costa wants to merge 12 commits intocodex/spacing-cutfrom
codex/typography-cut
Open

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

Conversation

@diogo-filipe-costa
Copy link
Contributor

@diogo-filipe-costa diogo-filipe-costa commented Mar 20, 2026 •
edited by atlassian bot
Loading

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, and updates the docs and migration guidance to match the new typography model. It also intentionally keeps numeric responsive font-size override classes as the consumer override API, because they are easier to reason about in real usage than named style-key utilities.

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
  • Removed legacy direct typography utility aliases such as ofh-u-font-size-h1
  • Kept the numeric responsive font-size override classes as the supported override surface:
    • 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-20
    • ofh-u-font-size-16
    • ofh-u-font-size-14
  • 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
  • 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) Numeric responsive override utilities retained for consumers

  • Kept numeric responsive font-size override classes instead of teaching named style-key utilities
  • Documented the retained numeric override surface on the typography docs page with explicit breakpoint values
  • Updated toolkit examples and site examples to use numeric override classes where overrides are intended
  • Followed the later design decision to remove ofh-u-font-size-19 from the supported override set and replace it with ofh-u-font-size-20
  • ofh-u-font-size-20 now uses the current medium paragraph/list values:
    • mobile: 18px / 24px
    • tablet and desktop: 20px / 28px

3) 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
  • Documented that numeric typography utility classes remain supported as the override API
  • Added explicit guidance for consumers who already adopted ofh-u-font-size-19 to rename it to ofh-u-font-size-20 and visually QA the changed responsive values
  • Reduced the top-level upgrading guide to a concise summary that points consumers to the standalone guide as the authoritative reference

4) 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
  • Clarified the typography override docs so they present breakpoint names and actual supported utility values consistently

Validation

  • pnpm lint
  • npm test
  • pnpm --filter=site build
  • 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
    • the ofh-u-font-size-19 -> ofh-u-font-size-20 override change

Reviewer Focus

  • Completeness of the direct typography alias removal
  • Correctness of the retained numeric responsive override utility surface
  • Correctness of the font-size-20 replacement and downstream example updates
  • Accuracy and usefulness of the standalone consumer migration guide
  • Site/docs examples remaining reliable after the typography hard cut

@diogo-filipe-costa
feat(audit): add typography alias usage report
3c59aaf 
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.
@diogo-filipe-costa
refactor(typography): hard-cut direct figma aliases
fd844ea 
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.
@diogo-filipe-costa
chore(audit): refresh typography alias definitions
97fa3ff 
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.
@diogo-filipe-costa
docs(migration): add v4.5.0 consumer guide
128d803 
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.
@diogo-filipe-costa
docs(site): refine spacing and typography examples
28fef64 
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.
@diogo-filipe-costa 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
refactor(typography): remove heading-xxs alias
34a03a1 
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.
@diogo-filipe-costa
chore(typography): drop alias audit tooling
71fb1bf 
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.
@diogo-filipe-costa 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 diogo-filipe-costa self-assigned this Mar 20, 2026
Copilot AI reviewed Mar 20, 2026
View reviewed changes
Copy link

Copilot AI left a comment

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

@diogo-filipe-costa
fix(typography): address review docs issues
a5088bf 
Replace the broken local migration-guide link, fix the GitHub brand capitalization and page-template grammar, and close the invalid paragraph wrapper in the typography docs example.
@diogo-filipe-costa
refactor(typography): restore numeric override utilities
e903f34 
Restore the responsive numeric font-size utility classes used by consumers before the monorepo migration.

Keep the direct typography API Figma-aligned while generating numeric override classes with the legacy responsive font-size and line-height values.

Update toolkit examples, site docs, and the migration guide so the override utility surface is documented consistently with the restored numeric scale.
@diogo-filipe-costa
docs(migration): align v4.5.0 typography guidance
6891158 
Update the v4.5.0 upgrading docs to match the final typography API shipped on this branch.

Remove stale guidance that implied named font-size override utilities remained supported and document the retained numeric responsive override utilities instead.
@diogo-filipe-costa
docs(site): clarify responsive typography overrides
deb4b88 
Fix stale typography page markup and tighten the override guidance so it matches the retained numeric responsive utility classes.

Present the font override scale from the tablet-and-up reference size first, then show the collapsed mobile values to match how maintainers choose these utilities.

Call out the exact font weight override classes so the docs describe the real supported API.
@diogo-filipe-costa
refactor(typography): replace font-size-19 utility with 20
15cd1da 
Remove the out-of-place numeric font-size-19 override utility and replace it with font-size-20 using the current paragraph/list responsive values.

Update toolkit and site examples, card documentation, and typography docs so the supported override surface is consistent everywhere.

Extend the migration guidance so consumers who already used font-size-19 have a direct rename path to font-size-20 and know they must visually QA the changed responsive values.
@diogo-filipe-costa diogo-filipe-costa marked this pull request as ready for review March 24, 2026 11:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@rmds16 rmds16 Awaiting requested review from rmds16

@willmcb willmcb Awaiting requested review from willmcb

@cfgreene cfgreene Awaiting requested review from cfgreene

@jpsanders101 jpsanders101 Awaiting requested review from jpsanders101

@wotton-software wotton-software Awaiting requested review from wotton-software

Assignees

@diogo-filipe-costa diogo-filipe-costa

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@diogo-filipe-costa