figure

Figure

One animated SVG, no scripts, no upload: it renders and plays anywhere markdown does — GitHub README, PR and issue comments, blog posts, Notion. Sharp at any size, and it follows the reader's light or dark theme.

Figures are Giotto diagrams: one JSON document, the same format the docs site's interactive figures use (hindsight-docs/figures/*.json).

You write the diagram JSON — never SVG. One command renders it. No build, no browser.

1. Write the diagram

Do not save it as a file in the repo. It is an input, not a deliverable — pipe it in (step 2), and the rendered SVG keeps a copy of it for you.

{
  "title": "Retain",
  "speed": 2000,
  "elements": [
    { "id": "root", "type": "group", "children": ["agent", "api", "bank"], "layout": { "direction": "row", "gap": 48 } },
    { "id": "agent", "type": "rectangle", "content": [{ "type": "title", "text": "Your AI Agent" }] },
    { "id": "api", "type": "group", "label": { "title": "Hindsight API" }, "children": ["retain"], "layout": { "direction": "column", "gap": 24 } },
    { "id": "retain", "type": "rectangle", "content": [{ "type": "title", "text": "Retain" }, { "type": "subtitle", "text": "LLM extraction" }] },
    { "id": "bank", "type": "group", "label": { "title": "Memory Bank" }, "children": ["facts", "obs"], "layout": { "direction": "column", "gap": 28 } },
    { "id": "facts", "type": "cylinder", "content": [{ "type": "title", "text": "Facts" }, { "type": "subtitle", "text": "world · experience" }] },
    { "id": "obs", "type": "cylinder", "content": [{ "type": "title", "text": "Observations" }] },
    { "id": "call", "type": "arrow", "route": "curved", "start": { "id": "agent" }, "end": { "id": "retain" }, "label": { "text": "retain()" } },
    { "id": "store", "type": "arrow", "route": "curved", "start": { "id": "retain" }, "end": { "id": "facts" }, "label": { "text": "extract" } },
    { "id": "consolidate", "type": "arrow", "route": "curved", "start": { "id": "facts" }, "end": { "id": "obs" }, "label": { "text": "consolidate" }, "quiet": true }
  ],
  "scenes": [
    {
      "label": "retain()",
      "beats": [
        { "edges": { "edge": "call", "data": "“Alice joined Google in March”" }, "say": "Your agent sends what happened." },
        {
          "edges": "store",
          "show": { "facts": [{ "tag": "world", "tone": "blue", "text": "Alice joined Google", "meta": "Mar 2026", "mark": "new" }] },
          "say": "An LLM pulls out the facts."
        },
        {
          "edges": "consolidate",
          "ms": 2600,
          "show": { "obs": [{ "text": "Alice works at Google", "meta": "2 sources" }] },
          "say": "The worker merges them into one belief."
        }
      ]
    }
  ]
}

Elements — a flat list. A group lists its children by id and lays them out (layout: { direction: "row" | "column", gap, align }); a label: { title } draws a frame around it. Children line up at the top/left unless the layout says otherwise: use align: "center" in rows and align: "stretch" in columns (equal-width boxes), as the docs figures do. rectangle boxes are the things that do something; cylinder is data at rest; diamond is a decision. A box's content is blocks: title, subtitle, text, list, chips, code. Give every element a stable id.

Arrows — { type: "arrow", start: { id }, end: { id }, label?: { text }, route: "curved", around?, quiet? }; the ends name a box or a group. around: "above" | "below" arcs over the boxes in between; quiet: true draws the arrow only while a scene uses it (for long arrows that would cut across).

Scenes and beats — each scene is one story the figure tells; the SVG plays them in a loop. A beat is one moment: edges (an arrow id, { edge, back, data } for a reverse hop or a data chip, or an array to run several at once), say (the caption), show (fills the card inside a box until the scene ends), light (highlight boxes for that beat; on the scene, for the whole scene), ms (how long the beat lasts).

Card rows — { tag?, tone?, text, meta?, mark?, mono? }. tone is blue | purple | green | orange | red | gray. Use tag for the kind of thing (world, user, page), meta for a detail, and mark for what happened to it (new, ✓, cited, ↻). **bold** and `code` work in any text.

The full format is the FORMAT text in node_modules/giotto/lib/edit.js. The 13 figures in hindsight-docs/figures/ are working examples — the fastest start is copying the closest one.

Keep it honest and specific: real example data beats placeholders, and every claim in a label, card or caption must match what the code actually does — check the code, don't assume.

2. Render it — from stdin, so nothing is left on disk

npx giotto export - path/to/out.svg <<'DOC'
{ "title": …, "elements": […], "scenes": […] }
DOC

giotto comes from the docs site's dependencies (npm install at the repo root). The quoted <<'DOC' heredoc passes the JSON through untouched, and the only file produced is the SVG. Layout and scene warnings print on stderr: fix them. A reference to an element that doesn't exist (an arrow end, a group child, a box a scene fills) is an error: the export fails and writes nothing.

Other forms:

npx giotto export hindsight-docs/figures/retain.json out.svg   # a docs figure, as an SVG
npx giotto export doc.json out.svg --theme dark --static       # one still frame, dark
npx giotto spec out.svg                                        # print the diagram an SVG carries

Every SVG embeds its diagram in <metadata id="giotto-doc">, so a figure stays editable without anyone keeping the JSON: read it back with giotto spec, change what you need, render again.

3. Look at it before you ship it

Always. Text that overflows its box, an arrow crossing a box, a caption that does not match what is moving — obvious on sight, invisible in the source.

cd $(dirname out.svg) && python3 -m http.server 8777 &   # the browser tool blocks file:// URLs

Then open http://localhost:8777/out.svg, screenshot it, wait a few seconds and screenshot again to catch a later beat. open out.svg works too when a human is watching.

4. Put it where it belongs

• PR or issue comment — commit the SVG on the branch, then reference its raw URL: ![figure](https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<path>.svg). GitHub renders and animates it immediately.

• README or repo docs — commit it and link it with a relative path.

• Blog post — hindsight-docs/static/img/blog/, referenced as /img/blog/<name>.svg.

• The docs site's own pages — don't use an SVG. Those pages use the interactive player, which has tabs, pause, speed and hover. Save the diagram as hindsight-docs/figures/<name>.json and put it on the page:

  import Figure from '@site/src/components/Figure';
  import retain from '@site/figures/retain.json';
  
  <Figure doc={retain} />
  

What the SVG cannot do

It loops through every scene with no controls: no tabs, no pause, no hover. If the figure needs those, it belongs on the docs site. Keep an SVG to one or two scenes so the loop comes back round quickly.