Diagrams

Diagrams in the SIOT documentation are plain SVG files written by hand. Each file is its own source, so there is nothing to export: edit the SVG, view it in a browser, and commit it. The shared style below keeps every diagram consistent and lets each one follow the reader’s light or dark theme.

Style guide

Starting a new diagram

Copy an existing diagram that is close to what you need and edit it. Every file starts with the same <style> block, <defs> with the arrow markers, and a background <rect class="bg">. Keep that header unchanged so the diagrams stay in step; if the style needs to change, change it in every file.

Put the file in the images/ directory next to the page that uses it (ADRs use assets/).
Set viewBox, width, and height to the same size, about 900 × 500 or smaller.
Describe the diagram in the aria-label on the <svg> element, and give the Markdown image the same kind of alt text.
Leave the title out of the diagram. The heading or sentence around it says what it shows.

Shapes

Element	SVG	Use
Box	`<rect class="shape blue" rx="6">`	a thing: an instance, a client, a node, a device
Container	`<rect class="shape gray" rx="10">`	where things run or belong: an instance, a site, the cloud
Pill	`<rect class="shape purple">`, `rx = h/2`	a NATS bus or a stream
Circle	`<circle class="shape green">`	a node in an abstract graph (`N1`, `a`)
Diamond	`<polygon class="shape yellow">`	an edge that carries points
Stick figure	`<g class="actor">`	a person
Dashed border	add `dashed`	a replica, a mirror, or something that does not run

Container titles start with an emoji so the reader can tell places apart at a glance: ☁️ cloud, 📟 edge device, 🏭 site, 📦 SIOT instance, 🧩 clients. Use an emoji in a box label only when it names a kind of thing (👤 user, 📜 rule).

Colors

Each color has a meaning. Pick the color by what the shape is, never for decoration.

Class	Light fill	Meaning
`blue`	`#dae8fc`	SIOT instances, clients, and other software
`green`	`#d5e8d4`	nodes in the tree
`yellow`	`#fff2cc`	points and other data
`purple`	`#e1d5e7`	NATS, streams, and external services
`orange`	`#ffe6cc`	hardware: sensors, MCUs, motors
`red`	`#f8cecc`	a warning, or something that does not happen
`gray`	`#f5f5f5`	containers

The @media (prefers-color-scheme: dark) rule in the style block swaps each fill for a dark tint of the same color, so the meaning carries over to the dark theme.

Lines

All lines use class="edge" (1.5 px):

Flow: an arrowhead at the end, marker-end="url(#arrow)".
Two-way: add marker-start="url(#arrow)", for sync or request/response.
Tree: no arrowheads, drawn as elbows from parent to child, with the parent above or to the left.
Dashed (edge dashed): a logical link, such as a subscription or the same node in two places.
Colored (edge c-red with url(#arrow-red)): only when one diagram shows more than one kind of flow; say what each color means in a label.

Text

Class	Size	Use
`title`	14px	container titles
(default)	12px	box labels
`small`	11px	line labels and second lines in boxes
`small muted`	11px	notes and explanations
`mono`	11px	stream names, NATS subjects, and point types

Line labels sit on a <rect class="label-bg"> so they stay readable where they cross a line. Use sentence case and keep labels to a few words; put longer explanations in the page text.

Checking a diagram

Open the SVG in a browser and switch the system between light and dark mode. To check from the command line, render both modes with Chromium:

chromium --headless --force-device-scale-factor=1 --window-size=900,500 \
  --screenshot=light.png file://$PWD/docs/ref/images/arch-app.svg
chromium --headless --force-device-scale-factor=1 --window-size=900,500 \
  --force-dark-mode --blink-settings=preferredColorScheme=0 \
  --screenshot=dark.png file://$PWD/docs/ref/images/arch-app.svg