## TL;DR

Percy snapshots the DOM at a moment it chooses, which is often before fonts arrive. Force the timing: wait for document.fonts.ready in the page before Percy snapshots, or use Percy's snapshot stabilization options, and self-host the fonts. Snapshots then capture the real type.

## Error

```text
percy snapshot taken before fonts loaded: how to fix
```

Percy snapshots show fallback fonts while the live page renders the correct webfonts.

## Steps

1. Confirm the symptom: Percy diffs show fallback fonts while the live page looks right. Expected output: you know it is timing, not a broken font setup.
2. Add a font-ready wait in the page under test: await document.fonts.ready before the snapshot point. Expected output: fonts are loaded when Percy captures.
3. Self-host the webfonts so they load from the same origin without extra DNS and TLS round trips. Expected output: faster, more deterministic font loading.
4. If the framework supports it, use Percy's per-snapshot wait or discovery options to delay capture until network idle. Expected output: snapshots wait for the fonts as well as the page.
5. Re-run Percy and compare. Expected output: font rendering matches the baseline.

## When to use

- Percy snapshots show fallback fonts.
- Font diffs are flaky across runs.
- Setting up Percy with custom webfonts.

## When not to use

- Diffs show layout changes (real diffs, review them).
- Fonts never load even live (fix the font serving first).
- You use system fonts only (there is nothing to wait for).

## Variant phrasings

### Flaky font diffs

Race between font load and snapshot; the font-ready wait removes the race.

### Custom font-face ignored by Percy

Percy's asset discovery must capture the font files; check the snapshot's network log for the font requests.

### Snapshot timing hooks

Use Percy's before-snapshot hooks to run the font wait; do not rely on page load timing alone.

## Why it happens

Percy renders the captured DOM in its own browsers, and font loading is asynchronous relative to DOM readiness. A snapshot taken at DOM-ready usually precedes font-ready, so Percy rasterizes whatever fallback was showing at capture time.

## Edge cases

- document.fonts.ready resolves when initial fonts load; fonts added later (lazy subsets) need their own waits.
- A font that fails to load still lets fonts.ready resolve; check the network log for 404s on font files.
- Approving fallback-font baselines hides the problem; re-baseline after the fix.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_da0ORpWy_eL8q3f6JaZrGw