Static Site Generators in Production

Metric-Matched Fallback Fonts with size-adjust

When a web font loads with font-display: swap, the browser first renders text in a fallback font, then re-renders it in the web font when the file arrives. If the two fonts have different widths and line heights, every paragraph reflows at the moment of swap: lines rewrap, blocks change height, and everything below moves. That movement is layout shift, and on text-heavy static sites it is often the largest single contributor to CLS.

The fix is to stop using the fallback font as it comes. Four @font-face descriptors — size-adjust, ascent-override, descent-override and line-gap-override — let you define a new face that uses a local font's glyphs with the web font's measurements. This guide explains what each descriptor does, how to calculate the values, and how to generate them in the build. It is part of Font Loading Strategies for Static Sites.

Prerequisites

  • A self-hosted web font you can read metrics from.
  • A build step that can run Node.js, or willingness to calculate the numbers once by hand.
  • Field or lab CLS data showing text reflow when fonts swap — see Eliminating Layout Shift from Web Fonts.

Why the Swap Moves Text

Two properties of a font decide how much space a paragraph takes: the average advance width of its characters, which controls how many words fit on a line, and its vertical metrics, which control the height of each line box. Inter and Arial at the same font-size differ on both. Inter is wider, so a paragraph set in Arial wraps later and has fewer lines; Inter's ascent and descent are also larger, so each of those lines is taller.

A paragraph before and after a font swap Three paragraph blocks. Plain Arial fallback takes four lines and 96 pixels. The Inter web font takes five lines and 125 pixels, so content below moves 29 pixels. The metric-matched fallback takes five lines and 125 pixels, the same as Inter, so nothing moves. Same paragraph, same font-size, three faces Plain Arial fallback 4 lines, 96 px Inter web font 5 lines, 125 px swap from Arial: +29 px shift Matched fallback 5 lines, 125 px swap: 0 px shift 360 px column, 16 px text, line-height normal
The matched fallback still draws Arial glyphs, but it occupies Inter's space.

The Four Descriptors

All four go inside an @font-face rule that uses local() as its source, creating a new family name that you place in the font stack between the web font and the generic fallback.

@font-face {
  font-family: 'Inter Fallback';
  src: local('Arial'), local('Helvetica'), local('Liberation Sans');
  size-adjust: 107.12%;
  ascent-override: 90.44%;
  descent-override: 22.52%;
  line-gap-override: 0%;
}

body {
  font-family: 'Inter', 'Inter Fallback', sans-serif;
}
  • size-adjust scales the glyphs and their advance widths. It is the main control for how many words fit on a line.
  • ascent-override sets the height above the baseline used for line box calculation, as a percentage of the used font size.
  • descent-override does the same below the baseline.
  • line-gap-override sets extra leading. Most modern web fonts use 0%, and matching it removes one more source of difference.

The override percentages apply after size-adjust, so derive the ascent and descent values by dividing the web font's metrics by the size adjustment, as shown below.

Calculating the Values

Every value comes from two sets of numbers: the web font's metrics, read from its hhea and OS/2 tables, and the fallback font's average character width.

From font metrics to override percentages Inter's units per em is 2048, ascent 1984, descent 494 and average width 1105 units. Arial's average width scaled to 2048 units is 1032. size-adjust is 1105 divided by 1032, 107.12 percent. ascent-override is 1984 divided by 2048 divided by 1.0712, 90.44 percent. descent-override is 494 divided by 2048 divided by 1.0712, 22.52 percent. Deriving the descriptors for Inter over Arial Measured metrics Inter unitsPerEm: 2048 Inter ascent: 1984 Inter descent: 494 Inter avg width: 1105 Arial avg width: 1032 weighted by English letter frequency Descriptors size-adjust = 1105 / 1032 = 107.12% ascent-override = 1984 / 2048 / 1.0712 = 90.44% descent-override = 494 / 2048 / 1.0712 = 22.52%
Width sets size-adjust; the vertical overrides are then divided by it.

Average width is the part that needs care. A plain mean over all glyphs weights rarely used characters equally with "e" and "t", so tools weight each glyph by how often it appears in the site's language. For English body text the frequency-weighted value lands within one or two percent of the real rendered width; for German, French or code-heavy pages, use the matching frequency table or measure against real content.

Generating Fallbacks in the Build

Calculating by hand works once, but the values must change whenever the font file or weight changes. Generate them instead.

  • fontaine (from the UnJS project) is a Vite and webpack plugin that reads the @font-face rules in your CSS, calculates overrides for a list of fallbacks and injects the extra faces. It works with Astro, Nuxt and any Vite-based build.
  • Capsize exposes the metrics of common fonts as JSON and a createFontStack helper that outputs the fallback @font-face CSS; it suits Eleventy and Hugo pipelines where a small Node script writes a CSS partial.
  • next/font does the same automatically in Next.js, including for static export.

A minimal fontaine setup in Astro:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { FontaineTransform } from 'fontaine';

export default defineConfig({
  vite: {
    plugins: [
      FontaineTransform.vite({
        fallbacks: ['Arial', 'Helvetica Neue', 'Liberation Sans'],
        resolvePath: (id) => new URL(`./public${id}`, import.meta.url),
      }),
    ],
  },
});

After a build, check the emitted CSS: each web font family should have a companion Inter fallback face with the four descriptors, and the font-family stacks should list it second.

Tuning Per Platform

Arial is present on Windows and macOS but absent on most Linux desktops and on Android, where Roboto or Liberation Sans take its place. Each has slightly different widths, so one set of values fits one platform best. Where the difference matters, declare separate fallback faces with values tuned for each local font and list them all:

body {
  font-family: 'Inter', 'Inter Fallback Arial', 'Inter Fallback Roboto', sans-serif;
}

The browser picks the first face whose local() source exists. Test each by forcing the web font to fail — block the font URL in DevTools' network request blocking — and comparing paragraph heights against a normal load.

CLS attributed to font swap before and after metric matching Field CLS p75 from font swap on a documentation template. Windows fell from 0.09 to 0.01, macOS from 0.08 to 0.01, Android from 0.12 to 0.03 after adding a Roboto-tuned face. Field CLS p75 from font swap, by platform 0.09 0.01 Windows 0.08 0.01 macOS 0.12 0.03 Android red: plain fallback, green: matched fallback
Android kept a small residual shift because Roboto's glyph shapes differ more from Inter than Arial's do.

Verifying the Match

Numbers from a tool are a starting point, not proof. Two quick checks confirm the fallback really occupies the same space:

  1. Block the font and compare heights. Load a long article normally and note the height of the main content element in DevTools. Block the WOFF2 URL with network request blocking, reload, and compare. A good match is within one line over several thousand words.
  2. Record a swap on a slow connection. Throttle to "Slow 4G", open the Performance panel and record a load. The Layout Shift track should show no entries at the moment the font arrives; any that remain are attributed to the elements that moved, which points to the face or weight that still needs tuning.

Repeat both checks after any font upgrade, because a new release of the same family can change its metrics.

Measured Impact

On a 900-page documentation site using Inter with font-display: swap, font swap accounted for 71% of attributed layout shift. Adding fontaine-generated Arial and Roboto fallbacks took about an hour, added 480 bytes of CSS and no requests, and moved the docs template from 0.11 to 0.02 CLS at the 75th percentile on mobile. The number of URLs in Search Console's "CLS issue: more than 0.1" group fell from 610 to zero within the 28-day window.

Pitfalls & Rollback

  • Matching only width. size-adjust alone fixes wrapping, but line heights still change; always set the vertical overrides too.
  • Forgetting bold and italic. Each weight and style used above the fold needs its own fallback face, because bold glyphs are wider.
  • Monospace code blocks. Code fonts need their own fallback matched against Courier New or Menlo, or code samples jump on swap.
  • Browser support. Safari added size-adjust in 17; older versions ignore it and simply show the unmatched fallback, which is no worse than before.
  • Rollback: remove the fallback faces and the extra family name from the font stack.

Conclusion

A web font swap shifts layout because the fallback font takes a different amount of space. size-adjust fixes line wrapping, the three override descriptors fix line height, and together they turn a local system font into a stand-in with the web font's footprint. Generate the values in the build with fontaine or Capsize, add faces for each platform's fallback, and verify by blocking the font file — text should look different, but nothing on the page should move.

FAQ

What does size-adjust do in @font-face?

It scales every glyph of the font face by a percentage, changing the average character width and therefore how many characters fit on a line. On a fallback face it is used to make a local font such as Arial set text at the same width as the web font.

Why do I need ascent-override and descent-override as well?

size-adjust fixes width, but line height is computed from the font's ascent, descent and line gap. If those differ, each line of fallback text is a different height and paragraphs still grow or shrink on swap. The overrides set those metrics explicitly.

How do I calculate the override values?

Read the web font's metrics from its OS/2 and hhea tables with a tool such as fontkit or Capsize, compare the average character width with the local fallback's, and derive the percentages. Tools like fontaine and next/font generate the values automatically at build time.

Which local font should I use as the fallback?

Pick a font installed on nearly every device whose shapes are close to the web font — Arial or Helvetica for most sans-serifs, Georgia or Times New Roman for serifs. List platform alternatives in separate fallback faces so each operating system gets tuned values.