Drawing the real mechanism

Ask an agent to "diagram how password reset works" and you will often get the vague version. Here is the real one; flip to Vague to compare.

The vague one is not wrong, exactly. It is just empty. "Backend" and "Cloud" could be any system on earth, the arrows go every direction, and nothing tells you what happens first.

The real one names the actual parts and shows the order they act in. That is the whole job of a figure: show the mechanism, so a reader could rebuild it.

Delete first

A designed diagram is mostly deletion. Before you draw, run four tests on your list of parts.

1. Can a node go?

   Every node should be a distinct idea. A "Load balancer" nobody asked about can usually go.

2. Can two nodes merge?

   If two boxes always travel together, they are one box.

3. Can an arrow go?

   If the layout already implies it (left to right, top to bottom), the arrow repeats it.

4. Can a label go?

   If the shape or color already says it, the word is noise.

Then hold the budget from the last lesson: about 9 nodes, 12 connectors, 2 accents and 2 callouts. The figure is done when nothing else can be removed.

One accent, and hierarchy by treatment

A focal accent is one bright color on one or two elements: the thing the reader must see first. In the password reset figure that is the email worker and the link it sends. An accent on five boxes is no accent at all.

Everything else gets a treatment instead of a size or a color. Identical boxes erase the hierarchy, so each kind of node looks slightly different:

Use borders, not shadows. Nodes get a corner radius of 6, never a pill and never a soft floating card. A figure is print, so the rules for shadows in a live interface don't apply here.

The six connector rules

Connectors are where most figures fail. These six rules come from Cathryn Lavery's diagram-design, and they are what make the right-hand picture look calm.

1. Orthogonal only. Right-angle elbows rounded at 8px. A straight line only when both ends share an x or a y.
2. Labels on a mask. Each arrow label sits on a patch of paper color, 6 to 10px clear of its line, never on it. 14 characters at most.
3. No stacked lines. Parallel routes sit at least 12px apart. Hop at a single crossing.
4. Own attach points. Several arrows on one edge spread out evenly, at least 12px apart, instead of meeting at the middle.
5. Never behind a box. A line that passes behind a box it doesn't end at gets rerouted.
6. Arrows before boxes. Draw lines first, so they sit behind the nodes and no label covers a box.

Strokes are muted gray by default. The headline path gets the accent, and async or return paths are dashed (5,4), like the "user clicks" line looping back to the browser.

Grid, type and legend

Put every position, size, gap and padding on a 4px grid: if it doesn't divide by 4, nudge it. Node names go in a sans font at weight 600. Technical sublabels (ports, URLs, commands) go in mono. Never use mono as a blanket "developer" font for everything.

The legend is a horizontal strip under the figure, never floating among the nodes. Widen the drawing by about 60px to make room for it.

On a phone, try the demo above at a narrow width: it switches to a vertical layout, a redesign rather than a squeeze. If you can't redesign it, keep the SVG at its full width inside a small scrolling wrapper, so the figure scrolls sideways and the page doesn't.

An SVG a screen reader can describe

A figure is an image, so it needs a name. Put role="img" on the SVG and point aria-labelledby at a <title> and <desc>.

<svg viewBox="0 0 710 320" role="img"
     aria-labelledby="reset-flow-title reset-flow-desc">
  <title id="reset-flow-title">How a password reset works</title>
  <desc id="reset-flow-desc">The API saves a short-lived token and queues a job;
    a worker emails the link, and the user clicks it.</desc>
  <!-- arrows first, then boxes; labels as real <text> -->
</svg>

Three details people miss. <title> is the first child, before <defs>. Both ids carry the figure's name as a prefix (reset-flow-title, never a bare title), because two figures on one page would otherwise clash. And <desc> describes the content in one sentence, not the geometry ("boxes and arrows" tells nobody anything).

When your project has a brand

If the project ships a .design file (a written design contract), it supplies the skin of the figure: the paper color, the ink, the one accent and the font families. diagram-design keeps everything else: the geometry, the connector rules, the type sizes and its motion timing, because its scripts check them.

The gotcha goes both ways. Skip diagram-design's first-run question about colors and you ship its default palette (an orange accent on warm gray) as if it were your brand. Re-skin the connector rules "to match the brand" and you break the checks it runs.

Draw a figure of how [system] actually works, as one HTML file with inline SVG.
Name the real parts (not "Backend" or "Cloud") and show the order they act in.
Delete first: cut any node, arrow or label the layout already implies. Max 9 nodes, 12 connectors.
One accent on the headline path only. Treatment by kind: focal tint, service white, store 5% ink, external 3%.
Orthogonal connectors (r=8), labels on paper masks 6–10px off the line, own attach points, arrows drawn before boxes.
4px grid, sans 600 names, mono only for technical sublabels, legend as a strip under the figure.
role="img" with aria-labelledby to a prefixed <title> and a one-sentence <desc>.