Should you draw it?

Here is the same idea said three ways. Pick a piece of content, then flip between a sentence, a table and a picture. Only one of them is the best fit each time, and it is not always the picture.

A diagram is the most expensive way to say something. It costs layout, labels, a legend and a review. And a wrong one teaches the wrong structure faster than a paragraph ever could, because people trust pictures.

So the first question is never "which kind of diagram?". It is does a reader learn more from a picture than from a paragraph or a table?

Picture, table or sentence

Most content falls into one of a few shapes. Each shape has a format that suits it.

The test is simple. If a three-column table carries the same meaning, the table wins. If a sentence does, the sentence wins.

The trap is "before and after". If a redesign only changes attributes (a new price, a new name), that is a table. If it changes the topology, meaning which thing connects to which, that is a diagram.

Who touches it next?

Once you know a picture helps, the next question decides where it lives. A picture has a surface, and you choose it by asking who will touch it next.

1. Readers only read it

   A doc, a blog post, a README, a deck, a pull request. Make a finished editorial figure: one HTML file with the drawing inside it as SVG. Cathryn Lavery's diagram-design skill draws these.

2. A team keeps moving boxes

   Planning, whiteboarding, reviewing in comments. Use an editable canvas like tldraw, where arrows stay attached when someone drags a box.

3. It lives beside the code

   A picture that changes when the code changes. Write it as a Mermaid block in the Markdown, versioned with the text it explains.

4. The team lives in Figma

   Use FigJam. Meet people where they already work.

One picture, one surface. When a canvas grows up into a published figure, redraw it from its structure. Never paste a screenshot of a whiteboard into a doc and call it the figure.

Try the whole decision

Here is that flow as three questions. Answer them for something you have been meaning to diagram.

Notice that three of the four first answers end in "don't draw it". That is the honest ratio. Most "can you diagram this?" requests are tables wearing a costume.

The budget

A single figure holds about 9 boxes, 12 arrows and 2 accent colors. That is the diagram budget. Past it, the figure is really two figures: an overview that shows the big parts, and a detail that zooms into one of them.

diagram-design aims for a density of about 4 out of 10: complete enough to be correct, sparse enough that nobody needs a guide to read it. A canvas has no hard budget, but if a board needs a legend to find your way around, it needs frames (labelled groups) instead.

Ask your agent the right way

Agents love to say yes to "diagram this". The skill makes them ask the cheap questions first. You can too, in the prompt.

Before you draw anything, decide whether this should be a sentence, a table or a diagram, and say why in one line.
If it is a diagram, ask me who will touch it next (readers, a team editing it, the code, or Figma) and pick the surface from that.
Keep one figure under 9 nodes, 12 connectors and 2 accent colors; if it needs more, propose an overview and a detail instead.

Two gotchas to remember. A chart inside a live product is not a figure at all: it is a component with loading, empty and error states. And if the request does not say who edits the picture next, that is a question to ask, not a guess to make.