Why My Fonts Caused Layout Shift: Field Notes on next/font, size-adjust, and Arabic Fallback Metrics

Font-driven layout shift occurs when the fallback font the browser paints first occupies a different box than the webfont that replaces it. Next/font addresses this issue for Latin text by generating a size-adjusted fallback @font-face automatically. However, it does not handle Arabic text, requiring manual computation of the override descriptors.

The reporter runs a bilingual site and observed layout shifts on Arabic routes during cold loads. The key takeaways are that font layout shift is a metrics mismatch, not a download-speed issue, and that next/font self-hosts font files, preloads them per route, and generates a fallback @font-face with size-adjust, ascent-override, descent-override, and line-gap-override properties.

To remove swap-driven shift, font-display: optional can be used, which has a brief block period and a zero swap period. Download speed does not affect the layout shift, and a warm font cache hides the bug even on local tests. The main causes of font-related layout shift involve the average character width of the fallback and webfont, and the ascent-to-descent ratio, which sets the line box height.

The generated fallback by next/font uses Arial or Times New Roman for non-Latin scripts, and it does not pre-load fonts imported in components that never render. Additionally, if CSS re-declares font-family using family names instead of the variable returned by the loader, the generated fallback may be dropped from the chain entirely.