This site sets its text in IBM Plex Sans and IBM Plex Mono, the fonts on my CV. Web fonts arrive after the HTML, so for a moment the browser either shows a system font or shows nothing. If the system font takes up a different amount of space, text re-wraps when Plex lands and the page jumps. That jump is layout shift, and Lighthouse scores it as CLS (Cumulative Layout Shift).
This post is how the site got to a Lighthouse CLS of 0, and the parts that didn't work on the way. The short version: matching the fallback font got close, a CSS unit was quietly breaking it, a clever fix was too fragile to keep, about 200 tunings of a simple fix still left one paragraph moving, and in the end the fix was to change font-display instead of the font. I didn't write this code: a small team of Claude Code agents (a lead, frontend, QA and infra) built and tuned it while I directed. The fixes, the measuring and the tuning below were theirs. The QA agent's review is what stopped the team from keeping the clever fix.
Only three font files ship: Plex Sans 400, Plex Sans 600 and Plex Mono 400. They're self-hosted, latin subset only, and their @font-face rules are inlined in the <head>. The two Sans files are preloaded, because the home page's largest text and every h1 use them. Mono isn't, because it's never in that text.
Each web font has a local "Fallback" face listed right after it in the font stack. It points at a system font through local() and reshapes it with three descriptors:
size-adjustscales the glyphs, so the system font's letters are about as wide as Plex's (MDN).ascent-overrideanddescent-overrideset the line box, so a line of fallback text is exactly as tall as a line of Plex.
The vertical numbers come from @capsizecss/metrics: Plex has 1000 units per em, an ascent of 1025 and a descent of 275, and no line gap. The one subtle bit is that size-adjust also scales the overrides, so you divide Plex's values by it to keep Plex's line box. The site generates the rules with a small helper in app/fonts.ts:
const face = (family: string, weight: number, locals: string[], size: number) =>
`@font-face{font-family:"${family}";font-style:normal;font-weight:${weight};src:${locals.map((l) => `local("${l}")`).join(",")};size-adjust:${pct(size)};ascent-override:${pct(10250 / size)};descent-override:${pct(2750 / size)};line-gap-override:0%}`;For Sans 400 that comes out as (local list shortened):
@font-face {
font-family: "IBM Plex Sans Fallback";
font-weight: 400;
src: local("Arial"), local("ArialMT"), local("Liberation Sans"), local("Roboto");
size-adjust: 100%;
ascent-override: 102.5%;
descent-override: 27.5%;
line-gap-override: 0%;
}Sans 600 uses 97.5%. Mono is the easy one: both fonts are monospaced, so a single ratio is exact (99.66% for Menlo, 99.98% for Courier New).
The height is solved by arithmetic. The width is the hard part. Arial's letters aren't Plex's letters, and size-adjust can only scale all of them by the same amount. So a word that's a little wider in one font than the other can still push a line over the edge.
The first real bug wasn't a font metric. Lighthouse measured CLS 0.0147 on /stage/zemoga on every run, and the page has nothing that loads late except the fonts.
The text column used Tailwind's max-w-prose, which is 65ch. The ch unit is the width of the "0" glyph in whichever font is showing. While the fallback showed, the column was 578 px wide. When Plex arrived it became 624 px. Every paragraph in that column re-wrapped on swap, however well the glyphs matched.
The fix is to size the column in em, which follows the font size, not the font. Plex's "0" is 0.6 em wide, so 65ch of Plex is exactly 39em:
// tailwind.config.js
maxWidth: { prose: "39em" },The column is now the same width in every font, on every platform. This is the one part of the story that never needed revisiting. If you size text columns in ch and use a web font, it's worth checking.
Even with a fixed column, a few lines still wrapped differently. The next fix was clever. Tahoma's letter widths were closer to Plex than Arial's, so on macOS and Windows the Sans fallback became Tahoma. Then it was split with unicode-range into separate faces for spaces, digits, punctuation, capitals and everything else, each with its own size-adjust. Ten faces in total, with an Arial-tuned family after them for platforms without Tahoma. It added 305 B to the home page.
It worked where it was measured. The QA agent measured CLS 0 on all 8 pages at 375, 412 and 1280 px wide, with Tahoma, in Chromium on macOS.
QA's verdict was "it works where it was tuned, but it's fragile", and the reasons hold up:
- It was tuned to sub-pixel margins in the current copy: 0.3 px of room on the home page's main line, and a 1–3 px knife-edge on another line. One ordinary copy edit could bring a shift back.
- It was measured only on macOS. Windows renders Tahoma with different hinting, and nobody had checked whether Safari supports the overrides.
- Splitting spaces, digits and punctuation into separate faces drops kerning across those boundaries while the fallback shows.
- It cost about 0.3 KB on every page.
- Phones, which have no Tahoma, never used it. On the Arial-tuned path the home page at 375 px still shifted by 0.0159, and with Verdana standing in for the wider DejaVu Sans, 18 of 24 page and width combinations shifted, up to 0.061.
The worst part was that CI checked none of it. The font tests skipped when Tahoma wasn't installed, so on Linux CI all 16 of them skipped, and the build stayed green. The site had a test suite that proved the fix only on the machine where it was tuned.
The decision (amendment 14 in the spec) was to drop the Tahoma layer, keep 39em, and restate the goal in two halves: Lighthouse CLS 0 on every page, and font-swap CLS under 0.1 on every platform. 0.1 is the line web.dev calls "good".
Back to one Arial-tuned face per weight, the same on every platform. The method was a sweep: hold the web fonts back 800 ms, load all 8 pages at 375, 412 and 1280 px, and measure the shift for each size-adjust.
Some results were good. Sans 600 doesn't shift anything anywhere between 96.5 and 98.5%. Sans 400 keeps the home page's summary paragraph on Plex's line breaks at 375 px with any value from 99.75 to 100.25%, and 100.5% re-wraps it.
But one paragraph never settled. A Context paragraph on /stage/zemoga at 412 px is 2 lines in Arial and 3 lines in Plex. A size that fixed it moved a line on another page, and a size that fixed that page brought it back. A single scale factor can't make two different typefaces break lines in the same places across all the copy on a site, and the agents spent about 200 tunings proving that the long way.
The fix was to stop swapping. The two Plex Sans faces now use font-display: optional. Per MDN, optional gives the font an extremely small block period and no swap period, while swap has an infinite swap period.
In practice:
- On a normal first visit the two preloaded Sans files are small and arrive inside that short window, so the page renders in Plex from the first paint.
- On a slow first visit they arrive late, so the page stays in the matched fallback for that whole view. Nothing swaps, so nothing moves.
- Either way the download finishes and is cached, so the next page is in Plex.
This is why the fallback tuning still matters: with optional, a slow visitor reads the entire page in it.
Plex Mono stays on swap. Its fallback is matched exactly, so its swap moves nothing (measured CLS 0). optional was tried for Mono too and dropped: on a cold load, the prompt lines, labels and wordmark stayed in the system monospace for the whole view. That's a visible change of look for no gain.
The cost is real and accepted in the spec: on a slow first visit, someone may read a page in Arial instead of Plex. For a portfolio, a stable page in a decent font beats a jump into the right one.
The failure I most wanted to avoid repeating was "the tests pass because they didn't run". Two tools check two halves of the goal, because neither one can see both.
lighthouserc.json runs every page on a throttled mobile profile and asserts CLS on every one:
"cumulative-layout-shift": ["error", { "maxNumericValue": 0, "aggregationMethod": "pessimistic" }]pessimistic means the worst run counts. The limit is exactly 0, not a small tolerance, because Chrome reports a page with no shift as exactly 0, and the smallest real defect seen here was 0.0037. A negative check that set one /stage/zemoga run to 0.001 made lhci assert fail, as it should.
When QA ran Lighthouse on the play levels, all 24 runs scored 100 in all four Lighthouse categories, with CLS 0. That run was on a build that still had the Tahoma layer, and there's no committed Lighthouse record for the final setup yet. From here on, the assertion is what holds it to 0.
Lighthouse alone isn't enough, though. It caught the 0.0147, but in QA's later runs it got the fonts before first paint, so it reported 0 no matter how good the fallback was.
The second half is an end-to-end test with Playwright. It intercepts every .woff2 request, holds it 800 ms, records layout-shift entries with a PerformanceObserver, and fails if the total reaches 0.1. It runs on every page in its list, at mobile and desktop widths, using whatever fallback the machine has.
e2e/fonts.spec.ts also checks the shape of the setup: Sans is optional, Mono is swap, both Sans files are preloaded, there's no Tahoma or unicode-range left, and every fallback face has Plex's line box. It checks that a normal load renders the h1 and body text in Plex, reading the font Chromium actually used through the DevTools protocol. And it checks that a slow load keeps the fallback instead of swapping late.
Since the old suite went green by skipping, there's a small script, .github/scripts/check-font-guard.mjs, that reads Playwright's JSON report. It fails the job unless every expected swap-guard test ran and passed, and unless fonts.spec.ts ran at least one test in every project. A renamed or skipped test now fails CI instead of passing it.
- The site is live now, but every Lighthouse figure here comes from a local production build. None has been taken on the live site, so none of this is measured on real visitors' networks.
- The Linux fallback path now holds in CI: the swap guard passed 20 of 20 on GitHub's Linux runner. That's a headless browser in CI, not a visitor's machine.
- Safari's support for
ascent-overrideanddescent-overridehasn't been checked, and WebKit wasn't installed for the QA pass. - Android's Roboto path couldn't be measured, and none of this has been tried on a real phone or in Windows Chrome or Edge yet.
If we did it again, I'd point the agents at em widths and font-display: optional on the text faces first, and only then have them tune the fallback. That would have saved about 200 tunings, though I wouldn't have learned that ch changes with the font.