font-loading-stinger
Start with README.md for the workflow map and detailed references.
You are font-loading-wasp-drone's arsenal. Your job is to encode the 2026 production-consensus patterns for web font loading performance so the Drone 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
| Presenting symptom or request |
Primary guide |
"What font-display value should I use?" |
guides/01-font-display-decision-matrix.md |
| "Invisible text on first load" (FOIT) |
guides/00-principles.md + guides/01-font-display-decision-matrix.md |
| "Text shifts when font loads" (FOUT + CLS) |
guides/01-font-display-decision-matrix.md + guides/05-cls-elimination.md |
| "Font loads slowly" / "font is blocking render" |
guides/02-preload-strategy.md |
| "Variable font file is too large" |
guides/03-variable-font-subsetting.md |
| "next/font config" / "App Router fonts" |
guides/04-nextjs-font.md |
| "CLS from font swap" / "layout shift after font loads" |
guides/05-cls-elimination.md |
| "Font performance checklist" / "audit font setup" |
guides/06-performance-checklist.md |
| Full audit |
All guides in order; see examples/full-audit.md |
| Next.js Inter setup from scratch |
guides/04-nextjs-font.md + examples/happy-path-nextjs-inter.md |
| Self-hosted variable font from scratch |
guides/03-variable-font-subsetting.md + examples/edge-case-self-hosted-variable.md |
Critical directives (summary)
These are non-negotiable. Full rationale in each guide.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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-wasp-drone is the loading mechanics layer. Stay in-lane:
- Upstream (not ours): Typeface selection, aesthetic decisions, fluid type scale, CSS token architecture (
typography-font-wasp-drone)
- Downstream (not ours): CWV measurement loop, LCP attribution, SEO impact of CLS score (
seo-aeo-wasp-drone)
- Infrastructure (not ours): CI/CD subsetting pipelines, automated
glyphhanger in build jobs (devops-wasp-drone)
When a request crosses into a peer domain, complete the font-loading portion and then name the peer Drone 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 (source-repository research, not shipped with the plugin): depth tier, queries, page budget
- Source research archive (not shipped with the plugin): the shipped distillation summarizes it; do not require it.
1---2name: font-loading-stinger-33description: "Fix web font loading performance. Use for FOIT/FOUT, preload, subsetting, metric-matched fallbacks, or font-swap CLS. Read README.md for the guide map."45license: AGPL-3.0-or-later6metadata:7 source: https://skillmd.com/skills/legioncodeinc/font-loading-stinger-38---910# font-loading-stinger1112Start with [README.md](README.md) for the workflow map and detailed references.1314You are `font-loading-wasp-drone`'s arsenal. Your job is to encode the 2026 production-consensus patterns for web font loading performance so the Drone can audit, implement, and advise with precision rather than approximation.1516Read `SKILL.md` first. Then open the specific guide that matches the task. When the task spans multiple guides, read them in order.1718---1920## Task router2122| Presenting symptom or request | Primary guide |23|---|---|24| "What `font-display` value should I use?" | `guides/01-font-display-decision-matrix.md` |25| "Invisible text on first load" (FOIT) | `guides/00-principles.md` + `guides/01-font-display-decision-matrix.md` |26| "Text shifts when font loads" (FOUT + CLS) | `guides/01-font-display-decision-matrix.md` + `guides/05-cls-elimination.md` |27| "Font loads slowly" / "font is blocking render" | `guides/02-preload-strategy.md` |28| "Variable font file is too large" | `guides/03-variable-font-subsetting.md` |29| "next/font config" / "App Router fonts" | `guides/04-nextjs-font.md` |30| "CLS from font swap" / "layout shift after font loads" | `guides/05-cls-elimination.md` |31| "Font performance checklist" / "audit font setup" | `guides/06-performance-checklist.md` |32| Full audit | All guides in order; see `examples/full-audit.md` |33| Next.js Inter setup from scratch | `guides/04-nextjs-font.md` + `examples/happy-path-nextjs-inter.md` |34| Self-hosted variable font from scratch | `guides/03-variable-font-subsetting.md` + `examples/edge-case-self-hosted-variable.md` |3536---3738## Critical directives (summary)3940These are non-negotiable. Full rationale in each guide.41421. **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.432. **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.443. **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.454. **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.465. **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.476. **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.4849---5051## Scope boundaries5253`font-loading-wasp-drone` is the **loading mechanics layer**. Stay in-lane:5455- **Upstream (not ours):** Typeface selection, aesthetic decisions, fluid type scale, CSS token architecture (`typography-font-wasp-drone`)56- **Downstream (not ours):** CWV measurement loop, LCP attribution, SEO impact of CLS score (`seo-aeo-wasp-drone`)57- **Infrastructure (not ours):** CI/CD subsetting pipelines, automated `glyphhanger` in build jobs (`devops-wasp-drone`)5859When a request crosses into a peer domain, complete the font-loading portion and then name the peer Drone explicitly.6061---6263## References6465Read the guides in this order for a full-scope audit:6667- `guides/00-principles.md`: FOIT/FOUT/FOFT taxonomy, font-display period model, browser defaults68- `guides/01-font-display-decision-matrix.md`: when to use swap/optional/fallback/block/auto69- `guides/02-preload-strategy.md`: preload hints, crossorigin, over-preloading anti-pattern70- `guides/03-variable-font-subsetting.md`: pyftsubset, glyphhanger, subfont, unicode-range71- `guides/04-nextjs-font.md`: next/font App Router vs Pages Router, fonts.ts patterns72- `guides/05-cls-elimination.md`: size-adjust, ascent-override, fontpie, capsizefitter73- `guides/06-performance-checklist.md`: 2026 targets: payload, preloads, CLS, zero double-fetches7475Examples:7677- `examples/happy-path-nextjs-inter.md`: Next.js 15 + Inter variable + zero CLS (most common pattern)78- `examples/edge-case-self-hosted-variable.md`: paid font self-hosted with pyftsubset + metric override7980Templates:8182- `templates/font-face-block.md`: canonical `@font-face` template with all required descriptors83- `templates/preload-link.md`: correct `<link rel="preload">` markup84- `templates/nextfont-config.ts.md`: `app/fonts.ts` starter templates8586Research trail:8788- `research/research-summary.md`: executive summary from scripture-historian89- `research/research-plan.md` (source-repository research, not shipped with the plugin): depth tier, queries, page budget90- Source research archive (not shipped with the plugin): the shipped distillation summarizes it; do not require it.