Typography Font Weapon
Typography is the invisible infrastructure of every UI. Font loading choices directly impact Core Web Vitals (LCP, CLS), accessibility (WCAG 1.4.4 text resize), and brand consistency. Getting it right in 2026 means navigating variable font subsetting, the font-display decision matrix, fluid clamp() type scales, and the growing split between next/font, Fontsource, and full self-hosting pipelines.
This Weapon encodes the 2026 state-of-the-art for the full technical typographic stack: font loading strategy, variable font configuration, fluid type scale arithmetic, vertical rhythm, and the font-token layer. Read SKILL.md for task routing; follow the specific guide for implementation depth.
Task routing
| Task |
Guide |
| Understand FOIT, FOUT, FOFT, and font-display semantics |
guides/00-principles.md |
| Choose font hosting strategy (next/font vs Fontsource vs self-host) |
guides/01-hosting-strategy.md |
| Configure variable fonts and subsetting |
guides/02-variable-fonts.md |
| Build a fluid type scale with clamp() |
guides/03-fluid-type-scale.md |
| Establish vertical rhythm and line-height |
guides/04-vertical-rhythm.md |
| Author a font token CSS layer |
guides/05-font-token-layer.md |
| Audit and improve font loading performance |
guides/06-performance-checklist.md |
| Happy-path: Next.js + next/font + Tailwind |
examples/happy-path-nextjs-font.md |
| Edge-case: self-hosted variable font with manual subsetting |
examples/edge-case-self-hosted-variable.md |
| CSS typography token skeleton |
templates/typography.css.template.md |
| next/font config template |
templates/next-font-config.ts.template.md |
The seven non-negotiables
From the Command Brief, repeated here as guardrails for every implementation:
- Always specify
font-display on every @font-face rule. Browser defaults vary; omitting it causes unpredictable FOIT/FOUT/FOFT across Chrome, Safari, and Firefox. See guides/00-principles.md.
- Never reference raw px font sizes in component code. All sizes must route through the fluid type-scale token layer. See
guides/05-font-token-layer.md.
- Distinguish FOIT, FOUT, and FOFT. Each has a different
font-display remedy; conflating them leads to wrong values. See guides/00-principles.md.
- Always subset variable fonts. Unsubsetted variable fonts are 300-800 kB; a Latin subset is typically 20-60 kB. See
guides/02-variable-fonts.md.
- Validate next/font usage against the App Router API, not Pages Router. The two APIs differ in import path, options object, and class/variable application. See
guides/01-hosting-strategy.md.
- Express fluid type steps as
clamp() expressions, not media-query breakpoint steps. clamp() provides smooth interpolation that breakpoints cannot replicate. See guides/03-fluid-type-scale.md.
- Keep the font-token file as the single source of truth. Font decisions scattered across globals, components, and Tailwind config produce a system that cannot be audited holistically. See
guides/05-font-token-layer.md.
Scope boundary
| In scope |
Out of scope - route to |
| Font loading strategy (next/font, Fontsource, self-host) |
Typeface aesthetic selection - design-system-guardian |
Variable font axes, subsetting, @font-face config |
Build pipeline subsetting CI steps - devops-guardian |
font-display semantics and FOIT/FOUT/FOFT remediation |
Per-component type token application - ux-ui-guardian |
Fluid clamp() type scale arithmetic |
LCP font impact analysis in broader CWV audit - seo-aeo-guardian |
Vertical rhythm and line-height tokens |
Persisted user font preference schema - db-guardian |
Font-token CSS layer (--font-* custom properties) |
Brand identity and palette decisions - design-system-guardian |
Quick-start checklist
For a standard Next.js 15 App Router + next/font + Tailwind v4 stack:
Research trail: research/research-summary.md | Command Brief: ai-tools/command-briefs/typography-font-guardian-command-brief.md
1---2name: typography-font-weapon3description: Typography and font-loading specialist for web products — variable fonts, Google Fonts vs Fontsource vs self-host, the FOIT/FOUT/FOFT loading story, font-display semantics, fluid type scales via clamp(), vertical rhythm, and the type-token architecture. Use when the user says "set up fonts", "audit our typography", "fix FOIT/FOUT", "build a type scale", "migrate to next/font", "self-host fonts", "fluid type", "variable fonts", "font performance", or when typography-font-guardian is invoked. Do NOT use for typeface selection or brand identity decisions (design-system-guardian), per-component application of type tokens (ux-ui-guardian), build pipeline font optimization (devops-guardian), or persisted user font preferences (db-guardian).4license: MIT5---67# Typography Font Weapon89Typography is the invisible infrastructure of every UI. Font loading choices directly impact Core Web Vitals (LCP, CLS), accessibility (WCAG 1.4.4 text resize), and brand consistency. Getting it right in 2026 means navigating variable font subsetting, the `font-display` decision matrix, fluid `clamp()` type scales, and the growing split between `next/font`, Fontsource, and full self-hosting pipelines.1011This Weapon encodes the 2026 state-of-the-art for the full technical typographic stack: font loading strategy, variable font configuration, fluid type scale arithmetic, vertical rhythm, and the font-token layer. Read `SKILL.md` for task routing; follow the specific guide for implementation depth.1213---1415## Task routing1617| Task | Guide |18|------|-------|19| Understand FOIT, FOUT, FOFT, and font-display semantics | `guides/00-principles.md` |20| Choose font hosting strategy (next/font vs Fontsource vs self-host) | `guides/01-hosting-strategy.md` |21| Configure variable fonts and subsetting | `guides/02-variable-fonts.md` |22| Build a fluid type scale with clamp() | `guides/03-fluid-type-scale.md` |23| Establish vertical rhythm and line-height | `guides/04-vertical-rhythm.md` |24| Author a font token CSS layer | `guides/05-font-token-layer.md` |25| Audit and improve font loading performance | `guides/06-performance-checklist.md` |26| Happy-path: Next.js + next/font + Tailwind | `examples/happy-path-nextjs-font.md` |27| Edge-case: self-hosted variable font with manual subsetting | `examples/edge-case-self-hosted-variable.md` |28| CSS typography token skeleton | `templates/typography.css.template.md` |29| next/font config template | `templates/next-font-config.ts.template.md` |3031---3233## The seven non-negotiables3435From the Command Brief, repeated here as guardrails for every implementation:36371. **Always specify `font-display` on every `@font-face` rule.** Browser defaults vary; omitting it causes unpredictable FOIT/FOUT/FOFT across Chrome, Safari, and Firefox. See `guides/00-principles.md`.382. **Never reference raw px font sizes in component code.** All sizes must route through the fluid type-scale token layer. See `guides/05-font-token-layer.md`.393. **Distinguish FOIT, FOUT, and FOFT.** Each has a different `font-display` remedy; conflating them leads to wrong values. See `guides/00-principles.md`.404. **Always subset variable fonts.** Unsubsetted variable fonts are 300-800 kB; a Latin subset is typically 20-60 kB. See `guides/02-variable-fonts.md`.415. **Validate next/font usage against the App Router API, not Pages Router.** The two APIs differ in import path, options object, and class/variable application. See `guides/01-hosting-strategy.md`.426. **Express fluid type steps as `clamp()` expressions, not media-query breakpoint steps.** `clamp()` provides smooth interpolation that breakpoints cannot replicate. See `guides/03-fluid-type-scale.md`.437. **Keep the font-token file as the single source of truth.** Font decisions scattered across globals, components, and Tailwind config produce a system that cannot be audited holistically. See `guides/05-font-token-layer.md`.4445---4647## Scope boundary4849| In scope | Out of scope - route to |50|----------|------------------------|51| Font loading strategy (next/font, Fontsource, self-host) | Typeface aesthetic selection - `design-system-guardian` |52| Variable font axes, subsetting, `@font-face` config | Build pipeline subsetting CI steps - `devops-guardian` |53| `font-display` semantics and FOIT/FOUT/FOFT remediation | Per-component type token application - `ux-ui-guardian` |54| Fluid `clamp()` type scale arithmetic | LCP font impact analysis in broader CWV audit - `seo-aeo-guardian` |55| Vertical rhythm and `line-height` tokens | Persisted user font preference schema - `db-guardian` |56| Font-token CSS layer (`--font-*` custom properties) | Brand identity and palette decisions - `design-system-guardian` |5758---5960## Quick-start checklist6162For a standard Next.js 15 App Router + `next/font` + Tailwind v4 stack:6364- [ ] Font loading: `next/font/google` or `next/font/local` configured in `app/fonts.ts`65- [ ] Font variables applied to `:root` via `className` or `variable` prop on `<html>`66- [ ] No render-blocking `<link rel="stylesheet">` for Google Fonts in `<head>`67- [ ] `font-display` declared (or confirmed via `next/font`'s automatic `optional`)68- [ ] Variable font configured with `wght` axis range, not discrete weights69- [ ] Fluid type scale: all sizes expressed as `clamp()` CSS custom properties in `tokens/typography.css`70- [ ] Vertical rhythm: `line-height` multiples stored as tokens71- [ ] No raw px font sizes in any `.tsx` or `.css` component file72- [ ] Font subset: Latin-only for non-multilingual projects (`subset: ['latin']` in next/font)7374---7576*Research trail: `research/research-summary.md` | Command Brief: `ai-tools/command-briefs/typography-font-guardian-command-brief.md`*
The-Notorious-Avengers