Diagrams

Trim before you add

Every node, arrow, and label in an estate diagram has to do work the surrounding prose can't. The four-tile FLOW/DISCIPLINE cluster at the top of every hero is this rule made literal: four facets, never six, never ten. Bairn's vendor-survives diagram carries one downstream direction plus three disruption arrows that terminate at a barrier, nothing else. Patinate's pipeline carries the four CLI commands and their three caches, no more.

Before adding a node to an existing diagram, ask which node it replaces. Diagrams that grew got worse; diagrams that shed got better.

When one is already over budget, cut in a fixed order: decoration, exact duplicates, leaf clusters, degree-1 sinks, cross-cutting infrastructure, and only then split the diagram. A collapsed cluster becomes one node carrying its count, named in the caption.

Fill and stroke rank the node

The focal node wears the accent. A service is surface on ink. A store, or anything outside the boundary, fades back to --surface behind a --border hairline. Identical boxes for every node erase the hierarchy the reader came for, and no amount of labelling puts it back.

The accent is a budget

Moss #4a6741 is the single brand accent across the estate. Inside a diagram it is a budget: one or two elements wear it, and they are the elements you want the reader to look at first. Everything else renders in --text, --text-2, --text-muted, or --border.

If you find three things needing accent in a single diagram, the diagram is doing two jobs: split it.

Coordinates snap

Estate diagram SVGs snap structural coordinates to a four-unit grid. Boxes start at x=20, never x=23. Gaps are 16, never 15. Heights and widths are multiples of 4. The exception is intra-element geometry (curve control points, arrowhead apices, path tangents), which lands where it needs to.

Stroke, radius, shadow

• Borders and rules are 1px hairlines. Content lines (arrows, flow paths) are 1.5–2px.
• Border-radius caps at var(--radius) (10px). Super-rounded corners snap straight into template-flavor territory.
• No drop shadows. Depth comes from the contrast between --bg and --surface, never from blurred copies of the element.

Five roles, one type ramp

Size in a diagram is a role, not a taste call. At 660 wide the ramp is fixed, and sans carries meaning while mono carries technical fact.

• Eyebrow. 8px IBM Plex Mono, tracked caps, --text-muted. What kind of thing this node is.
• Name. 12px IBM Plex Sans 600, --text. The word the reader takes away.
• Sublabel. 9px IBM Plex Mono, --text-2. Port, path, command, count.
• Arrow label. 8px IBM Plex Mono, --text-2, sitting on its own opaque mask.
• Caption. --text-sm in --text-2, prose under the SVG, never a legend.

A node stacks at most three of these rows. A fourth row is a sublabel that wants to be its own node.

Arrows stay traceable

A reader has to follow any one connector from source to target without losing it. No two connectors share a path or an attach point: fan the arrows leaving a box across its edge instead of stacking them on one anchor, hold parallel runs 12px apart end to end, and where two lines must cross, hop the less important one.

Nodes sharing no axis connect through a rounded right-angle elbow at r=6, never a diagonal, and return legs route around boxes along the row's bottom edge rather than through them. A diagonal that clips a box is the line the reader loses.

Fan the arrows leaving one edge at L*k/(N+1), and open parallel runs to 14px where a label has to sit between them.

Three arrow kinds, no fourth

Muted for an internal hop, moss for the one focal path, dashed for optional, async, return or transit. A fourth colour would be a second accent, and the budget is already spent.

Every connector ends in an arrowhead. A line with no marker-end is a wire, not a flow, and the reader has to guess which way the thing moves.

Paint order is fixed

Background, zones, arrows, labels, nodes. Arrows before boxes is what makes every label rule checkable: a connector that would have crossed a node is visibly clipped by it instead of floating over the top, so the routing error shows up while you are drawing.

Arrow labels get an opaque mask

Each arrow label sits on its own opaque rect: 8px between mask edge and stroke, clearing any node painted after it, and clear of the arrowhead's ~10px range. Length is the constraint the mask cannot fix: "GET descriptor" fits beside its arrow, "GET descriptor.xml" overruns.

Detail-rich diagrams ship as a pair

Anything carrying more than six labeled elements at hero scale ships as a .diagram.figure-pair: a wide horizontal SVG for desktop, a stacked vertical one for mobile. The chrome swaps at the 900px breakpoint. Patinate's pipeline diagram is the worked example.

A 660×200 canvas tops out near six nodes and eight arrows. Past that, a diagram of two mechanisms the prose treats separately ships as a pair, or two figures with a caption each, never a denser canvas. A single-concept object, a ladder, a spectrum, a matrix, a chain the post walks end to end, a side-by-side comparison, is not two mechanisms: it stays one figure however many nodes it carries, growing the canvas height instead of splitting.

Every specimen, the four below and the rest in the gallery, is single-figure by design: each one shows a type at its simplest legible density, so none of them reaches the threshold that earns a pair.