A Calculus of Diagrams

Continuous relations are function-plot. Categorical and distributional data are one unified chart — bar, column, line, scatter, histogram, box-plot, pie, donut, combination, area, error-bar, bubble, stem — discriminated on a chartType. Relational structure is tree, node-graph, and pedigree; spatial structure is geometry (including curved solids), free-body, circuit, and ray-optics; symbolic structure is chem-structure; tabular data is table; sequence is timeline and number-line; and set relations are venn. A labelled apparatus is schematic-diagram — fully specified, never a raw drawing. Labels that bear mathematics — fractions, integral bounds, radicals, matrices — are typeset rather than approximated, to the standard a reader expects of set mathematics 13.

Because the union is closed and the renderer is exhaustive, the language has a useful property for an examination platform: it can only draw things it understands. There is no path by which a chemistry question produces a half-rendered physics diagram, because the type that would describe that diagram does not exist. The grammar is the safety property.

Determinism as a theorem

The renderer is a pure function. Given a specification, it computes the same SVG string every time — on every machine, in every process, forever. This is not an aspiration enforced by review; it is a structural invariant of the engine’s source. Nothing in the rendering path may read a clock, draw a random number, or touch the network, and every numeric coordinate is passed through a single quantiser before it reaches the output.

Write $\mathrm{render}$ for the compiler from specifications to SVG. The invariant is referential transparency 3:

The consequence is that a figure’s bytes are a function of its meaning alone. Two authors who write the same spec get the same picture down to the byte; a spec re-rendered a year later is unchanged; and — crucially — the stored picture can be checked against the spec at any time by simply rendering again and comparing. Determinism is what turns "is this figure correct?" from a matter of opinion into a matter of equality.

The quantiser earns particular mention. Floating-point arithmetic is associative on paper but not in silicon; a coordinate computed two equivalent ways can differ in its last bit and so in its rendered text. Routing every number through one formatter collapses that nondeterminism, so the equality above holds across platforms rather than merely within one — the same discipline that lets a build be reproducible bit-for-bit 5.

Emphasis by form, not colour

A good diagram answers a question, and most questions are about one element: the extremum, the equilibrium bar, the true-positive branch, the dominant share. The engine carries a single channel — emphasis — to mark that element. What it does not do is reach for colour.

Early versions used a per-curriculum accent hue. We retired it. The accent axis is now collapsed onto ink: the emphasised element is rendered filled and heavier, its context kept open and light, and that is the whole of it. The reasons are not aesthetic preference but obligation. Meaning carried by colour vanishes in greyscale print, in a photocopied past paper, and for the colour-blind reader 11; meaning carried by form — fill, weight, openness — survives all three 79. A figure that must remain legible in an examination hall cannot stake its one important fact on a hue. Emphasis is therefore one bit of form per element, and the engine is built so that a figure with no emphasis is byte-identical to the same figure before the channel existed.

This is a restraint, not a limitation: a diagram whose content genuinely is colour — a spectrum, a labelled physical field — may still use it. What the engine forbids is using colour to smuggle in importance that form should carry — restraint in the direct service of the data 8.

One specification, two surfaces

The platform is read on a light page and, increasingly, on a dark one. A figure must be at home on both without being drawn twice.

The renderer takes a surface argument and resolves a theme — concrete ink, paper, and hairline values for light or dark — before it emits a single mark. One specification therefore denotes two faithful pictures, and neither is a recolouring hack applied after the fact: each is computed from the same value against a different resolved palette. The light rendering is canonical; it is the one whose bytes the verification regime checks, so the dark surface is a true second view of a single source rather than a second artefact to maintain. Each rendering also carries a data-bearing, localised text description for assistive technology 10, so the diagram is legible to a reader who cannot see it at all.

Verification — the byte-exact contract

Determinism is only useful if something exercises it. Two gates do. They re-render every stored figure from its specification and assert that the bytes already on disk are exactly what the renderer now produces:

If a drawing constant changes, the gates go red until every dependent figure has been re-rendered and its stored bytes updated in the same change — together with a set of golden fixtures that pin the exact output of representative specs 12. The effect is that the question "did this edit quietly alter a diagram?" is answered mechanically, for the whole corpus, on every commit. A picture cannot drift away from its meaning without the build noticing.

Sanitisation is the second, security-facing half of the same contract. Because a specification may originate from a model, the rendered SVG is treated as untrusted until it has passed a strict allow-list 4; validation rejects the raw-SVG escape hatch outright, so there is no route by which an unchecked string of markup reaches a reader. Honesty and safety are enforced at the same boundary.

A corpus, migrated

A formalism is only as good as the artefacts it can actually carry. The engine now backs the entire question banks of two national examinations — the Austrian Matura and the German Abitur — comprising on the order of 1,800 specification-backed figures.

Much of that corpus did not begin as specifications. It began as hand-drawn one-off SVGs, each a frozen picture of exactly the kind this essay argues against. We migrated them: read each drawing and its question, recover the meaning, and re-express it as a typed spec that the engine then renders. Roughly three-quarters of the figures converted cleanly. The residue — staff notation, freehand maps, political cartoons, reproductions of artworks — was left exactly as it was and labelled as such. The engine is colour- and form-capable, but it is not a substitute for a painting, and forcing a cartoon into a node-graph would have destroyed the very meaning the question tested. The honest move is to migrate what a kind can faithfully denote and to leave the rest visibly alone.

The migration pays a compounding dividend. Because every migrated figure is now a value rather than a picture, a future improvement to the engine — a better label-placement rule, a new accessibility feature, a restyle — propagates to the whole library by re-rendering, not by re-drawing thousands of files by hand. We set the data once; the engine restyles the corpus on command. That is the practical meaning of treating diagrams as a language: maintenance becomes a single edit, and correctness becomes a single equation.

Coda

None of this is visible to the student, and that is the point. They see a clean diagram that answers their question, the same on paper and screen, legible in greyscale, identical to the one their classmate sees. What they do not see is the machinery that makes the diagram unable to lie — the type that constrains it, the function that compiles it, the equation that checks it. A figure engine, done properly, is not a drawing tool. It is a small proof system, and every picture it ships is a theorem it has already verified.