Draw only when a reader learns more from the picture than from a paragraph or a table. 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 prose would. Ask that question before choosing a diagram type, then choose the surface by who will touch the picture next.

Picture, table, or sentence

The content is…	Use
A list of things, or attributes compared side by side	a table or bullets
One relationship ("the API calls the queue")	the sentence
A before / after that changes attributes only	a table; a change of topology is a diagram (an architecture delta)
Flow, containment, order in time, dependency, position on two axes	a diagram
Live numbers inside a product	a chart component with states, not a figure (data-is-content)

If a three-column table carries the same meaning, the table wins.

Who touches it next decides the surface

Next touch	Surface	Owner
Readers of a doc, post, README, deck or PR	a finished editorial figure: one self-contained HTML file with inline SVG; PNG or SVG only on request	`diagram-design`; diagram-craft when it is not installed; diagram-design-reconciliation when the project ships a contract
A team that keeps moving boxes: whiteboarding, planning, review in comments	an editable tldraw canvas	tldraw's agent surfaces (tldraw-canvas)
The code: versioned beside the text it explains	a Mermaid block in Markdown	the docs renderer; redraw it in diagram-design when it ships to readers
A team that lives in Figma	FigJam	Figma's `figma-generate-diagram`

One picture, one surface. When a canvas becomes a published figure, redraw it: diagram-design imports Mermaid, draw.io and Excalidraw sources and lays them out again. From a tldraw board, take the structure from its shapes and bindings, not from a screenshot. Never screenshot a canvas into a doc and call it the figure.

The budget

A figure holds about 9 nodes, 12 connectors and 2 accents. Past that it is two diagrams, an overview and a detail. diagram-design aims at a density of 4/10: complete enough to be correct, sparse enough to need no guide. An import set to faithful may run to 24 nodes in zones, and splits above that. A canvas has no hard budget. If a board needs a legend to get around, it needs frames instead (tldraw-canvas).

When to apply

Before drawing any architecture, flow, sequence, state, ER, timeline, org, journey or chart figure. Also before opening a canvas, and whenever someone asks "can you diagram this?".

Gotcha

"Make a diagram" from someone who will edit it tomorrow is a canvas job, not a figure job. A diagram-design file is finished output, and changing it means running the skill again. When the request doesn't say who touches it next, ask. And a chart inside a live product is a component with loading, empty and error states (empty-loading-states), not a figure exported once.

Sources

Cathryn Lavery, diagram-design (MIT; plugin 2.6.68, HEAD f4547ee, read 2026-10-08): SKILL.md §1 (deletion, density 4/10), §2 (when not to draw), §3 (type selection), §7 (budget), §11 (import dials).
tldraw: the tldraw-offline agent skill that tldraw Desktop installs (the app is not open source; cited, not copied), and the tldraw MCP app (tldraw/tldraw, apps/mcp-app).
Figma: the figma-generate-diagram skill (Mermaid → editable FigJam).
HKTITAN — choosing the surface by who touches it next.