dj.Diagram theme: make the font configurable

從 src/datajoint/diagram.py 開始，定位目前使用 Helvetica 的兩個位置，並檢查最近重寫 diagram 後的 _DIAGRAM_THEMES。新增 opt-in theme 設定，同時預設保留 Helvetica，確保兩個位置都使用該設定，並驗證沒有 override 的 diagram 保留現有版面配置；更新字型指南，說明明確的 opt-in 以及版面配置注意事項。

Narrowed 2026-09-09. This issue originally carried two theme gaps. The second — reconciling the tier palette with the brand palette — was split into #1543 and shipped in 2.3.3 via #1544. Only the fontname half below remains open. See the closing note for what was decided on the palette.

Amended 2026-09-10. The motivation below originally stated the brand typefaces the wrong way round, and proposed the theme key without acknowledging that diagram themes deliberately do not carry fonts. Both are corrected in place.

Surfaced by putting a dj.Diagram figure through a brand review, where the generated diagram is published in a blog essay. In src/datajoint/diagram.py; it would improve every DataJoint diagram, which is why it belongs here rather than in a post-process downstream.

fontname is hardcoded

node.set_fontname("Helvetica")                      # ~line 1596
fontname="Helvetica",  # schema label in a sans font  ~line 1696

Two hardcoded sites, so a caller who wants a different typeface has no way to ask for it. Proposal: add fontname to _DIAGRAM_THEMES, defaulting to "Helvetica", and read it at both sites. Small and mechanical, and no behavior changes for anyone who does not set it.

Note the line numbers above predate the 2.3.3 diagram work (#1534, #1544, #1545), which rewrote much of this file — locate the two Helvetica sites rather than trusting them.

Why the default has to stay Helvetica

Graphviz sizes node boxes using the face it actually finds on the machine doing the rendering. A fontname the environment lacks does not fall back gracefully: it changes text metrics, and therefore node dimensions and layout. That is why the shipped themes change colors only, never fonts, and why this proposal is opt-in rather than a new default.

It also means the two mechanisms are not interchangeable:

• Setting fontname affects layout. It is correct only where the caller controls the rendering environment and knows the face is installed.
• Restyling the emitted SVG — applying a CSS font-family stack to an inlined SVG — is display-only and cannot disturb layout, provided the substitute is metrically close to Helvetica. For DataJoint-controlled surfaces publishing a figure, this remains the safer route, and it is what docs and published figures use today.

So this issue asks for a caller-controlled escape hatch, not a replacement for SVG restyling. If the theme key lands, the guidance that themes do not change fonts needs amending to say "except by explicit opt-in, with the layout caveat above."

Motivation

DataJoint brand typography assigns Roboto to titles and headings, Roboto Slab to body and paragraphs, and Source Code Pro to code. Diagram node and cluster labels are body-tier text rather than headings, so a brand-aligned caller would set Roboto Slab — not Roboto. Whether Roboto Slab is the right weight for a short label inside a shape is a separate question: the weight is specified against continuous prose, and a diagram label is neither prose nor a heading.

Stating this because the earlier text had the two faces reversed, and a fontname default chosen from it would have pointed at the wrong face.

Not proposed

Per-table icons appear in hand-designed versions of the same figure (a person for Subject, a test tube for Sample, and so on). They read well, but nothing in a schema derives them — they would need a hand-maintained table→icon map, which reintroduces exactly the drift that generating the figure exists to prevent. Better left to hand-made cover art.

Monospace labels. Table names are code identifiers, but diagram text is proportional by design: a docs diagram should look like the one the reader just generated locally. Source Code Pro does not belong in a diagram, whatever fontname allows.