|$ curl https://forge-ai.dev/api/markdown?path=docs/performance/fonts
$cat docs/fonts.md
updated Recently·18 min read·published
Fonts
Introduction
Custom fonts improve design but can hurt Core Web Vitals if loaded inefficiently. The goal is to display text as soon as possible while minimizing layout shift.
font-display
The font-display CSS descriptor controls how a font face is rendered while it is loading.
| Value | Behavior |
|---|---|
| auto | Browser default (usually block) |
| block | Invisible text for up to 3s, then fallback |
| swap | Fallback immediately, swap when font loads |
| fallback | Brief invisible period, then swap |
| optional | Use font only if cached/loaded quickly |
font-face.css
CSS
| 1 | @font-face { |
| 2 | font-family: "Inter"; |
| 3 | src: url("/fonts/Inter.woff2") format("woff2"); |
| 4 | font-display: swap; |
| 5 | } |
✓
best practice
Use font-display: swap for body text so content remains visible. Use optional for non-critical decorative fonts.
Preloading
Preload critical fonts so the browser discovers them early. Only preload fonts used above the fold.
preload.html
HTML
| 1 | <link rel="preload" href="/fonts/Inter.woff2" as="font" type="font/woff2" crossorigin="anonymous" /> |
Subsetting & Compression
Subset fonts to include only the characters you need. Serve WOFF2, which offers the best compression. Use variable fonts to combine multiple weights and styles into a single file.
Fallback Strategy
fallback.css
CSS
| 1 | body { |
| 2 | font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; |
| 3 | } |
ℹ
info
Match the fallback font's metrics to the custom font using size-adjust, ascent-override, and descent-override to reduce layout shift.