Skip to content

Correct the stale next/font hashed-family-name comments #1141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
blove merged 1 commit into from
Sep 23, 2026
+20 −10
Merged

Correct the stale next/font hashed-family-name comments #1141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions apps/website/src/app/layout.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,10 +84,13 @@ const sansItalic = Archivo({

/**
* Inter is retained for diagrams only, and MUST be loaded here rather than
* left to theme.css: next/font registers its family under a hashed name, so
* theme.css's raw `Inter, system-ui` stack never matches it and would silently
* fall back to system-ui. Diagram geometry is pinned to Inter's metrics —
* see the FONTS note in src/styles/ui.css and e2e/home-architecture.spec.ts.
* left to theme.css. theme.css's `Inter, system-ui` stack only names the
* family; this loader is what actually ships the font file. Without it no
* `Inter` face exists and diagrams silently fall back to system-ui. (Older
* next/font versions also registered hashed family names, which a raw stack
* could never match; next/font 16 registers the real name, `Inter`.) Diagram
* geometry is pinned to Inter's metrics — see the FONTS note in
* src/styles/ui.css and e2e/home-architecture.spec.ts.
*/
const diagram = Inter({
subsets: ['latin'],
Expand Down
19 changes: 13 additions & 6 deletions apps/website/src/styles/ui.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,19 +101,26 @@
*
* layout.tsx loads the fonts via next/font, which defines those three
* vars on <html> with self-hosted, size-adjusted stacks ("Inter",
* "Inter Fallback", etc.). Raw literals like `Inter, system-ui` only
* matched a locally-installed Inter (next/font registers its family
* under a hashed name), so they silently fell back to system fonts.
* "Inter Fallback", etc.). Raw literals like `Inter, system-ui` are how
* this went wrong: the next/font of the time registered families under
* hashed names, so a raw name matched only a locally-installed Inter and
* those sites silently fell back to system fonts. next/font 16 registers
* the real family name (verified in the built CSS: `font-family:Inter`),
* so a raw literal would now match while the loader is present. The vars
* remain the rule anyway: they carry the size-adjusted fallback stacks
* and keep one source of truth.
* The 2026-08-30 unification (findings audit §10) moved all sites onto
* the vars — a deliberate visual change: real webfonts everywhere, no
* more mixed stacks. theme.css also defines the same var names from
* the design tokens; next/font's <html>-level values win, which is now
* the intended resolution, and they guarantee the vars always resolve.
*
* --font-diagram is diagram-only and MUST keep being supplied by next/font in
* layout.tsx. theme.css emits it as a raw `Inter, ...` stack, which next/font's
* hashed family never matches — so if the loader is removed, diagrams silently
* fall back to system-ui, every glyph width shifts, and
* layout.tsx. theme.css emits it as a raw `Inter, ...` stack, and that stack
* only NAMES the family — the font file exists only because next/font loads
* it. Remove the loader and nothing supplies an `Inter` face, so diagrams
* silently fall back to system-ui (or whatever Inter happens to be installed
* locally), every glyph width shifts, and
* e2e/home-architecture.spec.ts (which measures text runs against their cards)
* is the only thing that will notice.
*/
Expand Down
Loading