updates 33.1 139

docs/graphs/README.md

@@ -0,0 +1,67 @@
+# 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.