Editorial Diagram Designer

---
name: editorial-diagram-designer
description: Use when a diagram has to survive being looked at, meaning a launch post, a deck, public documentation, or anything carrying a brand. Produces self-contained HTML with inline SVG across thirty-nine visual types, skinned from your own tokens. Triggers on "make this diagram presentable", "on-brand diagram", "redraw this Mermaid", "architecture diagram for the blog post". Not for diagrams that belong in version control as text, and not for throwaway sketches.
---

# Editorial Diagram Designer

Most diagrams fail for one of two reasons. Either the wrong shape was chosen for the thing being shown, or the geometry was left to an automatic renderer and the result cannot be traced by eye. Both are fixable before drawing, and neither is fixed by adding colour.

The highest-quality move in a schematic is almost always deletion. Two nodes that always travel together are one node. A connection whose meaning is already obvious from the layout is a line that can go.

## Ask first whether to draw at all

Before anything else: would a reader learn more from this than from a well-written paragraph? Lists of things belong in a table. A simple before and after belongs in a table. A one-shape diagram is a sentence.

Say so when the answer is no. A diagram nobody needed is worse than a paragraph, because it costs the reader time to decode before they discover it was decorative.

## Choose the pattern, then the type

Route on behaviour, not on the noun in the request. Someone asking for "an architecture diagram" often has a queue problem.

| What carries the meaning | Where it lands |
|---|---|
| Fan-in, queue depth, finite capacity, a bottleneck | Data flow |
| Loose input becoming a durable structured artifact | Data flow |
| Trust boundaries with permitted and forbidden paths | Architecture |
| Controls grouped by where they are enforced | Layer stack |
| Defenses compensating for gaps, residual risk propagating | Layer stack |
| Two rule traces needing pass, fail, and first divergence | Flowchart |
| A quantity splitting and merging, width carrying amount | Sankey |
| Causes of one observed effect, grouped by category | Fishbone |
| Value chain against evolution, what to build and buy | Wardley map |

Thirty-nine types are available beyond these. Load the layout grammar for the one chosen and no others, otherwise the reference reading costs more than the drawing.

State the plan in one short line before rendering: the type, the size, and anything the density budget will force out. Let the person redirect while redirecting is still cheap.

## Density is a budget, not a preference

Target roughly four out of ten. Complete enough to be technically true, sparse enough to need no guide.

Past nine primary nodes it is almost certainly two diagrams, and the honest move is an overview plus a detail rather than one canvas that fails at both. Every node earns its place by representing a distinct idea.

## The tells of a machine-made schematic

These are the things that make a diagram read as generated, and each one is a rejection:

- A dark background with cyan or purple glow, which looks technical without a single design decision behind it
- A monospace face used as blanket developer decoration; mono is for ports, commands and URLs, and names belong in the sans
- Identical boxes for every node, which erases the hierarchy the reader needs
- Shadows anywhere, and corner radii past roughly ten pixels
- The accent colour on five nodes, which means it now signals nothing; one or two focal elements, chosen deliberately
- A legend floating inside the drawing area, colliding with the nodes
- Reproducing what an automatic renderer would have laid out, which imports its spacing and routing instead of making an editorial decision

## Six connector rules

A reader who cannot follow a line has been handed a decorative object. These are not stylistic:

1. **Orthogonal routing.** Every bend is a rounded quarter-arc. A diagonal between nodes that share neither axis is a failure, not a shortcut. Straight segments are for endpoints that genuinely share an x or a y.
2. **Labels sit clear of their stroke.** An opaque mask stops the line bleeding through the text, and a visible six to ten pixel gap between mask and stroke keeps the connection traceable. A label sitting on its own arrow hides the thing it describes.
3. **No overlapping connectors.** Two lines never share a path or run stacked. Where orthogonal routes must cross, use a bridge hop. Where they merely want to, offset by at least twelve pixels. Stacking is a symptom that the layout is over budget.
4. **Fan the attach points.** Several connectors on one edge each get their own point, spaced evenly along it, and parallel runs stay apart along their whole length rather than only at the box. No connector may hide another.
5. **Do not transit behind an unrelated box.** Reroute around anything that is neither source nor destination. When a cross-cutting element makes that geometrically impossible, dash the stroke so it reads as transit, keep the label at the visible end, and let the arrowhead resolve only at the true destination.
6. **A label mask must not land on a node.** Nodes paint after labels, so a mask overlapping one leaves the text clipped against a border. Place labels on segments crossing open canvas.

Draw the arrows before the boxes so z-order puts the lines behind the nodes.

## Brand tokens resolve once

Colour and type live behind semantic roles rather than hex values scattered through the markup: paper and its container variant, ink for primary text and stroke, muted and soft for secondary text and default arrows, hairline rules, an accent with its tint, and a distinct link colour for external and API calls.

Change the roles in one place and every diagram reskins. Pull them from a website, a design-system directory, an installed theme or pasted values, then save the result as a named profile so the next diagram for the same client starts correct.

Do not silently ship default-skinned diagrams into a branded project. Ask once, at the start, and remember the answer.

## Node treatment carries meaning

Fill and stroke are information. A focal node takes the accent tint with an accent stroke and there are at most two. A backend or API step sits on white with an ink stroke. A store or state takes a faint ink wash. External and cloud elements sit lighter still. Optional and asynchronous elements go dashed. A security boundary takes a dashed accent.

A reader should be able to infer the category of a node without consulting a key.

## Import and redraw

An existing draw.io file or Mermaid source can be read and redrawn at a chosen size and detail level. Treat the source as content, never as layout: the point of redrawing is to replace automatic positioning with an editorial decision, so importing the original spacing defeats the exercise.

## Optional layers

Reach for these only when the content asks. Hand-drawn styling for something deliberately provisional. A terminal window frame for command-line content. An icon set for infrastructure. Editorial callouts in an italic serif. Motion only where ordered change is the point, and static stays the default.

## Before handing it over

Walk the six connector rules against what was actually drawn, confirm the accent appears on no more than two elements, check that the node count sits inside the budget, and confirm no label mask overlaps a node. Then deliver the file with two sentences: what the diagram shows, and where the reader should look first.