DSE-378 / DSE-379 :: spacing and typography hard cut with token alignment (#182)

* refactor(tokens): align toolkit token sources with figma

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.

* chore(site): update docs site token references

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.

* refactor(spacing): hard-cut figma-aligned spacing api

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.

* docs(site): clarify spacing migration examples

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.

* fix(spacing): clarify responsive scale error

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

* docs(site): clarify responsive spacing behavior

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.

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

* feat(audit): add typography alias usage report

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.

* refactor(typography): hard-cut direct figma aliases

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.

* chore(audit): refresh typography alias definitions

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.

* docs(migration): add v4.5.0 consumer guide

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.

* docs(site): refine spacing and typography examples

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.

* refactor(typography): remove heading-xxs alias

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.

* chore(typography): drop alias audit tooling

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.

* fix(typography): address review docs issues

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.

* refactor(typography): restore numeric override utilities

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.

* docs(migration): align v4.5.0 typography guidance

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.

* docs(site): clarify responsive typography overrides

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.

* refactor(typography): replace font-size-19 utility with 20

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.

Author: diogo-filipe-costa

CHANGELOG.md

@@ -6,6 +6,32 @@ We are following [Semantic Versioning](https://semver.org/spec/v2.0.0.html), as
 
 ## Monorepo Package Releases (`toolkit-v*`, `react-v*`)
 
+### 2026-03-19
+
+#### @ourfuturehealth/toolkit 4.5.0 (`toolkit-v4.5.0`)
+
+##### ⚠️ BREAKING CHANGES
+
+- **Spacing API hard cut to Figma-aligned size keys**
+  - Removed `ofh-spacing(...)`
+  - `ofh-responsive-margin(...)` and `ofh-responsive-padding(...)` now take spacing size keys directly
+  - Spacing utility classes now use spacing size keys as their suffixes
+  - See [UPGRADING.md](UPGRADING.md#upgrading-to-v450) for migration details
+
+##### Changed
+
+- 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, while keeping numeric responsive font-size override utilities for consumers and replacing `ofh-u-font-size-19` with `ofh-u-font-size-20`
+
+##### 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`; use numeric override classes such as `.ofh-u-font-size-64` instead
+
 ### 2026-03-11
 
 #### @ourfuturehealth/toolkit 4.4.0 (`toolkit-v4.4.0`)

UPGRADING.md

@@ -8,12 +8,40 @@ This guide provides detailed migration instructions for upgrading between versio
 
 | Version                                                 | Date          | Breaking Changes      | Migration Complexity                  |
 | ------------------------------------------------------- | ------------- | --------------------- | ------------------------------------- |
+| [v4.5.0](#upgrading-to-v450)                            | March 2026    | Spacing and typography API changes | 🟡 Medium - Replace legacy APIs and recheck overrides |
 | [v4.3.0 / React v0.2.0](#upgrading-to-v430--react-v020) | March 2026    | Button variant naming | 🟡 Medium - Find/replace required     |
 | [v4.1.0](#upgrading-to-v410)                            | February 2026 | Spacing scale indices | 🟡 Medium - Index updates required    |
 | [v4.0.0](#upgrading-to-v400-monorepo-restructure)       | 2025          | Monorepo restructure  | 🔴 High - Installation & paths change |
 
 ---
 
+## Upgrading to v4.5.0
+
+**Released:** March 2026  
+**Affected packages:**
+
+- `@ourfuturehealth/toolkit` v4.5.0+
+
+**Authoritative migration guide:** [Toolkit v4.5.0 spacing, typography, and token migration guide](docs/migrations/toolkit-v4.5.0-spacing-typography-tokens.md)
+
+### Breaking Changes
+
+The toolkit spacing and direct typography APIs now use the Figma-aligned keys directly.
+
+Summary:
+
+- 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`
+- removed legacy direct typography utility aliases such as `ofh-u-font-size-h1`
+- kept the numeric responsive font-size override utilities as the supported override utility surface, with `ofh-u-font-size-20` replacing `ofh-u-font-size-19`
+- renamed several raw tokens and removed `$ofh-width-page-max`
+
+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.
+
+---
+
 ## Upgrading to v4.3.0 / React v0.2.0
 
 **Released:** March 2026