Files
Greg ShuflinandClaude Opus 5.5 79128766f5 ADR 0024: a weight per role, with the comparison behind it
Records the weight table and why chrome stops at SemiBold, adds
design/typeface-specimen/gen_weights.py (the Bold vs SemiBold comparison
on both grounds), notes the rule in AGENTS.md, and closes the TODO.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M7mmwecHbwdt5UY7nMBqod
2026-11-16 01:24:39 -08:00
..
2026-08-09 02:37:14 -07:00

Typeface specimen builder

Builds a single self-contained HTML page comparing candidate typefaces on this project's actual content — hex digests at UI sizes, Rust in the app's syntax colors, mixed Japanese/English prose, and a monospace-grid alignment test — on the real theme.rs palette. Every face is subset and embedded as a data URI, so the page renders the actual font rather than silently falling back.

This is the tool that produced the comparison behind ADR 0024. Reach for it when reconsidering a typeface, not for anything the app ships.

Running it

Everything runs under a throwaway nix shell; nothing needs to be installed.

cd design/typeface-specimen
nix shell --impure --expr 'let p = builtins.getFlake "nixpkgs"; pkgs = p.legacyPackages.x86_64-linux; in pkgs.python3.withPackages (ps: [ ps.fonttools ps.brotli ps.zopfli ])' \
  --command python3 gen_page.py

Downloads land in .work/ (gitignored) and the page is written to .work/typography-specimen.html. Set SPECIMEN_WORK to point somewhere else, e.g. at an existing download cache.

gen_page.py expects the font archives to already be extracted under $SPECIMEN_WORK/fonts in the layout its FONT_FILES table names. Fetching them is the same set of canonical release URLs scripts/vendor-fonts.sh uses — the quickest path to a fresh cache is to crib the curl/unzip lines from there.

The notes specimen

gen_notes_page.py answers a narrower question than gen_page.py: what a markdown note should be set in, in the Notes editor and its preview. It renders one real note in every candidate — styled markdown source on the left, the rendered preview on the right, on the app's palette — beside a row showing the app today and one showing what Joplin draws on this machine (Liberation Sans, where its Arial-ending default stack lands). Size, line height, editor theme and reading surface are live controls, and "match x-height" scales each face to the reference's lowercase height so a face is judged apart from its apparent size.

It needs only fonttools and brotli (the same nix shell as above works), and fetches the Google faces itself from fontsource at pinned versions into .work/notes-fonts/. Output: .work/notes-specimen.html.

python3 gen_notes_page.py

To add a candidate, add a row to its FACES; the metrics on each card are measured from the font, not typed in.

Adding a candidate

Add a row to FONT_FILES (family name → path) and an entry to whichever of MONOS / SANSES / PROSE it belongs in. The per-card metrics are typed in by hand, so measure first (below) rather than guessing.

The weight comparison

gen_weights.py is a narrower question again: which weight the chrome's emphasis takes. It draws the same pieces of chrome — onboarding title, screen heading, dialog title, a tab bar, a section label, a player title, a breadcrumb, an error banner — with Bold wherever the desktop used it, and with SemiBold as the ceiling, on both themes' window grounds. It reads Inter from assets/fonts/, so it is the vendored face, and needs only Pillow (ps.pillow in the nix shell above). Output: .work/weights.png. ADR 0024's weight table came from it.

python3 gen_weights.py

The analysis scripts

Standalone; each takes font paths as arguments and runs under the same nix shell. These are what the ADR's numbers came from.

Script Answers
fontinfo.py upem, x-height/em, cap-height/em, monospace-or-not, Latin advance, CJK:Latin ratio, glyph count, coverage of a probe set
cov.py Which of the 80 commonest kanji, the full kana set, and CJK punctuation a font is missing
cmapchk.py Enumerates every cmap subtable — use when a coverage result looks wrong, since a font can map a codepoint in one subtable and not another
names.py Family name (ID 1) vs typographic family (ID 16), weight class, and ratio for everything in assets/fonts/

names.py is the one to re-run after changing vendor-fonts.sh: gpui resolves faces by typographic family, so that column has to match the constants in rust/gui-app/src/typeface.rs or the lookup silently falls back.

Two traps worth knowing

Subset from the page, never from a hand-written string. An earlier version listed the characters by hand and drifted from the specimen copy; う was missing from the Noto Serif subset, so it fell through to the browser's default Japanese font and looked exactly like a flaw in the typeface being judged. gen_page.py now derives the character set from the finished page plus the complete kana and CJK-punctuation blocks.

Variable fonts are fine here, not in the app. The browser interpolates them happily, so the specimen can use them; gpui cannot (see ADR 0024). Don't let a face that looked good here get vendored as a variable font.