Diagramagic

You are writing SVG. The diag: extensions handle layout and sizing — they do not replace your responsibility to create rich, detailed, information-dense diagrams. Write with the same visual quality and detail you would if generating raw SVG. The diag: features save you from coordinate math, not from doing the actual design work.

Layout Rules

• Use <diag:diagram> root with xmlns="http://www.w3.org/2000/svg" and xmlns:diag="https://diagramagic.ai/ns"
• Use diag:flex for layout structure (stacks, rows, grids of cards) — but fill those containers with rich, detailed content
• Use diag:graph for auto-layout when topology matters (flowcharts, dependency graphs) — but treat it as scaffolding, not the complete design
• Choose graph layout deliberately:
  • layout="layered" for flowcharts, request pipelines, dependency chains
  • layout="radial" for hub-and-spoke systems
  • layout="circular" for peer/cyclic systems
• Choose routing deliberately:
  • routing="auto" as default
  • routing="ortho"/"polyline" for dense technical diagrams where readability matters most
  • routing="curved" for lighter conceptual diagrams; avoid it for dense feedback-heavy graphs
• Keep graph nodes content-rich (title + details), not just single-line labels
• For title+body graph nodes, set diag:node gap="6" to gap="12" to avoid cramped text blocks
• If graph output gets crowded, split into multiple subgraphs with diag:include or switch to a hybrid flex + arrows structure
• Use diag:wrap="true" on <text> for multi-line text (wrapping is a text feature, not a diag:node feature)
• Use diag:arrow with id-tagged elements for connectors
• Use label-rotate="horizontal" for readable arrow/edge labels by default; use follow only when line-following text is intentionally desired
• Use diag:anchor for precise named points (sequence diagrams, etc.)
• Use diag:include to compose large diagrams from sub-files
• Use diag:template when you have 3+ visually identical elements (e.g., entity cards, service boxes)
• Mix raw SVG freely: <rect>, <line>, <circle>, <path> for decorative elements, region backgrounds, custom shapes
• Do NOT stop at first compile — iterate until the render matches intent
• layout="circular" and layout="radial" require system Graphviz (dot) on PATH; layered layout can fall back if unavailable

Error Recovery

• E_PARSE_XML: fix malformed XML and retry
• E_SVGPP_SEMANTIC: fix svg++ structure/ids and retry
• E_INCLUDE_ID_COLLISION: rename conflicting ids between parent and included files
• E_GRAPH_UNKNOWN_NODE: ensure every diag:edge from/to id exists as a diag:node in the same graph
• E_GRAPH_SELF_EDGE: remove or redesign self-referential diag:edge (from == to)
• E_GRAPH_TOO_LARGE: split the graph into smaller sections or compose with diag:include
• Always attempt at least one fix before asking for help