Tofu boxes: why the icons ship as ~6 KiB of font

The icons on this site are not images and they are not an icon library. They are Nerd Font glyphs — private-use code points such as U+F413 and U+F08C8, drawn in the same monospace font as the text.

That is a nice trick right up until you remember the obvious: no stock system font maps those code points. A visitor who does not happen to have a Nerd Font installed gets a tofu box — the hollow rectangle of a missing glyph — in front of every link in the navigation. That is the failure the in-house font exists to prevent.

The fix, and the version of it I did not want

The lazy fix is a <link> to a third-party font CDN. That is a runtime dependency on someone else’s uptime, one more supply-chain hop on a page whose whole argument is that you should be able to check things, and a reference that can stop resolving without a single commit in this repository to warn you.

So the font is served from this origin, from assets/fonts/:

• Upstream: ryanoasis/nerd-fonts, with the release tag pinned in tools/nerd-font-subset.py;
• Family: JetBrainsMono Nerd Font Mono, Regular and Bold;
• Subset: only the icon and graphic code points this repository actually uses;
• Size: roughly 6 KiB per weight;
• Licence: OFL.txt, verbatim from upstream — SIL Open Font License 1.1.

Six kilobytes is small enough to inline, which is a nice place to land: the page carries its own icons, so drawing one is a local file read — nothing about the glyphs depends on a host we do not control, and nothing changes under us when somebody else’s URL does.

The generated files are generated

tools/nerd-font-subset.py scans the repository for glyphs in the icon ranges — arrows, box drawing, block elements, geometric shapes, and the two Nerd Font private-use blocks — subsets the pinned upstream release down to exactly those glyphs, writes the two woff2 files, deletes the ones it superseded, and rewrites the generated @font-face block in assets/css/style.css in place.

Two details in that script are load-bearing:

• Latin text and general punctuation are deliberately not in the subset. Those code points keep falling through the font stack to Fira Code and then to the platform monospace font, exactly as they did before. Adding a 300 KiB text font to fix 6 KiB of icons would have been a different decision with a different cost.
• The file name embeds a content hash. A stylesheet is referenced with a version query, and the font file it points at is named after its own bytes, so a cached copy of an old stylesheet can never pin a stale subset. The generated files are committed together with the stylesheet change that references them.

The failure is silent, so there is a gate

This is the kind of bug that returns without warning. A missing glyph does not produce a 404 — the font loads fine, and then draws a box. A glyph dropped from the stylesheet’s coverage looks exactly like a glyph nobody ever wrote.

So coverage is asserted at build time, in all four CI jobs:

1. tools/icon-codepoints.txt records exactly which code-point spans the shipped subset covers.
2. tools/check-icon-coverage.rb re-scans the sources on every build and fails if the site uses a glyph the subset does not cover — or if style.css references a font file that is not in the repository.

The consequence is the property worth having: adding a new icon without regenerating the subset is a red build, not a tofu box in production. The mistake is now louder than the fix.

The same reasoning runs through the rest of the theme — colour is checked against declared tokens, so the palette cannot drift out of the dark/light switch either. See how the stack is built for the rest of the pipeline, and the audit page for the version of this argument that concerns signatures rather than glyphs.