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.