# Drawing the real mechanism

> Draw a figure that shows how the thing actually works, with one accent, right-angle connectors, readable labels and an SVG a screen reader can describe.

Module: Diagrams · Level: intermediate · 8 min · https://school.agents.org.in/visual/diagrams/drawing-the-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.

*[Interactive demo: Same system. The vague version could describe any app. The real one shows the token, the queue, the async hop and the email that matters.]*

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.

  **Step: Can a node go?.** Every node (One box (or shape) in a diagram, standing for one distinct thing: a service, a step, a person, a store of data) should be a distinct idea. A "Load balancer" nobody asked about can usually go.

  **Step: Can two nodes merge?.** If two boxes always travel together, they are one box.

  **Step: Can an arrow go?.** If the layout already implies it (left to right, top to bottom), the arrow repeats it.

  **Step: 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 (The one bright color reserved for the one or two things a reader must see first. Everything else stays in quiet grays) 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:

| Kind | Treatment |
|---|---|
| Focal | accent tint fill, accent stroke |
| Service | white fill, ink stroke |
| Store (a database, a cache) | ink at 5% |
| External (the user, a third party) | ink at 3%, stroke at 30% |
| Optional | dashed `4,3` |

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.

*(Purple glow and rounded-everything is the generated-diagram look.)*

## The six connector rules

Connectors (A line or arrow between two boxes that says they are related: one calls, feeds, or leads to the other) 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 (Running only across and up or down, turning at right angles, never on a slant. Diagrams with right-angle lines look drawn on purpose) 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 (A small patch of background color behind a label on a line, so the line stops short of the words instead of running through them).** 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.

  **Before (avoid):**

Diagonal lines from center to center. "request" written across the stroke. Three arrows meeting at one point on the API box. A legend floating between nodes.

  **After (do this):**

Right angles. "request" on a paper mask above the line. Three arrows spread along the edge. The legend in a strip under the figure.

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>` (Two tags inside an SVG that name the picture and describe it in one sentence, so a screen reader can say what it shows).

```html
<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 (The colors and font families a diagram borrows from your brand. The brand changes the skin; it does not change the diagram's spacing or line rules) 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.

| Topic | Who wins inside a diagram-design file |
|---|---|
| Paper, accent, font families | your `.design` contract |
| Box radius, no shadows, connector rules | diagram-design |
| Small type (12px names, 9px sublabels) | diagram-design, as long as the figure isn't shown smaller than its width |
| Step-by-step reveal at 480ms | diagram-design: that is reading pace, not a slow button |
| Whether it moves at all | this skill decides; static by default |

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 the mechanism (paste into your agent):**

```text
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>.
```

**Check yourself:** Your figure has three arrows leaving the bottom of the API box, all starting from its exact center. Which rule fixes it?

- [ ] Make the arrows diagonal so they separate
- [x] Give each connector its own attach point, spread evenly at least 12px apart
- [ ] Put a label on each line so readers can tell them apart
- [ ] Add a drop shadow to the API box

*Why:* Connectors on one edge each get their own attach point, spaced along the edge. Diagonals and labels on lines are two of the faults the rules remove.

## In the skill

- https://school.agents.org.in/skill/diagram/diagram-craft.md
- https://school.agents.org.in/skill/diagram/diagram-design-reconciliation.md