Diagrams in code: every figure of this site is a small function

A diagram drawn in an editor is an image: it does not translate, it does not follow the site's colours, and nobody updates it when the system changes. Every figure on this site is code instead: a small function that writes the SVG, so the diagram lives next to the text, in version control, in both languages.

What you get. Around fifty diagrams that render in French and English from one source, sharp at any size, light to load, described for screen readers, and checked by a test at every build. Changing a label is a one-line commit.

1. A few helpers, one function per diagram

def agents(lang):
    L = {"en": labels(cap="Three coding agents, three roles...", of="OpenFox", ...),
         "fr": labels(cap="Trois agents de code, trois rôles...", of="OpenFox", ...)}[lang]
    body  = box(20, 20, 230, 50, L["of"], L["ofs"], stroke=GOOD)
    body += box(500, 55, 220, 54, L["gw"], L["gws"], stroke=GOOD)
    body += arrow(250, 45, 498, 75, None, GOOD, marker="good")
    return figure("agents", 740, 295, L["cap"], body)

• box, arrow and a text helper write native SVG shapes; colours come from a handful of constants.
• figure wraps the drawing in <figure> with its caption, and gives the SVG role="img" and an aria-label carrying the same sentence.
• A page calls a diagram with a marker, {{diagram:agents}}, and the build replaces it with the figure in the page's language.

2. The rules that keep them useful

1. One figure, one claim. The caption says what the picture shows, in one or two sentences.
2. Draw the mechanism, not its name: the path a request takes, the arrow that disappears when you remove a piece.
3. Label the arrows when the label carries information ("your tap", "signed answer").
4. Colour means something: one colour for local, one for the cloud, one for a problem. Nothing decorative.

3. A test for every diagram

The site's tests render every diagram in both languages and fail if one is missing or has no caption, and the build stops on a marker that names no diagram. A typo in a marker cannot reach the site.

A marker name with a digit once went unreplaced and printed raw on the page. The fix was in the pattern; the lesson was to test the marker, not just the drawing.

4. For richer charts: a diagram skill

For a standalone diagram (an architecture, a timeline, a state machine, a swimlane), we let an agent use a diagram skill: forty-five chart types, each a self-contained HTML file with inline SVG and an editorial style. Its first rule is a good one: before the first diagram of a project, it stops and asks for your brand colours, rather than shipping its defaults.

Traps

Read a rendered diagram before publishing: overlapping labels do not raise any error. We render each new figure in a headless browser and look at the screenshot.

Found this useful? Tell us what to measure next.