Repository navigation
dj.Diagram theme: make the font configurable #1539
Description
Activity
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.Diagramoutput 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"alongsidelightanddark— 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.- changed the title
[-]dj.Diagram theme: make the font configurable, and reconcile the tier palette with DataJoint brand colors[/-][+]dj.Diagram theme: make the font configurable[/+]on Sep 9, 2026 Narrowed this issue to the
fontnamehalf. 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
#171C39stroke 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
#00A0DFis 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
#55585CPart 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.- Per-tier strokes were kept, as argued for above — the accessibility reasoning held. The brand-produced version's uniform navy
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
fontnametheme 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.
Surfaced by putting a
dj.Diagramfigure through a brand review, where the generated diagram is published in a blog essay. Insrc/datajoint/diagram.py; it would improve every DataJoint diagram, which is why it belongs here rather than in a post-process downstream.fontnameis hardcodedTwo hardcoded sites, so a caller who wants a different typeface has no way to ask for it. Proposal: add
fontnameto_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
Helveticasites 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
fontnamethe 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:
fontnameaffects layout. It is correct only where the caller controls the rendering environment and knows the face is installed.font-familystack 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
fontnamedefault 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 forSample, 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
fontnameallows.