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
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.