From 8fa1969848316601a5f7c9604ccabc9534e2681e Mon Sep 17 00:00:00 2001 From: Brian Love Date: Wed, 23 Sep 2026 12:22:59 -0700 Subject: [PATCH] docs(website): correct the stale next/font hashed-family-name claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Inter comment in layout.tsx and the FONTS note in ui.css both said next/font registers families under a hashed name. That was true of older next/font; next/font 16 registers the real name — the built CSS emits `@font-face{font-family:Inter}` and `--font-diagram:"Inter","Inter Fallback"`. #1139's italic split depends on exactly that. The conclusions still hold, so behaviour is unchanged: theme.css's `Inter, system-ui` stack only names the family, and the font file exists only because next/font loads it. Remove the loader and diagrams still fall back to system-ui. Only the stated mechanism was wrong. --- apps/website/src/app/layout.tsx | 11 +++++++---- apps/website/src/styles/ui.css | 19 +++++++++++++------ 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/apps/website/src/app/layout.tsx b/apps/website/src/app/layout.tsx index 8db1dce2d..d7a97b31c 100644 --- a/apps/website/src/app/layout.tsx +++ b/apps/website/src/app/layout.tsx @@ -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'], diff --git a/apps/website/src/styles/ui.css b/apps/website/src/styles/ui.css index f1263e8ad..fc7e748f9 100644 --- a/apps/website/src/styles/ui.css +++ b/apps/website/src/styles/ui.css @@ -101,9 +101,14 @@ * * layout.tsx loads the fonts via next/font, which defines those three * vars on 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 @@ -111,9 +116,11 @@ * 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. */