dj.Diagram theme: make the font configurable

[dimitri-yatsenko]

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.

[dimitri-yatsenko]

Revising item 2. I suggested reconciling the tier fills toward the brand palette; on reflection that's the wrong default, and I'd withdraw it. Item 1 (configurable fontname) stands unchanged.

The reasoning, briefly: the two palettes are solving different problems. A brand palette maximizes recognition on marketing surfaces. A notation palette maximizes five-way categorical discrimination under adverse conditions — projector washout, grayscale printing, color-vision deficiency. No single palette is optimal for both, and where they conflict the notation's job should win, because the diagram's purpose is to be read correctly.

Three specifics:

• Brand systems are structurally too small for five categories. One or two primaries plus neutrals is the usual shape; five perceptually distinct hues plus a light/dark pair is a larger demand. Forcing it yields near-neighbours — in the brand-produced version, Computed shifts from red toward peach and lands closer to the Manual/Lookup end of the range. Less discriminable, more on-brand.
• Uniform stroke is a real regression, not a style preference. Carrying tier in fill alone removes the redundant encoding channel that keeps tiers apart in grayscale and for color-vision-deficient readers.
• Most dj.Diagram output isn't ours. It renders in users' notebooks, papers, and theses, describing their pipelines. A brand palette as the library default puts DataJoint's marketing identity into figures that aren't marketing.

The useful generalization: brand should govern what carries no meaning; notation should govern what does.

Carries meaning — notation owns	Carries no meaning — brand-safe
the five tier hues · per-tier stroke · node shape · line weight and dash · the underline	typography · frame · background · corner radius · shadow

Typography lands squarely in the right-hand column, which is why item 1 is uncontroversial: Roboto encodes nothing.

If a fully brand-skinned diagram is ever wanted for marketing surfaces, the mechanism should be an additional named theme — theme="brand" alongside light and dark — rather than a change to the defaults. That gives marketing what it needs on the surfaces it owns, and nothing changes underneath users who generate diagrams about their own schemas.

One honest note in the other direction, since it argues against me: I had assumed changing the palette now would churn an installed base. It wouldn't. datajoint-docs #248 (24 regenerated notebooks) is still open and only one committed figure in the docs tree uses these values, so the modernized theme has barely propagated — this is the cheapest moment a palette change will ever be. That removes "too expensive to change" as a defense. The defense is that the current palette is better suited to the job.

[dimitri-yatsenko]

Narrowed this issue to the fontname half. The palette half was split into #1543 and shipped in 2.3.3 (#1544).

Worth recording how it landed, because the outcome differs from what this issue proposed:

• Per-tier strokes were kept, as argued for above — the accessibility reasoning held. The brand-produced version's uniform navy #171C39 stroke was not adopted for tiers; navy is used for edges, cluster frames and titles instead.
• Brand fills were adopted, but not the exact values tabled above. Released light palette (fill / stroke / text): Manual #E8F0E9 / #3E7A52 / #28513A, Lookup #F0F0F1 / #808285 / #5A5C5F, Imported #E0F4FC / #00A0DF / #00537A, Computed #FFEDE5 / #FF5113 / #B23200, Part #FFFFFF / #B9BBBE / #55585C.
• Computed is now brand orange #FF5113, resolving the "peach vs. red/pink" divergence.
• The accent cyan #00A0DF is no longer unused — it is the Imported stroke.
• Renamed-FK edges are amber #C77D3A, deliberately duller than the Computed orange so a renamed edge landing on a Computed node doesn't read as the same signal.

The #55585C Part text is a deliberate one-step deviation from Lookup's #5A5C5F, so that every light color maps to exactly one role for the adaptive dark-mode block — visually identical, and noted in a code comment.

[dimitri-yatsenko]

Superseded by the amended issue body (2026-09-10). The correction below is now folded into the Motivation section, and the private-repo links it carried are replaced with the substance stated inline.

Keeping the record of what was wrong: this issue originally described the brand as "Roboto (body) / Roboto Slab (headings)", which is the reverse of the ratified assignment. Titles and headings are Roboto 400; body and paragraphs are Roboto Slab 300; monospace is Source Code Pro 400. So for a fontname theme key, the brand-aligned value for node and cluster labels — body-tier text, not headings — is Roboto Slab.

Whether Roboto Slab 300 is the right weight for a diagram label is a separate open question on the brand side, since the weight is specified against continuous prose.