# 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?