Theme wizard: font-family picking (Typography step 03)

[jerrythomas]

Context

The interactive theme wizard (shipped 2026-05-27) ships step 03 Typography as a sample placeholder — full font-family picking was explicitly deferred as its own design pass (font loading + system fallbacks). Steps 01 Style / 02 Skin / 04 Preview are fully interactive. See docs/design/12-priority.md (Demo App → Interactive theme wizard).

Scope

• Step 03 lets the user pick font families for the UI / display / mono roles.
• Handle web-font loading (with system fallbacks) so step 04's preview reflects the choice live.
• Persist the choice into the saved preset + exported tokens.css, consistent with how skin/style choices are saved.

Acceptance criteria

• Selecting a font in step 03 updates the live preview and the exported tokens.
• Graceful system fallback; no FOUT/layout-shift regression in the wizard.
• Tests cover the font selection → preview + export path.

[jerrythomas]

Font selection is done and tested (f69308fa) — 12 unit + 5 e2e over selection → live preview → export, and the "graceful system fallback" criterion is now enforced (every catalog stack must end on a generic CSS family, checked per entry).

Decision recorded: no custom font loader. Font loading is already solved at build time via self-hosted @fontsource (Fraunces, Inter, JetBrains Mono, Caveat), so selecting a font makes no network request. A runtime CDN loader would introduce exactly the FOUT/layout-shift the acceptance criteria forbid.

Remaining scope per that decision is heading levels + font styles. Planned at docs/plans/2026-08-21-typography-scale.md (b9e388f5).

One finding worth flagging, because it changes the size of the remainder: there is no type scale anywhere in the codebase. Verified in packages/themes/src/base/typography.css (font families + radius only) and packages/unocss/src/preset.ts — buildTypographyVars emits exactly three family vars plus two legacy aliases. No --text-*, no per-level size/weight/line-height, and rokkit.config.js's typography: {} carries only display/sans/mono.

So this is designing a new token set, not exposing existing tokens in the wizard. Five questions need settling first (scale shape, level count, what varies per level, whether variable-font axes are in scope, density interaction) — each changes the token surface. My recommendation is in the plan: ratio + per-level override, h1–h4 + body + small, varying size/line-height/weight, density-independent (matching the control-height precedent, which is deliberately density-independent).

Phased so tokens land with a real consumer before the wizard exposes them — tokens nothing reads would be dead export output.