XenonStack Insights CSS size-adjust for @font-face: Fix Font Swap Shift

The CSS size-adjust descriptor lets you scale a font inside an @font-face rule. Its most common use is to resize a local fallback font, such as Arial, so it takes up about the same space as your web font and the page does not jump when the web font arrives. According to MDN, it is Baseline Widely available since September 2023.

For enterprise teams the point is visual stability. Fonts that render larger or smaller than their fallback are a listed cause of layout shift on web.dev, and Cumulative Layout Shift (CLS) is a Core Web Vital, with 0.1 or less counted as good at the 75th percentile. This guide also separates size-adjust from the similar font-size-adjust property. For related typography work, see our guide to fluid typography with CSS clamp.

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

size-adjust sets a multiplier for a font's glyph outlines and metrics. MDN says it scales all metrics tied to the font, including glyph advances, baseline tables and the overrides set by other @font-face descriptors. The value is a percentage and the initial value is 100%. Here is the MDN example, which scales a locally installed font to sit better beside a web font:

@font-face {
  font-family: "web-font";
  src: url("https://example.com/font.woff");
}

@font-face {
  font-family: "local-font";
  src: local("Local Font");
  size-adjust: 90%;
}

body {
  font-family: "web-font", "local-font", sans-serif;
}

Source: MDN, size-adjust.

Why do web fonts shift the layout?

When a page shows a fallback font first and swaps to the web font later, the two fonts rarely have the same width and height. Text reflows, and content below it moves. web.dev lists fonts that render larger or smaller than the initial fallback as a cause of layout shifts, and its CLS guide defines a good score as 0.1 or less at the 75th percentile.

The font-display descriptor controls the swap itself. Per MDN, swap shows fallback text at once and switches when the web font loads, while optional uses the fallback for that page view if the font is not ready almost immediately. Matching the fallback with size-adjust reduces the visible jump when a swap happens. See MDN, font-display.

How do you build a size-matched fallback font?

web.dev describes the method: declare a local font such as Arial as a new font family, scale it with size-adjust, and list it after the web font in your font-family stack. It notes that the order of the font-family list is critical. Its example uses a Roboto fallback built from Arial:

@font-face {
  font-family: "Roboto-fallback-1";
  size-adjust: 100.06%;
  src: local("Arial");
}

html {
  font-family: "Roboto Regular", "Roboto-fallback-1", "Roboto-fallback-2";
}

web.dev points to a calculator by Malte Ubl that generates this snippet for a chosen Google Font. It also describes two calibration targets. In the first, you adjust a local font toward the downloaded brand font. In the second, you adjust the downloaded font toward the local font. Source: web.dev, CSS size-adjust for @font-face.

What do ascent-override, descent-override and line-gap-override add?

size-adjust alone changes scale, not the vertical layout of the line box. web.dev lists three descriptors for the finer tuning:

MDN marks ascent-override as limited availability, meaning it is not Baseline, so treat the overrides as an enhancement and test on your target browsers. See MDN, ascent-override.

How is size-adjust different from font-size-adjust?

The two are easy to confuse. They solve a similar problem in different places:

The font-size-adjust formula on MDN is u = (m / m') x s, where m is the target ratio, m' is the chosen metric of the font being adjusted divided by its font size, and s is the font-size. MDN's worked example: a first-choice font of 12px with a cap-height ratio of 0.20, and a fallback with 0.15, gives (0.20 / 0.15) x 12 = 16px. A value of 0 hides the text and negative values are invalid. MDN also warns that if a metric is overridden with size-adjust, size-adjust has no effect when combined with font-size-adjust. Source: MDN, font-size-adjust.

Here is a small sketch of the property in use, with the 0.545 x-height ratio MDN gives for Verdana:

.times {
  font-family: "Times", serif;
  font-size: 14px;
  font-size-adjust: 0.545;
}

What is the current browser support?

Older guides often describe font-size-adjust as unusable in Safari, so confirm current support on the MDN compatibility tables before you decide.

When should you not use it?

• If your fallback and web font already share similar metrics, the gain is small and the extra @font-face rules are not worth maintaining.
• If you rely on font-size-adjust with a number that differs from the first-choice font, MDN says the first-choice font is scaled too. Use font-size instead in that case.
• If you need exact vertical rhythm in old browsers, test the overrides, because ascent-override is limited availability on MDN.
• Do not tune by eye alone. Measure CLS in real user data, as web.dev recommends, at the 75th percentile.

How should a team adopt it?

1. Measure current CLS and find the shifts caused by font swaps.
2. Choose a font-display value, then build a local fallback with size-adjust.
3. Add the ascent, descent and line-gap overrides if the lines still move.
4. Test on your supported browsers, then re-measure.
5. Keep the fallback rules in your design system so every team reuses them.

Front-end quality sits inside a wider delivery process. ElixirClaw is described on its site as an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control, and ElixirData Context OS as keeping governed context, versioned policy and decision traces in one decision layer above AI agents. Related reading: user experience design, conversational user interface best practices and performance monitoring.

To map one front-end quality decision your AI agents should make, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop.

Frequently asked questions

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

It sets a percentage multiplier for a font's glyph outlines and metrics, so fonts rendered at the same font-size can be made to look closer in size. Its initial value is 100%, according to MDN.

Does size-adjust stop layout shift on its own?

No. It scales the fallback font, but line height also depends on the ascent, descent and line-gap metrics. web.dev pairs size-adjust with ascent-override, descent-override and line-gap-override to fine-tune the text box.

What is the difference between size-adjust and font-size-adjust?

size-adjust is an @font-face descriptor that scales one font face. font-size-adjust is a CSS property that scales every font used on an element so a chosen metric, by default the x-height, matches a target ratio. MDN notes that size-adjust has no effect when combined with font-size-adjust for an overridden metric.

Is size-adjust supported in all browsers?

MDN lists size-adjust as Baseline Widely available since September 2023, and font-size-adjust as Baseline 2024 (newly available since July 2024). It lists ascent-override as limited availability, so check the MDN compatibility tables before relying on the overrides.

How is font-size-adjust calculated?

MDN gives the formula u = (m / m') x s, where m is the target ratio, m' is the chosen metric of the font being adjusted divided by its font size, and s is the font-size. For example, (0.20 / 0.15) x 12px = 16px.