Font Loading
Master web font loading optimization — font-display strategies for FOIT/FOUT control, Unicode range subsetting, variable fonts for multi-weight reduction, WOFF2 compression, preloading critical fonts, self-hosting versus CDN delivery, and the Font Loading API for programmatic control.
When to Use
- Text is invisible for 1-3 seconds while web fonts download (Flash of Invisible Text)
- Text shifts or reflows when web fonts replace system fonts (Flash of Unstyled Text)
- Lighthouse flags "Ensure text remains visible during webfont load"
- Multiple font weights/styles are loaded but only 2-3 are used on most pages
- Google Fonts or other third-party font CDNs add extra DNS lookups and connections
- Font files are large (>50KB per weight) because they include unused character ranges
- CLS is caused by font swap changing text dimensions after initial render
- A design system uses 6+ font weights that could be consolidated with a variable font
- Font loading blocks LCP because the LCP element contains custom-font text
- Users on slow connections see significant delay before text renders
Instructions
Set font-display for every @font-face rule. This controls browser behavior while the font downloads:
@font-face {
font-family: 'Inter';
src: url('/fonts/inter-var.woff2') format('woff2');
font-weight: 100 900;
font-display: swap; /* show fallback immediately, swap when loaded */
}
font-display value | Behavior
-------------------|--------------------------------------------------
swap | Show fallback immediately, swap to web font when ready
optional | Show fallback; use web font only if it loads very quickly (~100ms)
fallback | Brief invisible period (~100ms), then fallback, then swap
block | Invisible text for up to 3s, then fallback (DEFAULT — avoid this)
auto | Browser decides (usually same as block)
Use swap for body text where readability matters most. Use optional for non-critical decorative fonts where layout stability matters more than exact typography.
Preload critical fonts. The browser does not discover font files until it parses CSS. Preloading eliminates this delay:
<head>
<!-- Preload the primary font used for body text -->
<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />
<!-- crossorigin is REQUIRED even for same-origin fonts -->
</head>
Only preload 1-2 fonts that are used above the fold. Preloading too many fonts competes with other critical resources.
Subset fonts to reduce file size. Remove unused character ranges to dramatically reduce font size:
# Using pyftsubset (from fonttools)
pip install fonttools brotli
# Latin subset only (covers English and most Western European languages)
pyftsubset Inter-Regular.ttf \
--output-file=inter-latin.woff2 \
--flavor=woff2 \
--layout-features='kern,liga,calt' \
--unicodes='U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0300-0301,U+0304,U+0308,U+0329,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD'
/* Declare Unicode ranges for subset loading */
@font-face {
font-family: 'Inter';
src: url('/fonts/inter-latin.woff2') format('woff2');
unicode-range:
U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+20AC;
font-display: swap;
}
@font-face {
font-family: 'Inter';
src: url('/fonts/inter-cyrillic.woff2') format('woff2');
unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
font-display: swap;
}
/* Browser only downloads the subset(s) needed for the page content */
Use variable fonts to eliminate multiple files. A single variable font file replaces 6-12 static weight files:
/* One file covers all weights from 100 to 900 */
@font-face {
font-family: 'Inter';
src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
font-weight: 100 900;
font-style: normal;
font-display: swap;
}
/* Use any weight without additional file downloads */
h1 {
font-weight: 750;
} /* not limited to 700 or 800 */
body {
font-weight: 400;
}
.bold {
font-weight: 650;
}
Comparison for Inter with 4 weights (400, 500, 600, 700):
Static files: 4 x ~25KB = ~100KB
Variable font: 1 x ~50KB = ~50KB (50% smaller)
Minimize layout shift from font swap. Match the fallback font metrics to the web font:
/* Size-adjusted fallback to match Inter metrics */
@font-face {
font-family: 'Inter Fallback';
src: local('Arial');
size-adjust: 107.64%;
ascent-override: 90.49%;
descent-override: 22.56%;
line-gap-override: 0%;
}
body {
font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
}
# Generate metric overrides automatically
npx @capsizecss/metrics Inter
# Or use: https://screenspan.net/fallback
Self-host fonts instead of using Google Fonts CDN. Self-hosting eliminates third-party DNS lookups and connection overhead, enables HTTP cache partition benefits, and gives full control over caching:
# Download Google Fonts for self-hosting
npx google-fonts-helper download -f Inter -s latin -w 400,500,600,700
# Or use: https://gwfh.mranftl.com/fonts (google-webfonts-helper)
Use the Font Loading API for fine-grained control. Programmatically manage font loading when CSS alone is insufficient:
// Load fonts programmatically with timeout
async function loadFonts() {
const font = new FontFace('Inter', 'url(/fonts/inter-var.woff2)', {
weight: '100 900',
display: 'swap',
});
try {
const loaded = await Promise.race([
font.load(),
new Promise((_, reject) => setTimeout(() => reject(new Error('Font timeout')), 3000)),
]);
document.fonts.add(loaded);
document.documentElement.classList.add('fonts-loaded');
} catch {
document.documentElement.classList.add('fonts-failed');
}
}
Details
WOFF2 Compression
WOFF2 uses Brotli compression and achieves 30-50% smaller files than WOFF. All modern browsers support WOFF2. There is no reason to serve WOFF, TTF, or EOT to modern browsers. A typical font file: TTF ~150KB, WOFF ~90KB, WOFF2 ~50KB. Always convert to WOFF2 and provide only WOFF2 in @font-face src unless supporting IE11 (which requires WOFF).
Worked Example: GitHub Font Optimization
GitHub uses a single variable weight Inter font file (WOFF2, ~50KB) self-hosted on their CDN. They preload it with <link rel="preload" as="font" type="font/woff2" crossorigin> and use font-display: swap with a size-adjusted system font fallback. The fallback uses size-adjust and ascent-override to match Inter's metrics within 1%, virtually eliminating visible reflow on font swap. Combined with Latin subsetting, their font loading adds zero render-blocking time and <5 CLS points from the swap.
Worked Example: Stripe Documentation
Stripe's documentation site uses a two-stage font loading strategy. Stage 1 loads the regular weight (used for body text) with preload and font-display: swap. Stage 2 loads bold and italic variants on requestIdleCallback after the page is interactive. The CSS classes fonts-stage-1 and fonts-stage-2 are added to the document element, allowing the design system to progressively enhance typography. This ensures body text renders within 100ms while non-critical weights load in the background without competing for bandwidth.
Anti-Patterns
Preloading too many fonts. Preloading 4+ font files competes with critical CSS, JavaScript, and LCP images for bandwidth. Preload only the 1-2 fonts used in above-the-fold body text.
Using font-display: block on body text. This causes up to 3 seconds of invisible text (FOIT) on slow connections. Use swap for body text so content is immediately readable. Reserve block only for icon fonts where showing the wrong character would be confusing.
Loading all weights when only 2 are used. If the page uses regular (400) and bold (700), loading light (300), medium (500), semi-bold (600), and extra-bold (800) wastes bandwidth. Audit which weights are actually used and load only those.
Not specifying crossorigin on font preload. Font requests are always CORS anonymous requests. Without the crossorigin attribute on <link rel="preload">, the preloaded font and the CSS-requested font are treated as different requests, causing a double download.
Source
Process
- Read the instructions and examples in this document.
- Apply the patterns to your implementation, adapting to your specific context.
- Verify your implementation against the details and edge cases listed above.
Harness Integration
- Type: knowledge — this skill is a reference document, not a procedural workflow.
- No tools or state — consumed as context by other skills and agents.
Success Criteria
- All @font-face rules include an explicit font-display value (swap or optional).
- Critical fonts (1-2 max) are preloaded with correct crossorigin attribute.
- Font files are WOFF2 format and subsetted to used Unicode ranges.
- Variable fonts replace multiple static weight files where applicable.
- Fallback fonts use metric overrides (size-adjust, ascent-override) to minimize CLS.
1---2name: perf-font-loading3description: Font Loading4---5# Font Loading67> Master web font loading optimization — font-display strategies for FOIT/FOUT control, Unicode range subsetting, variable fonts for multi-weight reduction, WOFF2 compression, preloading critical fonts, self-hosting versus CDN delivery, and the Font Loading API for programmatic control.89## When to Use1011- Text is invisible for 1-3 seconds while web fonts download (Flash of Invisible Text)12- Text shifts or reflows when web fonts replace system fonts (Flash of Unstyled Text)13- Lighthouse flags "Ensure text remains visible during webfont load"14- Multiple font weights/styles are loaded but only 2-3 are used on most pages15- Google Fonts or other third-party font CDNs add extra DNS lookups and connections16- Font files are large (>50KB per weight) because they include unused character ranges17- CLS is caused by font swap changing text dimensions after initial render18- A design system uses 6+ font weights that could be consolidated with a variable font19- Font loading blocks LCP because the LCP element contains custom-font text20- Users on slow connections see significant delay before text renders2122## Instructions23241. **Set font-display for every @font-face rule.** This controls browser behavior while the font downloads:2526 ```css27 @font-face {28 font-family: 'Inter';29 src: url('/fonts/inter-var.woff2') format('woff2');30 font-weight: 100 900;31 font-display: swap; /* show fallback immediately, swap when loaded */32 }33 ```3435 ```36 font-display value | Behavior37 -------------------|--------------------------------------------------38 swap | Show fallback immediately, swap to web font when ready39 optional | Show fallback; use web font only if it loads very quickly (~100ms)40 fallback | Brief invisible period (~100ms), then fallback, then swap41 block | Invisible text for up to 3s, then fallback (DEFAULT — avoid this)42 auto | Browser decides (usually same as block)43 ```4445 Use `swap` for body text where readability matters most. Use `optional` for non-critical decorative fonts where layout stability matters more than exact typography.46472. **Preload critical fonts.** The browser does not discover font files until it parses CSS. Preloading eliminates this delay:4849 ```html50 <head>51 <!-- Preload the primary font used for body text -->52 <link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />53 <!-- crossorigin is REQUIRED even for same-origin fonts -->54 </head>55 ```5657 Only preload 1-2 fonts that are used above the fold. Preloading too many fonts competes with other critical resources.58593. **Subset fonts to reduce file size.** Remove unused character ranges to dramatically reduce font size:6061 ```bash62 # Using pyftsubset (from fonttools)63 pip install fonttools brotli6465 # Latin subset only (covers English and most Western European languages)66 pyftsubset Inter-Regular.ttf \67 --output-file=inter-latin.woff2 \68 --flavor=woff2 \69 --layout-features='kern,liga,calt' \70 --unicodes='U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0300-0301,U+0304,U+0308,U+0329,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD'71 ```7273 ```css74 /* Declare Unicode ranges for subset loading */75 @font-face {76 font-family: 'Inter';77 src: url('/fonts/inter-latin.woff2') format('woff2');78 unicode-range:79 U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+20AC;80 font-display: swap;81 }8283 @font-face {84 font-family: 'Inter';85 src: url('/fonts/inter-cyrillic.woff2') format('woff2');86 unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;87 font-display: swap;88 }89 /* Browser only downloads the subset(s) needed for the page content */90 ```91924. **Use variable fonts to eliminate multiple files.** A single variable font file replaces 6-12 static weight files:9394 ```css95 /* One file covers all weights from 100 to 900 */96 @font-face {97 font-family: 'Inter';98 src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');99 font-weight: 100 900;100 font-style: normal;101 font-display: swap;102 }103104 /* Use any weight without additional file downloads */105 h1 {106 font-weight: 750;107 } /* not limited to 700 or 800 */108 body {109 font-weight: 400;110 }111 .bold {112 font-weight: 650;113 }114 ```115116 ```117 Comparison for Inter with 4 weights (400, 500, 600, 700):118 Static files: 4 x ~25KB = ~100KB119 Variable font: 1 x ~50KB = ~50KB (50% smaller)120 ```1211225. **Minimize layout shift from font swap.** Match the fallback font metrics to the web font:123124 ```css125 /* Size-adjusted fallback to match Inter metrics */126 @font-face {127 font-family: 'Inter Fallback';128 src: local('Arial');129 size-adjust: 107.64%;130 ascent-override: 90.49%;131 descent-override: 22.56%;132 line-gap-override: 0%;133 }134135 body {136 font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;137 }138 ```139140 ```bash141 # Generate metric overrides automatically142 npx @capsizecss/metrics Inter143 # Or use: https://screenspan.net/fallback144 ```1451466. **Self-host fonts instead of using Google Fonts CDN.** Self-hosting eliminates third-party DNS lookups and connection overhead, enables HTTP cache partition benefits, and gives full control over caching:147148 ```bash149 # Download Google Fonts for self-hosting150 npx google-fonts-helper download -f Inter -s latin -w 400,500,600,700151152 # Or use: https://gwfh.mranftl.com/fonts (google-webfonts-helper)153 ```1541557. **Use the Font Loading API for fine-grained control.** Programmatically manage font loading when CSS alone is insufficient:156157 ```javascript158 // Load fonts programmatically with timeout159 async function loadFonts() {160 const font = new FontFace('Inter', 'url(/fonts/inter-var.woff2)', {161 weight: '100 900',162 display: 'swap',163 });164165 try {166 const loaded = await Promise.race([167 font.load(),168 new Promise((_, reject) => setTimeout(() => reject(new Error('Font timeout')), 3000)),169 ]);170 document.fonts.add(loaded);171 document.documentElement.classList.add('fonts-loaded');172 } catch {173 document.documentElement.classList.add('fonts-failed');174 }175 }176 ```177178## Details179180### WOFF2 Compression181182WOFF2 uses Brotli compression and achieves 30-50% smaller files than WOFF. All modern browsers support WOFF2. There is no reason to serve WOFF, TTF, or EOT to modern browsers. A typical font file: TTF ~150KB, WOFF ~90KB, WOFF2 ~50KB. Always convert to WOFF2 and provide only WOFF2 in @font-face src unless supporting IE11 (which requires WOFF).183184### Worked Example: GitHub Font Optimization185186GitHub uses a single variable weight Inter font file (WOFF2, ~50KB) self-hosted on their CDN. They preload it with `<link rel="preload" as="font" type="font/woff2" crossorigin>` and use `font-display: swap` with a size-adjusted system font fallback. The fallback uses `size-adjust` and `ascent-override` to match Inter's metrics within 1%, virtually eliminating visible reflow on font swap. Combined with Latin subsetting, their font loading adds zero render-blocking time and <5 CLS points from the swap.187188### Worked Example: Stripe Documentation189190Stripe's documentation site uses a two-stage font loading strategy. Stage 1 loads the regular weight (used for body text) with preload and `font-display: swap`. Stage 2 loads bold and italic variants on `requestIdleCallback` after the page is interactive. The CSS classes `fonts-stage-1` and `fonts-stage-2` are added to the document element, allowing the design system to progressively enhance typography. This ensures body text renders within 100ms while non-critical weights load in the background without competing for bandwidth.191192### Anti-Patterns193194**Preloading too many fonts.** Preloading 4+ font files competes with critical CSS, JavaScript, and LCP images for bandwidth. Preload only the 1-2 fonts used in above-the-fold body text.195196**Using font-display: block on body text.** This causes up to 3 seconds of invisible text (FOIT) on slow connections. Use `swap` for body text so content is immediately readable. Reserve `block` only for icon fonts where showing the wrong character would be confusing.197198**Loading all weights when only 2 are used.** If the page uses regular (400) and bold (700), loading light (300), medium (500), semi-bold (600), and extra-bold (800) wastes bandwidth. Audit which weights are actually used and load only those.199200**Not specifying crossorigin on font preload.** Font requests are always CORS anonymous requests. Without the `crossorigin` attribute on `<link rel="preload">`, the preloaded font and the CSS-requested font are treated as different requests, causing a double download.201202## Source203204- web.dev: Best practices for fonts — https://web.dev/articles/font-best-practices205- MDN: font-display — https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display206- Variable Fonts guide — https://web.dev/articles/variable-fonts207- Font Loading API — https://developer.mozilla.org/en-US/docs/Web/API/CSS_Font_Loading_API208209## Process2102111. Read the instructions and examples in this document.2122. Apply the patterns to your implementation, adapting to your specific context.2133. Verify your implementation against the details and edge cases listed above.214215## Harness Integration216217- **Type:** knowledge — this skill is a reference document, not a procedural workflow.218- **No tools or state** — consumed as context by other skills and agents.219220## Success Criteria221222- All @font-face rules include an explicit font-display value (swap or optional).223- Critical fonts (1-2 max) are preloaded with correct crossorigin attribute.224- Font files are WOFF2 format and subsetted to used Unicode ranges.225- Variable fonts replace multiple static weight files where applicable.226- Fallback fonts use metric overrides (size-adjust, ascent-override) to minimize CLS.
Intense-Visions