feat: add a san-francisco-font feature

[ashwin153]

Softlight Overview

UX Score: 5/5

Softlight reviewed this change and found no issues.

To run Softlight again, click here or comment @softlight.

Installs Apple's San Francisco fonts and makes fontconfig answer the system font names with them, so Chromium renders pages the way macOS does instead of falling back to Liberation Sans.

What it installs

• SF Pro and SF Mono under /usr/local/share/fonts/san-francisco, root-owned and read-only to the remote user.
• /etc/fonts/conf.avail/59-san-francisco.conf, symlinked into conf.d so the substitution can be turned off without uninstalling the fonts.

SF Pro goes in as the variable pair (SF-Pro.ttf, SF-Pro-Italic.ttf), not the 44 static instances sitting beside them in the same download. One pair carries every weight from Ultralight to Black and every width from Compressed to Expanded, and its optical size axis is what makes text pick up the Display drawing at headline sizes and the Text drawing at body sizes the way it does on macOS. It is 40MB against 270MB for the same coverage; the image layer ends up ~41MB.

Apple ships each family as a disk image holding an installer package whose payload is a gzipped cpio archive. The build unpacks all three layers with 7-Zip, using include filters so the payload is never expanded in full, then purges the archiver again if the feature is what pulled it in.

The part that isn't obvious

Chromium never asks fontconfig for sans-serif. It resolves the CSS generic against its own default font preference — on Linux, the literal string Arial — and asks fontconfig for that. So aliasing the generic alone changes nothing a page can see:

request	rules for sans-serif only	with webSafeSans (default)
fc-match sans-serif	SF Pro	SF Pro
Chromium font-family: sans-serif	Liberation Sans	SF Pro

That is why webSafeSans is on by default and routes Arial, Helvetica, Helvetica Neue, Segoe UI and Roboto to SF Pro. The cost is that a page explicitly asking for Arial gets San Francisco too — there is no signal in what reaches fontconfig that separates Chromium's generic from a page's deliberate Arial. monospace needs no equivalent, because Chromium's default fixed font is Monospace, which fontconfig already treats as the generic.

Two smaller findings, both written up in NOTES.md:

• The file is numbered 59 to land before 60-latin.conf. Both files put their preference in front of the generic name rather than at the head of the list, so between two preferences for sans-serif the one read first wins — the opposite of the usual "last config wins".
• Arial and Helvetica already resolve, strongly, through 30-metric-aliases.conf. A weak <prefer> loses to that, so those two take the head of the family list with a matching binding instead. Everything else uses a weak preference, so a page naming a font the image actually has still gets that font.

Serifs are left alone: serif, Times New Roman, Georgia and Courier New resolve to whatever the image had, as does a page with no font-family at all.

Verification

Run against the real Chromium the playwright feature installs (measuring rendered text widths per family, since fontconfig agreeing is necessary but not sufficient):

sans-serif          => SF Pro          Arial               => SF Pro
system-ui           => SF Pro          Helvetica           => SF Pro
-apple-system       => SF Pro          "Segoe UI"          => SF Pro
BlinkMacSystemFont  => SF Pro          Roboto              => SF Pro
monospace           => SF Mono         serif               => Liberation Serif
ui-monospace        => SF Mono         "Times New Roman"   => Liberation Serif

install.sh was also run end to end on a clean host in all three option combinations, including the archiver install-and-purge path and a re-run over an existing install.

Three test scenarios: the default, mono: false + webSafeSans: false, and one alongside the playwright feature that drives headless Chromium and asserts the generics actually render as San Francisco. That last check was confirmed to fail when the fontconfig rules are removed, so it is testing something.

Licensing

These are Apple's fonts under Apple's licence, which allows use in designing and developing software but not redistribution. The feature fetches them from Apple's CDN at build time for that reason — nothing is vendored into this repository. Worth a look before the built image goes anywhere outside the team.

The download URL has no version in it and no published checksum, so there is nothing to pin; a rebuild picks up whatever Apple is shipping that day. The install fails loudly rather than half-installing if a face it expects is no longer in the download.

---

Generated by Claude Code

---

Note

Medium Risk
Build-time fetches unpinned Apple font URLs (layout/content can change), installs licensed fonts only at build time, and globally changes fontconfig resolution—including overriding common web fonts when webSafeSans is enabled.

Overview
Adds a new san-francisco-font devcontainer feature that downloads Apple's SF Pro (and optionally SF Mono) at image build time, installs the variable font pair under /usr/local/share/fonts/san-francisco, and writes 59-san-francisco.conf so fontconfig maps system/CSS font names to San Francisco.

install.sh pulls from Apple's CDN via curl, unpacks DMG → pkg → gzipped cpio with 7-Zip (installed only if needed, then purged), fails the build if expected faces are missing, and generates fontconfig rules using weak prefer aliases plus strong override matches when webSafeSans is on (default)—so Chromium's Linux default of Arial for sans-serif actually renders SF Pro, not just fc-match sans-serif. mono (default on) controls SF Mono install and monospace-related aliases; serifs are intentionally untouched.

Ships devcontainer-feature.json with those two boolean options, README.md / NOTES.md, and tests: default Ubuntu scenario (fc-match + permissions + archiver cleanup), mono: false / webSafeSans: false, and a Playwright Chromium headless canvas width probe to verify rendered generics match SF Pro/SF Mono.

^{Reviewed by Cursor Bugbot for commit 217769e. Configure here.}

[ashwin153]

Correcting one paragraph of the description above, which no longer matches the code. It says:

The build unpacks all three layers with 7-Zip, using include filters so the payload is never expanded in full

Both halves of that are now wrong, and the reason is worth recording since it's the bug the feature test caught.

The depth is not three, and it is not fixed. How deep the fonts sit depends on the 7-Zip build. 7-Zip 23, which Ubuntu 24.04 ships and which I developed against, unwraps the payload's gzip and cpio together while extracting the installer package. 7-Zip 26, on the Ubuntu 26.04 base image this repo tests on, stops at the gzip stream and needs a fourth pass — so the extraction aimed at the cpio was aimed at a gzip wrapper instead.

The include filters are gone, and they are why it failed quietly rather than loudly. That last extraction passed filters naming the faces to keep. No entry at that layer matched them, so 7-Zip extracted nothing, created no output directory, and exited 0 — surfacing three lines later as no font matching SF-Pro.ttf ... apple changed the font set, which pointed at Apple rather than at the nesting. Their only benefit was scratch space inside a build layer that is discarded anyway, against a failure mode invisible until the nesting shifts. Not a good trade.

install.sh now extracts one layer at a time and stops at the first one holding font files, which covers both versions. Verified end to end against 7-Zip 23.01 and 26.00 — 14 files, 41MB, identical fontconfig resolution and a passing Chromium render probe on each.

NOTES.md in the diff carries this; the stale wording is only in the description, which matters if the squash message is taken from it.

Everything else in the description still holds, including the webSafeSans reasoning and the ~41MB image cost.

---

Generated by Claude Code