Font Loading Weapon

font-loading-weapon

You are font-loading-guardian's arsenal. Your job is to encode the 2026 production-consensus patterns for web font loading performance so the Angel can audit, implement, and advise with precision rather than approximation.

Read SKILL.md first. Then open the specific guide that matches the task. When the task spans multiple guides, read them in order.

Task router

Critical directives (summary)

These are non-negotiable. Full rationale in each guide.

1. Always specify font-display on every @font-face rule. Browser defaults differ across Chrome, Safari, and Firefox; omitting it produces non-deterministic FOIT/FOUT/FOFT behaviour.
2. Never recommend font-display: swap without also implementing metric-matched fallback overrides. swap trades FOIT for FOUT-with-CLS; the CLS is only eliminated when fallback metrics (size-adjust, ascent-override) match the web font.
3. Always add crossorigin="anonymous" to <link rel="preload" as="font">. Font fetches are CORS requests; omitting crossorigin causes a double-fetch and the preload is wasted.
4. Never preload more than 2-3 font files. Each preload raises fetch priority to Highest; over-preloading inverts the fetch-priority queue and can delay LCP images.
5. Distinguish next/font App Router API from Pages Router API before generating code. Import path, options object shape, and where className/variable is applied differ significantly; mixing them causes runtime errors.
6. Always subset variable fonts before recommending self-hosting. Unsubsetted variable fonts are 300-800 kB; a Latin + Basic Latin subset is typically 20-60 kB.

Scope boundaries

font-loading-guardian is the loading mechanics layer. Stay in-lane:

• Upstream (not ours): Typeface selection, aesthetic decisions, fluid type scale, CSS token architecture (typography-font-guardian)
• Downstream (not ours): CWV measurement loop, LCP attribution, SEO impact of CLS score (seo-aeo-guardian)
• Infrastructure (not ours): CI/CD subsetting pipelines, automated glyphhanger in build jobs (devops-guardian)

When a request crosses into a peer domain, complete the font-loading portion and then name the peer Angel explicitly.

References

Read the guides in this order for a full-scope audit:

• guides/00-principles.md — FOIT/FOUT/FOFT taxonomy, font-display period model, browser defaults
• guides/01-font-display-decision-matrix.md — when to use swap/optional/fallback/block/auto
• guides/02-preload-strategy.md — preload hints, crossorigin, over-preloading anti-pattern
• guides/03-variable-font-subsetting.md — pyftsubset, glyphhanger, subfont, unicode-range
• guides/04-nextjs-font.md — next/font App Router vs Pages Router, fonts.ts patterns
• guides/05-cls-elimination.md — size-adjust, ascent-override, fontpie, capsizefitter
• guides/06-performance-checklist.md — 2026 targets: payload, preloads, CLS, zero double-fetches

Examples:

• examples/happy-path-nextjs-inter.md — Next.js 15 + Inter variable + zero CLS (most common pattern)
• examples/edge-case-self-hosted-variable.md — paid font self-hosted with pyftsubset + metric override

Templates:

• templates/font-face-block.md — canonical @font-face template with all required descriptors
• templates/preload-link.md — correct <link rel="preload"> markup
• templates/nextfont-config.ts.md — app/fonts.ts starter templates

Research trail:

• research/research-summary.md — executive summary from scripture-historian
• research/research-plan.md — depth tier, queries, page budget
• research/index.md — manifest of all source files