docs: self-host fonts, eliminate layout shift, add SPA navigation

[tony]

Summary

Port documentation frontend improvements from tmuxp:

• docs(style): refine typography — headings, TOC, and body tmux-python/tmuxp#1021
• docs: self-host fonts, eliminate layout shift, add SPA navigation tmux-python/tmuxp#1022

Overhaul the docs frontend for faster, smoother page loads:

• Self-hosted fonts — IBM Plex Sans/Mono via Fontsource CDN with build-time download, caching, and preload to eliminate Flash of Unstyled Text (FOUT)
• Font fallback metrics — Capsize-derived size-adjust, ascent-override, descent-override on system fallbacks so text does not reflow when web fonts load
• Layout shift prevention — badge placeholder sizing and sidebar logo dimensions to eliminate Cumulative Layout Shift (CLS)
• SPA-like navigation — vanilla JS script (~170 lines, no deps) intercepts internal link clicks and swaps only the three DOM regions that change
• View Transitions API — smooth crossfade between pages during SPA navigation (instant swap on unsupported browsers)
• Typography refinements — kerning, ligatures, letter-spacing on body; optimizeSpeed on code blocks; Biome-inspired heading scale; wider TOC panel
• Sidebar visibility gate — prevent flash of active link state on initial load

See tmuxp PRs for full design rationale and test plan.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.24%. Comparing base (f268230) to head (5cab546).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #534   +/-   ##
=======================================
  Coverage   84.24%   84.24%           
=======================================
  Files          29       29           
  Lines        3795     3795           
  Branches      756      756           
=======================================
  Hits         3197     3197           
  Misses        378      378           
  Partials      220      220           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

Found 3 issues. Checked for bugs and CLAUDE.md compliance.

---

Issue 1 (score 90) — Bug: font_faces entries added to template even when download fails

vcspull/docs/_ext/sphinx_fonts.py

Lines 143 to 151 in e62ac30

	app.add_config_value("sphinx_font_css_variables", {}, "html")
	app.add_config_value("sphinx_font_preload", [], "html")
	app.connect("builder-inited", _on_builder_inited)
	app.connect("html-page-context", _on_html_page_context)
	return {
	"version": "1.0",
	"parallel_read_safe": True,
	"parallel_write_safe": True,
	}

font_faces.append(...) runs unconditionally — the return value of _download_font gates the shutil.copy2 but not the append. When a download fails, the @font-face CSS will still emit a src: URL pointing to a file that was never copied to _static/fonts/. With font-display: block, this blocks rendering waiting for a font that will 404.

The test test_on_builder_inited_download_failure asserts that a font_faces entry is created on failure (line 1197), which confirms this is the current behaviour, but it doesn't test that the built page functions without the file.

Fix: only append to font_faces when _download_font returns True, or at minimum change to font-display: swap for the failure path.

---

Issue 2 (score 85) — Temporary CI branch trigger left in workflow

vcspull/.github/workflows/docs.yml

Line 7 in e62ac30

- docs-fonts

The commit message for this line says "temporarily add docs-fonts branch to trigger". The branch is still listed in push.branches in the PR being merged. Once this lands on master, the entry is dead code that will never match and will confuse future contributors. It should be removed before merging, matching the pattern in the parent tmuxp PR which has a "Revert" commit.

---

Issue 3 (score 82) — Missing docstrings on _cache_dir and _cdn_url

vcspull/docs/_ext/sphinx_fonts.py

Lines 81 to 100 in e62ac30

	static_dir = pathlib.Path(app.outdir) / "_static"
	fonts_dir = static_dir / "fonts"
	fonts_dir.mkdir(parents=True, exist_ok=True)
	font_faces: list[dict[str, str]] = []
	for font in fonts:
	font_id = font["package"].split("/")[-1]
	version = font["version"]
	package = font["package"]
	subset = font.get("subset", "latin")
	for weight in font["weights"]:
	for style in font["styles"]:
	filename = f"{font_id}-{subset}-{weight}-{style}.woff2"
	cached = cache / filename
	url = _cdn_url(package, version, font_id, subset, weight, style)
	if _download_font(url, cached):
	shutil.copy2(cached, fonts_dir / filename)
	font_faces.append(
	{
	"family": font["family"],

Both functions lack docstrings. CLAUDE.md requires NumPy-style docstrings for all functions and methods. _cache_dir in particular has no docstring despite _make_app (in the test file) and SetupDict both having them. _cdn_url and _download_font also lack docstrings; _download_font at least has clear variable names but a one-liner summary would satisfy the convention.

🤖 Generated with Claude Code
_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}