ADS3-Design-System/plans/typography.md

Typography System Plan

What we're building

A complete typography token set for the design system, sourced from the NSW Design System style guide (desktop, >= 960px), expanded with missing styles for a well-balanced type system.

Font Family

Public Sans — the NSW Government typeface. Self-hosted via @fontsource-variable/public-sans (weights 100–900, normal + italic).

Fallback stack: 'Public Sans', system-ui, sans-serif

Typography Scale

From the style guide (12 styles)

Style	Class	Weight	Size	Line Height	Notes
Heading 1	text-h1	700	48px	1.25
Heading 2	text-h2	700	32px	1.25
Heading 3	text-h3	700	24px	1.333
Heading 4	text-h4	700	20px	1.4
Heading 5	text-h5	700	16px	1.5
Intro	text-intro	400	20px	1.4	Lead paragraph
Body Strong	text-body-strong	700	16px	1.5
Body	text-body	400	16px	1.5
Small Strong	text-small-strong	700	14px	1.357
Small	text-small	400	14px	1.357
Body Link	text-body-link	700	16px	1.5	Underlined, Blue 02
Small Link	text-small-link	700	14px	1.357	Underlined, Blue 02

New additions (4 styles)

Style	Class	Weight	Size	Line Height	Rationale
Heading 6	text-h6	700	14px	1.43	Completes heading hierarchy; same size as Small but bold, sits between H5 and body
Label	text-label	500	14px	1.43	Form labels — medium weight distinguishes from body text without being as heavy as bold. The user called this out as missing
Caption	text-caption	400	12px	1.5	Metadata, timestamps, helper text. Introduces 12px to the scale
Overline	text-overline	700	12px	1.5	Category tags, section labels. Uppercase + 0.05em letter-spacing

Total: 16 styles

Size scale summary

48 → 32 → 24 → 20 → 16 → 14 → 12 (px)

Implementation

1. tokens.css — Add to @theme block

• --font-sans for the font family
• --text-{name} + --text-{name}--line-height for each size/line-height pair (Tailwind v4 convention — gives us text-h1, text-body, etc. utilities automatically)
• Font weights don't need custom tokens — Tailwind's built-in font-normal (400), font-medium (500), font-bold (700) cover our needs

2. typography.css — Composed utility classes

Create src/tokens/typography.css with @utility directives for styles that combine multiple properties:

• text-body-strong, text-small-strong (size + weight)
• text-body-link, text-small-link (size + weight + underline + colour)
• text-overline (size + weight + uppercase + letter-spacing)
• text-label (size + weight)

This keeps the @theme block as raw tokens and the utilities as compositions.

3. Load Public Sans

Add Google Fonts import to index.html or src/index.css. Google Fonts is fine for dev; can revisit self-hosting later if needed for production/privacy.

4. Figma — Typography styles

Create typography styles in the Figma design file via MCP so designers can apply them from the styles panel.

Key decisions

• Public Sans via Google Fonts — simplest path; the font is open source (OFL) so self-hosting later is trivial.
• Tailwind v4 --text-* naming — gives us free utility classes. Composed styles go in a separate file to keep tokens.css clean.
• No text-xs/text-sm/text-lg scale aliases — the semantic names (text-body, text-caption) are clearer for a design system. Tailwind defaults still work if needed.
• Medium (500) for Label — distinguishes from Regular body text without being as heavy as Bold headings. Common pattern in Material Design, Atlassian DS, etc.

Questions for Richie

1. Font loading: Google Fonts import in index.html, or self-host from the start?
2. Does this expanded set look right? Any styles you want to add or remove?