Fallback Font Check · Open source
A small command-line tool that measures how closely your fallback font matches your webfont, using the real text on your real pages, one weight band at a time. It tells you which band is off and prints the size-adjust that fixes it.
Needs Node 18.3 or later. The first run also needs a Chromium build for Playwright:
npx playwright install chromiumnpx github:DebugSwiftHQ/fallback-font-check --font "Your Font" --fallback "Your Font Fallback" https://your-site.com/Give it several pages. Your homepage alone probably does not contain every size and weight you use.
The problem
Until a webfont loads, the browser draws text in a fallback font. If the fallback is wider or narrower, lines break in different places. When the webfont arrives, every paragraph re-wraps and everything below it moves. That movement is Cumulative Layout Shift, one of Google's Core Web Vitals.
and waits for the fonts to load.
straight from the page's stylesheets, including each one's font-weight range and current size-adjust. Those ranges become the bands.
rendering the same string at the same size, weight and letter-spacing in both fonts, and taking the width ratio.
the mean ratio per band, a flag on any band out of tolerance, and current size-adjust × mean: the value that brings it to 1.000.
This is the open-source version of the check that keeps debugswift.com honest. It is what found that our automatic fallback ran about 11% wide on body text.
Options
| Option | Default | What it does |
|---|---|---|
| --font <family> | required | The webfont family |
| --fallback <family> | required | The fallback family your @font-face rules declare |
| --tolerance <n> | 0.03 | How far a band's mean may drift, as a fraction |
| --width <px> | 412 | Viewport width. Phone-sized by default, where re-wraps hurt most |
| --min-length <n> | 15 | Shortest string worth measuring |
| --json | off | Machine-readable output |
Limits
Common questions
Those compute one number from the font file's average glyph width, and that average can be well off for your actual copy. On debugswift.com the automatic value ran about 11% wide on 18px body text. Many variable fonts also widen as the weight goes up while Arial barely changes, so one value cannot fit body text and headings at once. This measures your real text, one weight band at a time.
No. It opens your pages in headless Chromium, measures, and prints numbers. You decide whether to paste the suggested size-adjust into your CSS.
Yes. It exits 0 when every band is within tolerance, 1 when at least one band is out, and 2 for bad arguments or no fallback face found. Point it at a preview deployment and a font change or a big copy rewrite cannot quietly bring layout shift back. Add --json for machine-readable output.
Yes. It is MIT licensed. We built it for our own sites and shared it because the problem is not ours alone.
After the numbers
If the fonts are fixed and the page still drags, something further in is the cause. Finding it is the job.
Fixed price agreed before work starts. No hourly billing, no surprises.