# Graphs

The `.dot` files carry **structure and meaning**. The palette lives in
`themes/*.gvpr` and is applied at render time.

```bash
./render.sh              # every graph, every theme
./render.sh lucid        # one theme
./render.sh dark system_overview
```

Needs graphviz (`sudo apt install graphviz`). The committed SVGs work without
it; this is only needed to re-render.

## Why themes, and why gvpr

The sources used to hardcode the dark palette inline, which meant one look and
no way to get another. `gvpr` rewrites the *parsed* graph, so it overrides
whatever a `.dot` set — one source renders in any theme without being edited.

Command-line `-G`/`-N`/`-E` flags would not do: those are defaults, and an
attribute written in the file beats them.

Colour is **baked into each SVG** rather than driven by CSS, because both docs
sites embed graphs with `<img src=...>`. That makes the SVG a separate document
the page's stylesheet cannot reach.

## Output

| Theme | Writes | For |
| --- | --- | --- |
| `dark` | `<name>.svg` | the docs site — this is the default, and what `docs/data/en/*.md` links to |
| `lucid` | `<name>.lucid.svg` | regulated documents, print, and sitting beside a real lucid.app export |

## Classes

Nodes, edges, clusters and the graph itself may carry a `class`. Anything
untagged gets the theme's neutral treatment.

| Class | Means | dark | lucid |
| --- | --- | --- | --- |
| `accent` | the emphasised thing | amber outline | blue outline, pale blue fill |
| `accent-text` | emphasised *label*, not a box | amber text | blue text |
| `ok` | live, working | green text | green outline, pale green fill |
| `artery` / `atlas` / `station` | belongs to that system | that system's colour | its pale equivalent |
| `muted` | present but not the point | grey text | grey fill |

`class` survives into the SVG (`<g class="node accent">`), so an **inlined** SVG
can also be styled by page CSS. That is not how the docs embed them, but it is
there if a page wants it.

## What themes never touch

- **`shape`** — a cylinder is a datastore, not a decoration.
- **`style=invis`** — layout scaffolding. Filling it would draw it.
- **`style=dashed`** — a weaker relationship; the theme preserves it and adds to it.
- **`label`, `rankdir`, `rank`, `fontsize`** — content and layout.

## Adding a theme

Drop a `themes/<name>.gvpr` in beside the others; `render.sh` picks it up with no
edit. Match the palette to `soleprint/common/theme/themes/<name>.css` so a
diagram and the page around it are the same visual language.

Name fonts that exist on the target. `lucid.gvpr` uses Arial deliberately: it is
on every Windows box and fontconfig aliases it to Liberation Sans on Linux, so
the SVG measures the same on both and text does not reflow out of its box.