svg-diagram

SVG Diagramming Conventions

Output location and referencing

Diagrams go in SVG, never ASCII art. That rule decides whether to draw; this skill covers how, starting with where the file lands.

• Put the file in an assets/ directory next to the document (e.g. docs/foo.md → docs/assets/foo-arch.svg)
• Reference it from markdown with a relative path, ![title](assets/xxx.svg). Do not inline SVG XML.
• When data in the document changes, the corresponding SVG must be updated too. A figure that contradicts the prose beside it is worse than no figure

Core principles

Get it right on the first pass

The first SVG you generate must already satisfy every item in the verification checklist at the end of this document. Do not rely on user feedback to fix basic layout problems (spacing, padding, alignment, viewBox clipping). After generating, walk the checklist yourself and fix anything you find before showing the result.

No overlapping elements

• Text must not sit on top of boxes or lines
• Lines must not cut through boxes (unless the line is an arrow terminating at that box)
• Keep 10–20px between text and lines
• For spacing between sibling/adjacent boxes see the "Block spacing" section below (single standard: ≥25px, 25–30px recommended)
• Put color-key legends outside the diagram body (bottom or side), never overlapping the content area

<!-- ✅ Correct: label sits beside the line -->
<path d="M35,200 C 35,120 ..." .../>
<text x="55" y="200">Label text</text>  <!-- 20px clearance -->

<!-- ❌ Wrong: label sits on the line -->
<text x="35" y="200">Label text</text>

Visual balance

The left and right halves should carry similar visual weight; add or remove annotation boxes to even them out.

Layout rules

Centering

content width = right edge of rightmost element - left edge of leftmost element
left margin   = (viewBox width - content width) / 2

Center the title on the content center, not the viewBox center (they differ whenever the content is asymmetric):