perf: self-host the Source Sans 3 webfont

[mmcky]

Drops the last third-party origin from the critical path: Source Sans 3 is now served from the site's own origin.

Note

Stacked on #139. Based on fix/relative-css-asset-urls, not main. Without that fix the emitted font URLs are absolute /myst_assets_folder/… paths that resolve under myst start but 404 in myst build --html — so the font would fail silently in exactly the mode the lectures deploy in. Review or merge #139 first; GitHub will retarget this to main automatically.

Why this one matters more than the CDN stylesheets already removed

styles/app.css opened with a CSS @import to fonts.googleapis.com. Two things make it a worse problem than the jsdelivr stylesheets #124/#125 dealt with:

• It is the body font on every page, not the maths on some of them. Where Google Fonts is blocked — mainland China, a significant share of the QuantEcon readership — the whole lecture renders in the system sans.
• An @import is the worst shape a critical-path request can have. It is discovered only once app.css has downloaded and parsed, so the browser cannot preload it, and the chain ran app.css → Google's CSS → fonts.gstatic.com woff2 across two extra origins before any text could paint in the intended face.

What changed

The font ships from @fontsource-variable/source-sans-3, imported from app/links.ts — the module #125 introduced for KaTeX — so esbuild rewrites the url()s and emits the 14 .woff2 files alongside every other bundled asset.

It deliberately is not @imported from styles/app.css: Tailwind does not rebase url() inside an imported stylesheet, so the paths would resolve against the Tailwind output file and 404.

Two stylesheets are imported, upright and italic. Lecture prose uses both, and without the italic faces the browser synthesises an oblique from the upright, which measures wider and shifts the layout.

The links are declared on the root route rather than the two page routes like KatexCSS, because root's links() are the only ones that also apply when the root ErrorBoundary renders — the body font should be right on a 404 too.

The package declares the family as Source Sans 3 Variable, so tailwind.config.js and the inlined CRITICAL_CSS in app/root.tsx name it that way as well, keeping plain Source Sans 3 next in the stack for a locally installed copy and sans-serif as the tail.

First paint is unaffected

Worth being explicit, since this touches the critical CSS the #123 FOUC guard protects. The @font-face rules live in a <link>, so they are not available on the first painted frame — and they were not before either, since the Google @import sat inside app.css. The sans-serif tail is what paints in both cases; the webfont swaps in when the stylesheet lands. Nothing about the FOUC guard's premise changes.

The guard itself is tightened: it asserted /Source Sans 3/, and "Source Sans 3 Variable" contains that string, so the old regex would have kept passing even if CRITICAL_CSS and tailwind.config.js drifted apart. It now matches the head of the stack.

Verification

Static build gate first, since that is the mode that decides the mechanism — a real myst build --html of the fixture against make build-theme:

check	result
absolute myst_assets_folder URLs left in any stylesheet	0
asset references that resolve on disk	74 of 74
Source Sans 3 woff2 files in the static output	14
googleapis references in the built CSS	0
declared family in the compiled bundle	Source Sans 3 Variable,Source Sans 3,sans-serif

Then: npm run compile clean · npm run test:fouc 2 passed · full visual suite 19 passed, 0 failed with every baseline untouched — which is the evidence that rendered text is unchanged, i.e. fontsource's build is metric-identical to what Google was serving.

Closes #131

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-24 23:19 UTC

[Copilot]

Pull request overview

This PR self-hosts the Source Sans 3 font (variable + italic) so the body font no longer depends on Google Fonts and avoids an @import-driven critical-path request chain. It integrates the font via the existing Remix/esbuild “import CSS → emit assets” flow used for KaTeX, and updates the font-family stack in Tailwind + inline critical CSS accordingly.

Changes:

• Add @fontsource-variable/source-sans-3 and serve its upright/italic CSS from app/links.ts, applied from the root route.
• Remove the Google Fonts @import from styles/app.css and update font-family stack usages (tailwind.config.js, CRITICAL_CSS, FOUC guard test).
• Document the change in CHANGELOG.md.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/visual/fouc.spec.ts	Tightens the FOUC guard to check the updated font stack.
tailwind.config.js	Updates theme.extend.fontFamily.sans to include "Source Sans 3 Variable".
styles/app.css	Removes Google Fonts @import and documents why imports must come from Remix, not CSS.
package.json	Adds @fontsource-variable/source-sans-3 dependency.
package-lock.json	Locks the new font package and updates lockfile metadata.
CHANGELOG.md	Records the switch from Google Fonts to self-hosted Source Sans 3.
app/root.tsx	Uses the new font stack in CRITICAL_CSS and adds root-level <link>s for the font CSS.
app/links.ts	Adds SourceSans3CSS link descriptors for upright + italic stylesheets.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mmcky]

Note on CI coverage while this is stacked: ci.yml triggers on pull_request: branches: [main], so a PR based on another branch gets only the preview job — no typecheck, visual or FOUC run here yet. They will run automatically once #139 merges and GitHub retargets this to main.

Locally, against a make build-theme of this branch: npm run compile clean, test:fouc 2 passed, full visual suite 19 passed / 0 failed with baselines untouched, and a real myst build --html resolves 74 of 74 asset references with 0 absolute myst_assets_folder URLs remaining.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 8 changed files in this pull request and generated no new comments.

[mmcky]

@DrDrij merging this.