docs(book): restyle the book, especially in dark mode

[alchemydc]

Motivation

mdBook selects a theme from prefers-color-scheme, so anyone on system dark lands on the stock navy theme: #bcbdd0 body text on hsl(226, 23%, 11%), a #282d3f sidebar, #2b79a2 links. Past the palette, three things were structurally broken on a dark page — Mermaid diagrams always rendered in Mermaid's light theme, service-dependencies.svg was inverted with a bare filter: invert(1) that rotates every hue to its complement, and the screenshots under book/src/user/ glared against the background.

This is look-and-feel only. No prose, no SUMMARY.md, no restructuring — content is a separate pass.

Solution

The palette comes from Zebra's own mark (book/theme/favicon.png): gold #cf8c2a on black and white. It is lifted to #E0A340 on dark and darkened to #8A5A12 on light so both clear 4.5:1 against their ground. The dark ground is a neutral #0E1014 rather than navy blue.

Only light and navy are restyled — the two themes prefers-color-scheme actually selects. coal, ayu and rust are left stock so the theme picker still offers unmodified alternatives, and book.toml now pins default-theme / preferred-dark-theme to the two we cover.

Everything goes through mdBook's first-class override slots. index.hbs, book.js, general.css and chrome.css are not forked, so mdBook upgrades stay drop-in.

• book/theme/css/custom.css — full variable override for both themes plus the no-JS dark case, then typography, sidebar, code blocks, tables, GFM alerts, menu bar, focus rings and a print reset.
• book/theme/fonts/ — IBM Plex Sans (variable) and Plex Mono, self-hosted. This replaces mdBook's bundled Open Sans and Source Code Pro rather than adding to them: 6 woff2 at 225K total, against the 11 files mdBook shipped, so page weight goes slightly down. No font CDN is contacted, matching the privacy posture already set by book/lens-init.js.
• book/theme/highlight.css, book/theme/tomorrow-night.css — syntax themes tuned to the palette.
• book/mermaid-init.js — reads the theme class, renders in a matching palette, and re-renders from stashed source on theme switch (mdBook emits no theme-change event, so it uses a MutationObserver).

Notes for review

Stacked on #11390. Base is docs/knowledgelens-widget, not main. The two #lens-opt-in rules from that PR are carried forward here, restyled to the new tokens. Retarget to main once #11390 merges.

The logotype. book/src/README.md pulls a transparent PNG drawn for a white page — black wordmark, white stripes, gold roundel — which simply disappears on a dark ground. It now gets invert(1) hue-rotate(180deg) saturate(1.6) brightness(1.15): the invert whitens the wordmark, the hue-rotate stops the roundel going blue, and the saturate/brightness pair pulls the gold back to roughly brand after the round trip. The tradeoff is that this is a photographic negative, so the zebra head's stripes swap inside the roundel. The clean fix is a white-ink variant of the logotype hosted alongside the black one, which is a brand asset request rather than something to invent here.

No dependency bumps. book/mermaid.min.js is still the 8.13.10 bundle vendored in a3eed2daa (2022-05-09); mdbook-mermaid 0.17.1 would ship 11.6.0. That is deliberately a separate PR — three majors of breaking changes need the two diagrams re-verified, and a 2.7MB vendored blob swap is a different review from a theme diff. mermaid-init.js already prefers mermaid.run() with an init() fallback, so the bump won't need to touch the theme. Note for whoever does it: mdbook-mermaid install book overwrites mermaid-init.js, and the theme-aware version has to be restored afterward.

Known, not fixed here. Diagrams render undersized in a large frame — that is a Mermaid 8 sizing artifact and clears with the bump above. book/src/user/openapi1-3.png are referenced from nothing and look orphaned; left alone as a content-pass question.

No changelog fragment, consistent with previous book-only commits such as a3b770717.

Test evidence

mdbook build book succeeds on mdBook 0.5.4. Smoke-tested by hand in Chromium at 1440x1000 in both light and dark, and by the author in their own browser.

Pages walked, both themes: index.html (logotype, shields.io badges must stay unframed, h1), user/docker.html (long fenced blocks, copy button, inline code), user/elasticsearch.html and user/metrics.html (screenshots), dev/tokio-console.html (raw <img> from a remote host), dev/diagrams/mempool-architecture.html (Mermaid, including a live theme toggle mid-page), dev/overview.html (service-dependencies.svg hues), dev/crate-owners.html (wide table scroll).

Also confirmed: no console or page errors in either scheme; all six font files resolve through mdBook's {{ resource }} hashing; no requests to fonts.googleapis.com or fonts.gstatic.com; git status clean outside book/.

Contrast was computed by hand while choosing values rather than measured with a tool — body text ~15:1 on dark, accent ~8.6:1 dark and ~5.7:1 light, muted ~6:1. Worth an independent check if that matters for review.

AI disclosure

Written with Claude Code (Opus 5). Scope: the full change — palette and type selection, custom.css, the two syntax themes, mermaid-init.js, font vendoring, and this description. Reviewed and smoke-tested by me; I am the responsible author.

[v12-auditor]

Note

Complete: Audit complete. V12 did not find any issues that need review.

Open the full results here.

Analyzed one file, diff c1243f3...2074d5f.