mesh-catalog/modules/fonts/README.md

fonts

The faces the workstations draw text with, as a module (novox/hq research 026/04, to-be 42 phase 2 step 1). Assigned to the two workstations.

Owns

what	where	class (ADR 0182)
JetBrains Mono Nerd Font, for monospace: terminal, window manager, bar, launcher, prompt	package ttf-jetbrains-mono-nerd	package
Inter, for the interface: GTK, Qt, notifications	package inter-font	package
Nerd Fonts Symbols, the icon fallback for any face	package ttf-nerd-fonts-symbols	package
Noto, for serif and every other script	package noto-fonts	package
Noto Color Emoji	package noto-fonts-emoji	package
what monospace, sans-serif, system-ui, serif and emoji mean	~/.config/fontconfig/conf.d/50-mesh-fonts.conf	owned, whole

All five packages are in the distribution's official repositories.

Why the account's fontconfig directory, not /etc/fonts/conf.d. The choice of faces is the operator's taste on the operator's machine, and every program that draws for the operator runs as the account. The account's directory is read by fontconfig's stock 50-user.conf, before the distribution's 60-latin.conf, so the module's file decides the generic families without touching anything the distribution owns. Root's tools and any other account keep the distribution's defaults. A system file would need a symlink into conf.d the way the distribution does it, which the mesh never makes (ADR 0012).

The file in short. Each generic family prefers the decided face, bound same as the request. Measured with fontconfig 2.18 on a workstation: a face added with the default (weak) binding loses to Noto Sans Mono for a plain monospace request, because the distribution's own rule decides first. The Nerd Fonts symbols and the colour emoji are appended last to every pattern, so an icon or emoji a face lacks is still drawn, and they never displace a face that has the character.

Improves

• Every program agrees on monospace. Today monospace is Noto Sans Mono, while the terminal, the window manager and the bar use a hand-copied Hack. After the push, all of them can say the family and get one face.
• Configurations naming a font that is not installed stop falling back to a proportional face. The launcher's theme asks for Iosevka Nerd Font and its power menu for JetBrains Mono Nerd Font. Neither is installed on the laptop, so fontconfig falls back to sans-serif. The file maps Hack Nerd Font, MesloLGS NF and Iosevka Nerd Font to monospace and the old JetBrains name to the new one, for as long as those families are not installed. Where one still is, it is used as before.
• Packages instead of copies. The hand-copied files can go (below), and an upgrade of a face is a package upgrade.

Tools

All answer JSON; (r) reads, (a) acts.

tool	what
fonts_families (r)	installed families: styles, file count, monospaced or not, and source (package, account for a hand copy, other)
fonts_match (r)	what each generic family resolves to, beside the decided face, with all_as_decided; or any patterns given
fonts_glyph (r)	which installed families have a character (given as itself or U+F120), and which face monospace and sans-serif draw it with
fonts_sources (r)	every hand-copied font file with its family, duplicates, and whether a package now provides the family; marks each remove with the reasons; lists packaged families with their package. Removes nothing
fonts_config (r)	whether the module's file is in place and loaded by fontconfig, and the account's other fontconfig files beside it
fonts_cache_rebuild (a)	rebuild the account's font cache, or with system: true the system's (through sudo -n)

The one-off steps for the operator (ADR 0182)

The mesh removes nothing it did not place. After the first push that assigns this module, on each workstation:

1. Remove the hand-copied files in ~/.local/share/fonts that fonts_sources marks remove, then run fonts_cache_rebuild. Measured on 2026-10-04:
   • laptop: the four HackNerdFont-*.ttf; the four MesloLGS NF *.ttf; the four MesloLGS%20NF%20*.ttf, which are the same bytes under URL-encoded names. Twelve files, 30 MB. Nothing stays.
   • desktop: the same twelve, plus Iosevka-Nerd-Font-Complete.ttf and JetBrains-Mono-Nerd-Font-Complete.ttf (version-2 Nerd builds). GrapeNuts-Regular.ttf and Icomoon-Feather.ttf came from a theme's repository. They are kept until the theme module decides what it ships.
   • Do this after the modules below name the new family, or the terminal and the bar fall back through the file's aliases to monospace, which is the right face anyway.
2. Nothing else. No fontconfig file of the account's own exists today on either workstation.

Modules that must name the family

Fonts are not a seat (research 026/04): this module says what the generic families mean, and each desktop module names its family. Each switches to JetBrainsMono Nerd Font when it is written:

module	today, on both workstations
xterm	~/.Xresources.d/xterm: *faceName: Hack Nerd Font
i3	~/.config/i3/config: font pango: Hack Nerd Font 11, three times (the window manager and both bars)
the bar (i3status-rust)	takes the font i3's bar block names, above
rofi	theme.rasi: Iosevka Nerd Font 10; powermenu.rasi: JetBrains Mono Nerd Font 10 and Hack Nerd Font bold 32
dunst	font = Hack Nerd Font 10, which becomes Inter (the interface face)
the prompt (powerlevel10k)	nothing: it uses whichever Nerd Font the terminal has

The DPI fixed in an X resource is the display server's setting (issue 168), not this module's.

Leaves as found

• noto-fonts-cjk and noto-fonts-extra, installed on both workstations, and every other font package. The module does not remove a package it did not install.
• The distribution's fontconfig files under /etc/fonts.
• The theme's two fonts on the desktop, above.