DSE-379 :: Typography hard cut and migration guide

CHANGELOG.md

@@ -22,7 +22,15 @@ We are following [Semantic Versioning](https://semver.org/spec/v2.0.0.html), as
 
 - Replaced legacy point-based spacing usage across toolkit and site source with `$ofh-size-*` tokens and Figma-aligned responsive spacing keys
 - Removed legacy spacing helper compatibility and legacy point-based spacing utility generation
+- Replaced direct typography alias usage across toolkit and site source with Figma-aligned typography keys such as `heading-lg`, `paragraph-md`, and `list-sm`
+- Renamed the direct heading class surface from `.ofh-heading-l/.m/.s` to `.ofh-heading-lg/.md/.sm`
 - Updated spacing documentation and examples to teach the horizontal and vertical responsive spacing scales directly
+- Updated typography documentation and examples to teach the Figma-aligned direct heading classes and mixin keys
+
+##### Removed
+
+- Direct typography alias support for legacy keys such as `h1`, `lead`, `paragraph`, and `list-small`
+- Legacy direct typography utility aliases such as `.ofh-u-font-size-h1`
 
 ### 2026-03-11
 

UPGRADING.md

@@ -22,83 +22,21 @@ This guide provides detailed migration instructions for upgrading between versio
 
 - `@ourfuturehealth/toolkit` v4.5.0+
 
-### Breaking Changes
-
-The toolkit spacing APIs now use the Figma-aligned size keys directly.
-
-- Removed `ofh-spacing(...)`
-- `ofh-responsive-margin(...)` and `ofh-responsive-padding(...)` now expect spacing size keys
-- Spacing utility classes now use spacing size keys as their suffixes
-
-This is still being released as a minor bump because there are no active consumers on the post-`v3.4.2` monorepo line, but consumers adopting the monorepo line should migrate to the new spacing model.
-
-### What Changed
-
-- Static spacing now uses `$ofh-size-*` tokens
-- Responsive spacing now uses the Figma-aligned keys:
-  - `0`, `2`, `4`, `8`, `12`, `16`, `24`, `32`, `40`, `48`, `56`, `64`
-- `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)
 
-#### Replace static spacing function calls
-
-| Before | After |
-| ------ | ----- |
-| `ofh-spacing(0)` | `$ofh-size-0` |
-| `ofh-spacing(1)` | `$ofh-size-2` |
-| `ofh-spacing(2)` | `$ofh-size-4` |
-| `ofh-spacing(3)` | `$ofh-size-8` |
-| `ofh-spacing(4)` | `$ofh-size-16` |
-| `ofh-spacing(5)` | `$ofh-size-24` |
-| `ofh-spacing(6)` | `$ofh-size-32` |
-| `ofh-spacing(7)` | `$ofh-size-40` |
-| `ofh-spacing(8)` | `$ofh-size-48` |
-| `ofh-spacing(9)` | `$ofh-size-56` |
-| `ofh-spacing(10)` | `$ofh-size-64` |
-
-#### Replace responsive spacing mixin arguments
-
-| Before | After |
-| ------ | ----- |
-| `@include ofh-responsive-margin(0, 'bottom')` | `@include ofh-responsive-margin(0, 'bottom')` |
-| `@include ofh-responsive-margin(1, 'bottom')` | `@include ofh-responsive-margin(2, 'bottom')` |
-| `@include ofh-responsive-margin(2, 'bottom')` | `@include ofh-responsive-margin(4, 'bottom')` |
-| `@include ofh-responsive-margin(3, 'bottom')` | `@include ofh-responsive-margin(8, 'bottom')` |
-| `@include ofh-responsive-margin(4, 'bottom')` | `@include ofh-responsive-margin(12, 'bottom')` |
-| `@include ofh-responsive-margin(5, 'bottom')` | `@include ofh-responsive-margin(16, 'bottom')` |
-| `@include ofh-responsive-margin(6, 'bottom')` | `@include ofh-responsive-margin(24, 'bottom')` |
-| `@include ofh-responsive-margin(7, 'bottom')` | `@include ofh-responsive-margin(32, 'bottom')` |
-| `@include ofh-responsive-margin(8, 'bottom')` | `@include ofh-responsive-margin(40, 'bottom')` |
-| `@include ofh-responsive-margin(9, 'bottom')` | `@include ofh-responsive-margin(48, 'bottom')` |
-| `@include ofh-responsive-margin(10, 'bottom')` | `@include ofh-responsive-margin(56, 'bottom')` |
-| `@include ofh-responsive-margin(11, 'bottom')` | `@include ofh-responsive-margin(64, 'bottom')` |
-
-#### Replace spacing utility classes
-
-| Before | After |
-| ------ | ----- |
-| `ofh-u-margin-1` | `ofh-u-margin-2` |
-| `ofh-u-margin-top-4` | `ofh-u-margin-top-12` |
-| `ofh-u-padding-6` | `ofh-u-padding-24` |
-| `ofh-u-padding-bottom-8` | `ofh-u-padding-bottom-40` |
-| `ofh-u-margin-10` | `ofh-u-margin-56` |
-| `ofh-u-padding-11` | `ofh-u-padding-64` |
+### Breaking Changes
 
-### Search Your Codebase
+The toolkit spacing and direct typography APIs now use the Figma-aligned keys directly.
 
-```bash
-grep -r "ofh-spacing(" --include="*.scss" .
-grep -r "ofh-responsive-margin(" --include="*.scss" .
-grep -r "ofh-responsive-padding(" --include="*.scss" .
-grep -r "ofh-u-margin\\|ofh-u-padding-" --include="*.njk" --include="*.html" --include="*.md" .
-```
+Summary:
 
-### Testing After Migration
+- removed `ofh-spacing(...)`
+- replaced the old unified responsive spacing map with separate horizontal and vertical maps
+- renamed direct typography keys in `ofh-typography-responsive(...)` and `ofh-font(...)`
+- renamed direct heading classes from `l/m/s` to `lg/md/sm`
+- renamed several raw tokens and removed `$ofh-width-page-max`
 
-- [ ] Check spacing-heavy templates and components at mobile and desktop breakpoints
-- [ ] Check utility-class examples in the docs site
-- [ ] Check any spacing overrides that mix fixed geometry with layout spacing
+This is still being released as a minor bump because there are no active consumers on the post-`v3.4.2` monorepo line, but any consumer adopting `v4.5.0` should use the standalone migration guide above.
 
 ---