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.