Skip to content

perf(theme): cache fonts and add metric-matched fallbacks #1

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
Madraka merged 1 commit into from
Oct 21, 2026
Merged

perf(theme): cache fonts and add metric-matched fallbacks #1

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
0 public/fonts/fraunces-OFL.txt → public/fonts/v1/fraunces-OFL.txt
View file
Open in desktop
File renamed without changes.
0 ...onts/fraunces-latin-ext-wght-normal.woff2 → ...s/v1/fraunces-latin-ext-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 ...ic/fonts/fraunces-latin-wght-normal.woff2 → ...fonts/v1/fraunces-latin-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 public/fonts/inter-OFL.txt → public/fonts/v1/inter-OFL.txt
View file
Open in desktop
File renamed without changes.
0 ...c/fonts/inter-latin-ext-wght-normal.woff2 → ...onts/v1/inter-latin-ext-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 public/fonts/inter-latin-wght-normal.woff2 → ...ic/fonts/v1/inter-latin-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 public/fonts/jetbrains-mono-OFL.txt → public/fonts/v1/jetbrains-mono-OFL.txt
View file
Open in desktop
File renamed without changes.
0 ...etbrains-mono-latin-ext-wght-normal.woff2 → ...etbrains-mono-latin-ext-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 ...ts/jetbrains-mono-latin-wght-normal.woff2 → ...v1/jetbrains-mono-latin-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 public/fonts/source-sans-3-OFL.txt → public/fonts/v1/source-sans-3-OFL.txt
View file
Open in desktop
File renamed without changes.
0 ...source-sans-3-latin-ext-wght-normal.woff2 → ...source-sans-3-latin-ext-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 ...nts/source-sans-3-latin-wght-normal.woff2 → .../v1/source-sans-3-latin-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 public/fonts/source-serif-4-OFL.txt → public/fonts/v1/source-serif-4-OFL.txt
View file
Open in desktop
File renamed without changes.
0 ...ource-serif-4-latin-ext-wght-normal.woff2 → ...ource-serif-4-latin-ext-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 ...ts/source-serif-4-latin-wght-normal.woff2 → ...v1/source-serif-4-latin-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 public/fonts/space-grotesk-OFL.txt → public/fonts/v1/space-grotesk-OFL.txt
View file
Open in desktop
File renamed without changes.
0 ...space-grotesk-latin-ext-wght-normal.woff2 → ...space-grotesk-latin-ext-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
0 ...nts/space-grotesk-latin-wght-normal.woff2 → .../v1/space-grotesk-latin-wght-normal.woff2
View file
Open in desktop
File renamed without changes.
9 changes: 6 additions & 3 deletions scripts/copy-studio.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@ const from = path.join(cli, "dist/assets/studio");
const pub = new URL("../public/", import.meta.url).pathname;
await rm(path.join(pub, "assets"), { recursive: true, force: true });
await cp(from, pub, { recursive: true, filter: (src) => !src.endsWith(".map") });
// Studio's own headers (CSP etc.) for its files; the site's pages set their own.
const headers = await readFile(path.join(from, "_headers"), "utf8").catch(() => "");
if (headers) await writeFile(path.join(pub, "_headers"), headers);
// Studio's own headers (CSP etc.) for its files; the site's pages set their own. The theme's
// fonts never change under a path (a new set gets /fonts/v2/): cached for a year, so a reload
// draws the text in its font from the first paint instead of swapping it in later.
const studio = await readFile(path.join(from, "_headers"), "utf8").catch(() => "");
const fonts = "/fonts/v1/*\n Cache-Control: public, max-age=31536000, immutable\n";
await writeFile(path.join(pub, "_headers"), `${studio.trimEnd()}\n\n${fonts}`.trimStart());
console.log(`Studio copied from ${from}`);
18 changes: 12 additions & 6 deletions src/fonts.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,18 @@
* (Turkish and other accented letters) load on demand through fonts.css's unicode ranges.
*/
export const PAIRING_PRELOADS: Readonly<Record<string, readonly string[]>> = {
editorial: ["/fonts/fraunces-latin-wght-normal.woff2", "/fonts/inter-latin-wght-normal.woff2"],
modern: ["/fonts/space-grotesk-latin-wght-normal.woff2", "/fonts/inter-latin-wght-normal.woff2"],
humanist: ["/fonts/source-sans-3-latin-wght-normal.woff2"],
editorial: [
"/fonts/v1/fraunces-latin-wght-normal.woff2",
"/fonts/v1/inter-latin-wght-normal.woff2",
],
modern: [
"/fonts/v1/space-grotesk-latin-wght-normal.woff2",
"/fonts/v1/inter-latin-wght-normal.woff2",
],
humanist: ["/fonts/v1/source-sans-3-latin-wght-normal.woff2"],
technical: [
"/fonts/jetbrains-mono-latin-wght-normal.woff2",
"/fonts/inter-latin-wght-normal.woff2",
"/fonts/v1/jetbrains-mono-latin-wght-normal.woff2",
"/fonts/v1/inter-latin-wght-normal.woff2",
],
classic: ["/fonts/source-serif-4-latin-wght-normal.woff2"],
classic: ["/fonts/v1/source-serif-4-latin-wght-normal.woff2"],
};
36 changes: 24 additions & 12 deletions src/styles/features/tokens.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,29 +55,41 @@
font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
}
/*
* Font pairings (RFC-0023 §2): the families come from fonts.css and load only when used. They win
* Font pairings (RFC-0023 §2): the families come from fonts.css and load only when used; each is
* followed by its metric-matched fallback (font-fallbacks.css), so the swap does not move the
* text. They win
* over the older typeface setting; `system` keeps it.
*/
[data-ch-type-pairing="editorial"] {
--ch-font-display: "Fraunces Variable", ui-serif, Georgia, serif;
--ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
--ch-font-display: "Fraunces Variable", "Fraunces Variable Fallback", ui-serif, Georgia, serif;
--ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
}
[data-ch-type-pairing="modern"] {
--ch-font-display: "Space Grotesk Variable", ui-sans-serif, system-ui, sans-serif;
--ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
--ch-font-display:
"Space Grotesk Variable", "Space Grotesk Variable Fallback", ui-sans-serif, system-ui,
sans-serif;
--ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
}
[data-ch-type-pairing="humanist"] {
--ch-font-display: "Source Sans 3 Variable", ui-sans-serif, system-ui, sans-serif;
--ch-font-text: "Source Sans 3 Variable", ui-sans-serif, system-ui, sans-serif;
--ch-font-display:
"Source Sans 3 Variable", "Source Sans 3 Variable Fallback", ui-sans-serif, system-ui,
sans-serif;
--ch-font-text:
"Source Sans 3 Variable", "Source Sans 3 Variable Fallback", ui-sans-serif, system-ui,
sans-serif;
}
[data-ch-type-pairing="technical"] {
--ch-font-display: "JetBrains Mono Variable", ui-monospace, monospace;
--ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
--ch-font-code: "JetBrains Mono Variable", ui-monospace, monospace;
--ch-font-display:
"JetBrains Mono Variable", "JetBrains Mono Variable Fallback", ui-monospace, monospace;
--ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
--ch-font-code:
"JetBrains Mono Variable", "JetBrains Mono Variable Fallback", ui-monospace, monospace;
}
[data-ch-type-pairing="classic"] {
--ch-font-display: "Source Serif 4 Variable", ui-serif, Georgia, serif;
--ch-font-text: "Source Serif 4 Variable", ui-serif, Georgia, serif;
--ch-font-display:
"Source Serif 4 Variable", "Source Serif 4 Variable Fallback", ui-serif, Georgia, serif;
--ch-font-text:
"Source Serif 4 Variable", "Source Serif 4 Variable Fallback", ui-serif, Georgia, serif;
}
[data-ch-type-pairing]:not([data-ch-type-pairing="system"]) .ch-body {
font-family: var(--ch-font-text);
Expand Down
53 changes: 53 additions & 0 deletions src/styles/font-fallbacks.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
/*
* Generated by scripts/font-fallbacks.ts: do not edit. Metric-matched fallback faces for the
* pairings' web fonts (tokens.css lists each right after its web font), so the swap to the web
* font does not move the text.
*/
@font-face {
font-family: "Fraunces Variable Fallback";
src: local("Times New Roman"), local("TimesNewRomanPSMT");
size-adjust: 113.62%;
ascent-override: 86.08%;
descent-override: 22.44%;
line-gap-override: 0.00%;
}
@font-face {
font-family: "Inter Variable Fallback";
src: local("Arial"), local("ArialMT");
size-adjust: 107.12%;
ascent-override: 90.44%;
descent-override: 22.52%;
line-gap-override: 0.00%;
}
@font-face {
font-family: "Space Grotesk Variable Fallback";
src: local("Arial"), local("ArialMT");
size-adjust: 109.47%;
ascent-override: 89.89%;
descent-override: 26.67%;
line-gap-override: 0.00%;
}
@font-face {
font-family: "Source Sans 3 Variable Fallback";
src: local("Arial"), local("ArialMT");
size-adjust: 92.42%;
ascent-override: 110.80%;
descent-override: 43.28%;
line-gap-override: 0.00%;
}
@font-face {
font-family: "Source Serif 4 Variable Fallback";
src: local("Times New Roman"), local("TimesNewRomanPSMT");
size-adjust: 117.91%;
ascent-override: 87.87%;
descent-override: 28.41%;
line-gap-override: 0.00%;
}
@font-face {
font-family: "JetBrains Mono Variable Fallback";
src: local("Courier New"), local("CourierNewPSMT");
size-adjust: 99.98%;
ascent-override: 102.02%;
descent-override: 30.00%;
line-gap-override: 0.00%;
}
24 changes: 12 additions & 12 deletions src/styles/fonts.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
font-style: normal;
font-display: swap;
font-weight: 100 900;
src: url(/fonts/fraunces-latin-ext-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/fraunces-latin-ext-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
Expand All @@ -17,7 +17,7 @@
font-style: normal;
font-display: swap;
font-weight: 100 900;
src: url(/fonts/fraunces-latin-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/fraunces-latin-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
Expand All @@ -26,7 +26,7 @@
font-style: normal;
font-display: swap;
font-weight: 100 900;
src: url(/fonts/inter-latin-ext-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/inter-latin-ext-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
Expand All @@ -35,7 +35,7 @@
font-style: normal;
font-display: swap;
font-weight: 100 900;
src: url(/fonts/inter-latin-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/inter-latin-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
Expand All @@ -44,7 +44,7 @@
font-style: normal;
font-display: swap;
font-weight: 100 800;
src: url(/fonts/jetbrains-mono-latin-ext-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/jetbrains-mono-latin-ext-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
Expand All @@ -53,7 +53,7 @@
font-style: normal;
font-display: swap;
font-weight: 100 800;
src: url(/fonts/jetbrains-mono-latin-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/jetbrains-mono-latin-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
Expand All @@ -62,7 +62,7 @@
font-style: normal;
font-display: swap;
font-weight: 200 900;
src: url(/fonts/source-sans-3-latin-ext-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/source-sans-3-latin-ext-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
Expand All @@ -71,7 +71,7 @@
font-style: normal;
font-display: swap;
font-weight: 200 900;
src: url(/fonts/source-sans-3-latin-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/source-sans-3-latin-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
Expand All @@ -80,7 +80,7 @@
font-style: normal;
font-display: swap;
font-weight: 200 900;
src: url(/fonts/source-serif-4-latin-ext-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/source-serif-4-latin-ext-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
Expand All @@ -89,7 +89,7 @@
font-style: normal;
font-display: swap;
font-weight: 200 900;
src: url(/fonts/source-serif-4-latin-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/source-serif-4-latin-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
Expand All @@ -98,7 +98,7 @@
font-style: normal;
font-display: swap;
font-weight: 300 700;
src: url(/fonts/space-grotesk-latin-ext-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/space-grotesk-latin-ext-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
}
Expand All @@ -107,7 +107,7 @@
font-style: normal;
font-display: swap;
font-weight: 300 700;
src: url(/fonts/space-grotesk-latin-wght-normal.woff2) format("woff2-variations");
src: url(/fonts/v1/space-grotesk-latin-wght-normal.woff2) format("woff2-variations");
unicode-range:
U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
1 change: 1 addition & 0 deletions src/styles/global.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/* Scan `src/` only: automatic detection may walk up the file system (docs/design/starter-references.md §6). */
@import "tailwindcss" source("..");
@import "./fonts.css";
@import "./font-fallbacks.css";

/*
* One file per feature (docs/engineering/code-structure.md §8), in cascade order. Unlayered on
Expand Down
Loading