typograph

Full documentation →

typograph is a neutral diagram engine for Typst: nodes, edges, Bézier
curve controls, wire clipping to true silhouettes, ports, reusable
fragments, and layered style resolution — with no built-in visual language
of its own. No CeTZ, no LaTeX/TikZ dependency.

It has no opinion about what a node should look like. A document supplies
that itself through per-call style: dictionaries, or through a theme —
see typograph-zx for
ZX-calculus notation and
typograph-circuit for
quantum-circuit and continuous-variable circuit notation. Both are built
entirely on this package's public API.

Install and import

#import "@preview/typograph:0.3.0" as typ

Quick start

Diagram coordinates use the mathematical convention: x increases to the
right, y increases upward.

#typ.diagram({
  let a = typ.node(0, 0, label: [A], style: (
    shape: typ.shapes.circle, shape-labelled: typ.shapes.stadium,
    fill: aqua.lighten(70%), stroke: 0.6pt + teal, min-size: 12pt, inset: 4pt,
  ))
  let b = typ.node(1, 0, label: [B], style: (
    shape: typ.shapes.circle, shape-labelled: typ.shapes.stadium,
    fill: aqua.lighten(70%), stroke: 0.6pt + teal, min-size: 12pt, inset: 4pt,
  ))
  typ.edge(a, b)
  typ.edge(a, (-1, 0))
  typ.edge(b, (2, 0))
})

An edge automatically contributes the nodes at its endpoints. See the
full documentation for the
complete guide: drawing nodes and edges, shape builders, curve controls and
waypoints, writing a theme, configuration, fragments, and the exhaustive
API reference.

Relative node and label placement

#typ.diagram({
  let g = typ.gate((0, 0), [U])
  let p = typ.port(g, "right")
  let a = typ.box(typ.offset(p, 1, 0), label: [A])
  typ.edge(p, a)
  typ.place(p.x, -1, [aligned to the port])
})

Use box(p) for both axes or box(p.x, y) for one relative axis. Offsets
use numeric diagram units; port positions follow measured gate geometry.
The same syntax works with both themes' node constructors.

Testing

bash tests/run.sh

Runs the unit/API/contract/negative test suite, deterministic geometry and
layout checks, Python helper tests, an outline-geometry snapshot, and a
documentation-figure staleness check.

License

MIT — see LICENSE.