Diagrams

Boxes and arrows for architecture and flows, in the same flat style as the charts: hairlines, warm panels, one accent. Placed automatically, so nobody draws coordinates.

From photographer to customerA photo is uploaded, captioned and published, then found and bought by a customer.

The look

Diagrams share the charts’ language: flat shapes with no shadows or gradients, hairline outlines, a warm panel for groups, and the accent (Lava in the NTB theme) on one or two things only. Lines are quiet grey and turn the accent colour only on the path that matters. Everything is a design token, so diagrams follow Theme and Mode.

One idea per diagram; nine boxes or fewer, otherwise an overview plus a detail
Accent on at most two things: the point of the diagram
Real names from the system, short: “Photo desk”, not “Service A”
A title that says what the diagram shows, and a one-line description

Don’t

Colour as decoration, or a colour per box
Labels longer than a few words; put the explanation in the text
Arrows without a meaning; label them or leave them out
A diagram where a list or a table would do

Shapes

Most things are boxes. The other shapes say what kind of thing it is, so the reader doesn’t need a legend.

ShapesSix shapes: box, person, store, external, decision and terminal.

Tones and lines

Tones and linesAccent marks the focus, muted marks context, success and danger mark outcomes; dashed lines are optional or passive.

Tone	Use	Tokens
Default	Most boxes and lines	`surface-raised, line-strong, ink-muted`
Accent	The point of the diagram, at most two elements	`accent, accent-text`
Muted	Context the reader needs but shouldn’t focus on	`band, line, ink-muted`
Success, danger	Outcomes: allowed and refused, passed and failed	`success, danger and their soft fills`

Dashed lines are optional, passive or asynchronous; dashed and danger together mean “not allowed”. Numbered steps turn a diagram into a flow the reader can follow in order.

Type

Role	Face	Size
Name	Geist, semibold	14 px
Detail (file, technology, value)	Geist Mono	12 px
Tag (kind of thing)	Geist Mono, uppercase, tracked	10 px
Arrow label	Geist, medium	12 px
Group	Geist Mono, uppercase, tracked	11 px

Examples

Pick by what the reader needs to see.

Layers

What runs where.

Where the image portal runsBrowser, server and outside services, with what talks to what.

Numbered flow

A request, step by step.

Downloading a bought imageFour steps from click to file, numbered in order.

Decision

Which way something goes.

Can this customer buy the image?Agreement customers pay by agreement; others pay by card or are refused.

Fan-out

One source, many uses.

One receipt, three outputsThe same component is the page, the print and the PDF.

Lifecycle

Something that goes round.

A pack of downloadsBought, used, used up or expired, then bought again.

Allowed and blocked

A boundary and the way round it.

What an experiment may useExperiments use the platform; a direct import between them is refused; copying is the way.

Writing one

A diagram is described, not drawn: what the boxes are, how they connect, and which group they sit in. Placement and routing are automatic (ELK, a layout engine), and the style comes from this page. In markdown docs, write a diagram block; in pages, pass the same object to DiagramView.

```diagram
{
  "title": "From photographer to customer",
  "description": "A photo is uploaded, captioned and published, then bought.",
  "groups": [{ "id": "ntb", "label": "NTB" }],
  "nodes": [
    { "id": "photographer", "label": "Photographer", "shape": "person" },
    { "id": "desk", "label": "Photo desk", "detail": "captions, rights", "group": "ntb" },
    { "id": "portal", "label": "Image portal", "group": "ntb", "tone": "accent" }
  ],
  "edges": [
    { "from": "photographer", "to": "desk", "label": "uploads", "step": 1 },
    { "from": "desk", "to": "portal", "label": "publishes", "step": 2 }
  ]
}
```