Diagram Design

A diagram earns its place when the arrangement itself carries meaning that a sentence or a list cannot carry as fast.

That is the whole test. Boxes-and-arrows restating a numbered list is slower than the list. A flowchart of a linear three-step process is worse than three sentences. Before drawing anything, say what the reader will understand from the shape that they would not get from the prose.

If the answer is "nothing," write the prose.

The standard

The highest-quality move is usually deletion. Every node earns its place. Target density around 4/10 — a diagram that fills its frame is almost always doing too much.

The accent color is reserved for the one or two things the reader should look at first. Everything else is ink and hairlines.

(This standard is adapted from cathrynlavery/diagram-design, MIT. See Credits.)

Choosing a form

Match the form to the relationship being shown, not to the data you happen to have.

If the answer is "several of these," the diagram is doing too much. Split it. Two clear diagrams beat one complete one — a reader who has to decode a diagram has already lost the time the diagram was meant to save.

For per-form construction rules — what to label, where to place the accent, how to handle overflow — read references/diagram-families.md.

Output

Inline SVG in the document. Not a linked image, not a canvas, not a client-side renderer.

Inline SVG is the only form that scales into print without blurring, inherits the document's tokens, stays selectable and searchable, and survives being emailed as a single file.

Every diagram:

<svg role="img" aria-labelledby="dg-ingest-title dg-ingest-desc" viewBox="0 0 720 380">
  <title id="dg-ingest-title">Ingestion path</title>
  <desc id="dg-ingest-desc">Events enter through the gateway, buffer in the queue, and land in the warehouse. The queue is the only component without a failover.</desc>
  ...
</svg>

<title> first, unique IDs prefixed with the diagram's slug, and a viewBox on every SVG. The <desc> states what the arrangement shows — including the thing the accent is pointing at. See core/a11y.md.

Inline or <img> changes the rules

An SVG referenced through <img src="…"> — a README banner, an email, an embed on a site you do not control — renders as an isolated document. The host page's custom properties never reach it, so fill="var(--accent)" resolves to nothing and the shape disappears.

Decide the destination before drawing, because it is not a cosmetic difference — the same file cannot do both. For the second case, write literal colours for the light reading into the shapes, then add a <style> block inside the SVG whose @media (prefers-color-scheme: dark) rule overrides those fills and strokes by class, so one file serves both host themes without reaching for the page's tokens.

Visual rules

The token contract is in core/tokens.md and applies in full. Diagram-specific rules:

• One accent. Reserved for the one or two elements the reader should see first — the bottleneck, the boundary, the thing that changed. An accent on every node is the same as no accent.
• Hairlines. 1px strokes, var(--rule) for structure and var(--rule-strong) for boundaries. Thick borders read as UI chrome.
• No shadows, no gradients, no glow. Depth comes from grouping and whitespace.
• Everything on a 4px grid. Positions, sizes, gaps. Off-grid geometry is the single most reliable tell of an auto-generated diagram.
• Three type roles. var(--display) for the diagram title, var(--sans) for node labels, var(--mono) for technical identifiers, ports, and versions. Nothing else.
• Label every edge that isn't obvious. An unlabelled arrow means "leads to," and nothing else. If it means "on failure," "async," or "read-only," say so.
• Direction is a decision. Left-to-right for process and time. Top-to-bottom for hierarchy and layers. Do not mix within one diagram.
• No orphan nodes. Anything unconnected either needs an edge or does not belong.
• Never encode meaning in lightness alone. Every theme is legible, and a dark theme inverts which fill reads heavier, so "darker means more" breaks the moment the theme changes. Legends name each encoding in words ("dashed: outside Platform"), never only by swatch.
• Mark the structure. g.node (node-focal, node-external, node-muted), path.edge, g.edge-label, g.boundary, g.legend, g.callout, g.annotation — the classes are what scripts/check_diagrams.py measures.

Full geometry, node, edge, and callout specifications are in references/primitives.md.

Mermaid is an input, not an output

Mermaid is a good notation. Its default rendering is not — stock output brings its own fonts, its own colors, and its own spacing, none of which know about the document they land in. Shipping that into a designed document is visible immediately.

So: accept Mermaid as a source, convert it to a themed SVG, ship the SVG.

The rule underneath: auto-layout is acceptable when the arrangement is arbitrary, and unacceptable when the arrangement is the message.

See references/mermaid-bridge.md for the renderer, its theme bridge, and its coverage limits.

Sizing and audience

Two dials worth setting deliberately, because they change what belongs in the diagram:

Size — doc-inline (fits a text column, ~720px wide), full-width (~1100px), print-portrait, print-landscape. A diagram drawn for full width and dropped into a text column becomes unreadable rather than smaller.

Audience — an engineer diagram can name protocols, ports, and versions; an executive diagram cannot, and showing them is not rigor, it is noise. When both audiences need it, make two diagrams from the same model rather than one that half-serves each.

Before delivering

• The arrangement carries meaning prose could not carry as fast.
• Every node earns its place; nothing is there for symmetry.
• The accent marks one or two things, not a category.
• Every non-obvious edge is labelled.
• Geometry sits on the 4px grid.
• viewBox, <title> first, <desc>, unique IDs.
• Legible in grayscale and at print width.
• No color-only encoding.
• No shadows, gradients, or glow.
• Renders correctly at the intended size, not just at authoring size.
• Legends name every encoding in words; nothing relies on lightness alone.
• scripts/check_diagrams.py figure.svg reports no findings.

Paths in this skill

core/…, scripts/… and templates/… are relative to this skill's directory — the folder that contains this SKILL.md — not to your working directory. Each skill carries its own copy, so it works however it was installed. Prefix them with that directory:

node "<skill-dir>/scripts/render_diagram.mjs" in.mmd --id x --title "…" --desc "…" --out x.svg
python3 "<skill-dir>/scripts/check_diagrams.py" x.svg          # markup and geometry rules
python3 "<skill-dir>/scripts/import_diagram.py" old.drawio     # structure only, as JSON

Reference files

• references/diagram-families.md — per-form construction rules and failure modes.
• references/primitives.md — node, edge, label, callout, and grid specifications.
• references/mermaid-bridge.md — the Mermaid renderer, theme bridging, coverage limits.
• references/importing.md — draw.io and Mermaid import: the neutral model, the safety caps, and redrawing.

Credits

The editorial standard here — deletion as the highest-quality move, every node earning its place, one accent for the one or two things that matter, density around 4/10, hairlines and a 4px grid — is adapted from cathrynlavery/diagram-design (MIT), which established it for Claude Code.

This skill differs in scope: it is one member of a document design system, so its diagrams consume the same core/ tokens as the reports, charts, and decks they sit inside, rather than carrying a diagram-specific style of their own.