forked from bots-garden/ori
| ✨ Workspace panel, selectors, previews, desktop app, sandbox template, resizable file tree, light/dark theme | 1 | --- |
| 2 | name: slide-diagram | |
| 3 | description: Draw a diagram for the talk's slides — boxes-and-arrows explaining a mechanism (function calling, tool detection, MCP, an agent loop…) — in this deck's house style, as an SVG that draw.io can reopen and edit. Use whenever someone asks for a diagram, a schema, "un schéma", a drawing of a flow, or wants to change an existing `.assets/*.drawio.svg`. | |
| 4 | --- | |
| 5 | ||
| 6 | # Slide diagram | |
| 7 | ||
| 8 | Diagrams in this repository are **generated from a small JSON spec**, never hand-drawn: | |
| 9 | ||
| 10 | ``` | |
| 11 | <chapter>/.assets/<name>.json the spec — the source of truth | |
| 12 | <chapter>/.assets/<name>.drawio.svg the output — embeddable in Marp, editable in draw.io | |
| 13 | ``` | |
| 14 | ||
| 15 | The renderer is `scripts/make-diagram.mjs` (in this skill). The SVG it writes carries the | |
| 16 | mxfile in its `content` attribute, so draw.io opens it, and Marp/GitHub/browsers show it as a | |
| 17 | plain SVG. | |
| 18 | ||
| 19 | ## Workflow | |
| 20 | ||
| 21 | 1. **Turn the explanation into a flow.** Name the actors (boxes) and what travels between them | |
| 22 | (arrows). Number the steps in the edge labels (`1.`, `2.`, …) whenever the order matters — | |
| 23 | the audience reads a slide in two seconds, the numbers do that job. | |
| 24 | 2. **Write the spec** as `<chapter>/.assets/<name>.json` (schema below). Start from | |
| 25 | `references/example.json`. | |
| 26 | 3. **Render**: `node <skill>/scripts/make-diagram.mjs <chapter>/.assets/<name>.json` | |
| 27 | 4. **Look at it — always.** Text overflow is the failure mode and it is invisible in the source: | |
| 28 | ||
| 29 | ```bash | |
| 30 | command -v rsvg-convert || sudo apt-get install -y -qq librsvg2-bin | |
| 31 | rsvg-convert -z 1 <name>.drawio.svg -o /tmp/check.png | |
| 32 | ``` | |
| 33 | ||
| 34 | Then read `/tmp/check.png` with the Read tool and check: no text crossing a box border, no | |
| 35 | label sitting on top of another, every arrow head visible, nothing clipped by the canvas. | |
| 36 | 5. **Fix and re-render** until it is clean. Widen boxes, shorten wording, move a column right. | |
| 37 | 6. Report the file path and describe the flow in a few lines. | |
| 38 | ||
| 39 | Grep the code the slide is about (`tools.go`, `main.go`, …) before naming things: use the real | |
| 40 | tool names, the real model, the real arguments. A diagram that matches the demo output is worth | |
| 41 | three that are merely plausible. | |
| 42 | ||
| 43 | ## Spec format | |
| 44 | ||
| 45 | ```json | |
| 46 | { | |
| 47 | "name": "Tool detection", // the draw.io page name | |
| 48 | "width": 1220, "height": 540, // canvas, in px | |
| 49 | "nodes": [ | |
| 50 | { "id": "llm", "x": 370, "y": 250, "w": 280, "h": 110, | |
| 51 | "label": "LLM (tool support)\\nDocker Model Runner", "kind": "dark" } | |
| 52 | ], | |
| 53 | "edges": [ | |
| 54 | { "from": "user", "to": "llm", "label": "1. prompt +\\ntools[]" } | |
| 55 | ] | |
| 56 | } | |
| 57 | ``` | |
| 58 | ||
| 59 | `\\n` in a JSON string (a literal backslash-n, *not* a real newline) is a line break. | |
| 60 | ||
| 61 | **Node `kind`** — pick by role, not by taste: | |
| 62 | ||
| 63 | | kind | look | use for | | |
| 64 | |---|---|---| | |
| 65 | | `box` | white, dark border, regular | the human, the calling program | | |
| 66 | | `dark` | dark fill, white bold text | the LLM — always exactly one, it is the centre of gravity | | |
| 67 | | `accent` | sage fill, bold | data or a tool the model is given: the catalog, a tool, a store | | |
| 68 | | `intent` | white, blue border, blue bold | what the model *emits*: `tool_calls`, a JSON payload | | |
| 69 | | `note` | dashed border, smaller regular | the one sentence the audience must leave with | | |
| 70 | ||
| 71 | **Edge fields**: `from`, `to`, `label`, `dashed` (blue + dashed — reserve it for the tool / | |
| 72 | model machinery, keep plain dark for the human-facing flow), `waypoints` | |
| 73 | (`[{"x":…,"y":…}]`, absolute, for a return path routed around the boxes), and | |
| 74 | `fromSide`/`toSide` (`"top" | "bottom" | "left" | "right"`) with optional `fromAt`/`toAt` | |
| 75 | (absolute coordinate along that side). Use the sides when two boxes are stacked and linked | |
| 76 | **twice** — otherwise both arrows leave from the same centre and cross. | |
| 77 | ||
| 78 | Anything else about the palette, the sizing arithmetic and the standard layouts: | |
| 79 | `references/style.md`. Read it before choosing box widths. | |
| 80 | ||
| 81 | ## Rules that keep the deck coherent | |
| 82 | ||
| 83 | - **One spec, one SVG, same basename.** Never edit the `.drawio.svg` by hand. | |
| 84 | - **Never regenerate a diagram someone has re-exported from draw.io** without saying so: their | |
| 85 | export replaces the file and the JSON no longer describes it (a draw.io-exported file starts | |
| 86 | with `<svg host="…"` and has a compressed `content`; ours starts with `<svg xmlns=…` and a | |
| 87 | readable one). Ask, or port the edits back into the JSON first. | |
| 88 | - **English on the diagrams**, whatever language the conversation is in. | |
| 89 | - The renderer is byte-stable: same spec → same SVG. Regenerating a chapter's diagrams should | |
| 90 | produce no diff. | |
| 91 | ||
| 92 | ## Embedding in a Marp slide | |
| 93 | ||
| 94 | ```markdown | |
| 95 |  | |
| 96 | ``` | |
| 97 | ||
| 98 | Keep the canvas around 1000–1250 px wide: it lands at a readable size on a 1280×720 slide | |
| 99 | without scaling the text into mush. |