Skip to content

fix(web): stop Figtree font-swap shift in neta-pixel theme - #541

Closed
markbang wants to merge 2 commits into
mainfrom
fix/figtree-theme-cls
Closed

markbang wants to merge 2 commits into
mainfrom
fix/figtree-theme-cls

Conversation

@markbang

Copy link
Copy Markdown
Collaborator

Summary

Visitors who pick the neta-pixel theme (or neta-pixel-dark) see Figtree on public pages. Figtree loads late and swaps in over the fallback, so text reflows.

resolve theme (app.html inline script)
  neta-pixel / neta-pixel-dark -> preload /fonts/figtree-latin-wght-normal.woff2
themes/neta-pixel.css
  @font-face "Figtree Variable"  -> same URL (one request)
  @font-face "Figtree Fallback"  -> local Arial/Arimo, metric-matched
  --font-sans: Figtree Variable, Figtree Fallback, CJK ..., system-ui
  • The preload runs in the inline theme script, so it starts before first paint. Other themes and the default theme do not request it.
  • Figtree Fallback values: size-adjust: 99.8986%, ascent-override: 95.0965%, descent-override: 25.0254%, line-gap-override: 0%. size-adjust is the ratio of Figtree to Arimo text width (Chrome, 16 px, English pricing and docs text: 0.998986). Ascent and descent are Figtree's hhea 950/250 divided by that ratio.
  • packages/sdk/src/board/model/themes.ts is regenerated (generate:board-themes) because the Board font stack now lists the fallback.
  • Font file: Figtree Latin woff2 from @fontsource-variable/figtree with its OFL licence.

Does not touch app.css. #536 edits the Geist imports in app.css and adds a root preload, and both touch the font setup. Whichever lands second rebases.

Evidence

Measured on a production build served as cohub.live (HTTP/2 and HTTP/1 for warm visits), Chrome, neta-pixel set in localStorage. Medians of 3 runs. Full numbers and screenshots: https://public.cohub.live/p/ead34bb8-3796-4c07-8f80-2ecc7b8e9411/figtree-cls/SUMMARY.md

Page Viewport Measure main this PR
/pricing 390 Lighthouse CLS 0.4709 0.4705
/pricing 390 scroll 8 screens 0.0406 0.0406
/pricing 390 from load 0.3902 0.3902
/pricing 1440 Lighthouse CLS 0.1976 0.1780
/pricing 1440 scroll 8 screens 0.1245 0.1065
/zh/pricing 390 Lighthouse CLS 0.4946 0.4944
/zh/pricing 390 from load 0.0421 0.3314
/zh/pricing 1440 scroll 8 screens 0.1048 0.1046

Font swap alone (app JS blocked, so only the theme script and fonts run), CLS:

Viewport main, neta-pixel this PR, neta-pixel default theme
1440 0.01801 0.00000 0.00056
390 0.00000 0.00000 0.00000

Default theme (no stored choice): /pricing 390 and 1440 Lighthouse and scroll match main to four decimals. No Figtree request. Dark and neta-studio load only Geist.

Second visit (warm cache): Figtree renders on the second visit. The font file is revalidated rather than served from cache, because the adapter only marks /_app/immutable/* as immutable.

/zh/pricing 390 from-load is bimodal on main (about 0.04 or 0.33 per run), and this PR lands in the 0.33 mode, as the default theme does. Remaining CLS is not font-related. On both main and the default theme, the FAQ and plans sections reflow during hydration, and that is what makes up the numbers above. #536 targets that.

Not covered: a live cohub.live run, a combined run with #536, and Arial on macOS or Windows (only Arimo, the metric-compatible font, was installed here).

Checks: pnpm lint (exit 0; the warnings listed are on main), apps/web typecheck (0 errors), apps/web test (485 + 3 + 3 pass).

Merge Danger

Door: two-way

Only neta-pixel and neta-pixel-dark change. Other themes and the default theme are unchanged.

Blast Radius: neta-pixel theme, public pages

Ramifications: one extra font request (about 20 KB) for neta-pixel visitors. The Board font stack in the SDK lists one more name, which is harmless where it is not installed.

Preload Figtree's Latin file when neta-pixel (or neta-pixel-dark) resolves,
serve it from a same-URL @font-face, and fall back to a metric-matched
Arial stand-in so the swap does not move text on public pages.

Cohub Session: https://cohub.live/spaces/ead34bb8-3796-4c07-8f80-2ecc7b8e9411/sessions/4df2dafb-5eea-453a-b238-118f614ad274
Drop the static copy of the Figtree Latin file. The preload URL comes from
the hashed fontsource asset via hooks.server.ts, so the font is served with
the immutable cache header and the same URL as the @font-face. Add a bold
Arial fallback (weight 501-900) with its own size-adjust.

Cohub Session: https://cohub.live/spaces/ead34bb8-3796-4c07-8f80-2ecc7b8e9411/sessions/4df2dafb-5eea-453a-b238-118f614ad274
@markbang

Copy link
Copy Markdown
Collaborator Author

reopen after #536 lands

@markbang markbang closed this Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant