Mermaid to SVG

Mermaid to SVG

Convert Mermaid diagram definitions into hand-crafted SVG markup with professional layout and consistent styling. This skill produces standalone SVG files — no rendering engine or JavaScript required.

Supported Diagram Types

Mermaid Type	Layout Direction	Primary Shape
flowchart / graph	TD (top-down) or LR (left-right)	Rounded rectangles, diamonds, circles
sequenceDiagram	Left-to-right actors, top-down messages	Rectangles for actors, arrows for messages
classDiagram	Grid or hierarchical	Three-section rectangles
stateDiagram-v2	Hierarchical	Rounded rectangles, filled circles for start/end
erDiagram	Grid	Rectangles with attribute lists
mindmap	Radial from center	Rounded rectangles, varying sizes by depth

Conversion Workflow

1. Parse the Mermaid Source

Extract the structural elements from the Mermaid definition:

• Nodes — identifier, display label, shape hint ([], {}, (), (()), [[]], >], [/\])
• Edges — source, target, label, line style (-->, ---, -.->, ==>)
• Subgraphs — grouping containers with optional titles
• Directives — direction, classDef, style, click (ignore click)
• Diagram-specific — actors, messages, states, entities, relationships

2. Compute Layout

Apply layout rules from references/layout-patterns.md. The core principles:

Grid system. Place nodes on a virtual grid. Cell size adapts to the largest node plus gutter. Default gutter: 40px horizontal, 50px vertical. Minimum node-to-node distance: 120px.

Node sizing. Measure text length (approximate 8px per character at 14px font, 6.5px per character at 12px font). Add horizontal padding of 24px per side, vertical padding of 14px per side. Minimum node width: 80px. Minimum node height: 40px.

Rank assignment. For directed graphs, assign ranks (layers) using longest-path from sources. Nodes with no predecessors start at rank 0. Within each rank, order nodes to minimize edge crossings — place nodes adjacent to their most-connected neighbor in the previous rank.

Edge routing. Use orthogonal (right-angle) paths routed through inter-node channels. Edges leave from the nearest side of the source node and enter the nearest side of the target. When multiple edges share a channel, offset them by 6px to prevent overlap. Consult references/layout-patterns.md for routing algorithms per diagram type.

Subgraph containers. Compute the bounding box of all contained nodes, then add 20px internal padding and a 30px top margin for the title. Nest subgraphs before placing top-level nodes.

3. Generate SVG

Build the SVG document following these conventions:

Document structure:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {W} {H}"
     font-family="Inter, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
  <defs>
    <!-- arrowheads, filters, gradients -->
  </defs>
  <g class="edges">...</g>
  <g class="nodes">...</g>
  <g class="labels">...</g>
</svg>

Sizing. Set viewBox to the computed layout bounds plus 30px margin on all sides. Omit explicit width/height to allow responsive scaling, or set them to match viewBox if fixed dimensions are preferred.

Rendering order. Draw edges first (behind), then nodes, then labels. This prevents edges from overlapping node fills.

Apply the style system from references/style-guide.md:

• Node fills use muted cool palette colors with 2px borders in a slightly darker shade of the same hue
• Text is #334155 (slate-700) at 14px for node labels, 12px for edge labels, 18px for titles
• Edges are #94a3b8 (slate-400) with 1.5px stroke, arrow markers in matching color
• Subgraph containers use #f8fafc fill with #cbd5e1 dashed border
• Use warm accent (#f59e0b / #d97706) sparingly for decision nodes, error states, or key highlights

Text layout. Center text horizontally and vertically within nodes using text-anchor="middle" and dominant-baseline="central". For multi-line text, use multiple <tspan> elements with dy="1.3em" line spacing. Wrap text that exceeds node width minus padding.

4. Refine and Validate

• Verify no overlapping nodes or edges
• Confirm all edge endpoints connect to correct node boundaries
• Check text fits within nodes (resize nodes if needed)
• Ensure arrowheads render at correct positions and orientations
• Validate SVG is well-formed XML

Shape Mapping

Map Mermaid shape syntax to SVG elements:

Mermaid Syntax	Shape	SVG Element
[text]	Rectangle	<rect rx="6">
(text)	Rounded rectangle	<rect rx="16">
([text])	Stadium/pill	<rect rx="{h/2}">
{text}	Diamond	<polygon> rotated square
((text))	Circle	<circle>
[[text]]	Subroutine	Double-bordered <rect>
[/text/]	Parallelogram	<polygon> with skewed sides
>text]	Asymmetric	<polygon> flag shape
[(text)]	Cylinder	<path> with elliptical top/bottom

Edge Styles

Mermaid Syntax	Style	SVG Attributes
-->	Solid with arrow	stroke-dasharray: none, marker-end
---	Solid no arrow	stroke-dasharray: none
-.->	Dashed with arrow	stroke-dasharray: 6 4
==>	Thick with arrow	stroke-width: 3
~~~	Invisible	stroke: none (layout only)
--text-->	Labeled	Add <text> at edge midpoint

Key Conventions

• Always include xmlns on the root <svg> element for standalone files
• Use id attributes on nodes matching their Mermaid identifiers for traceability
• Define arrowhead markers in <defs> and reference via marker-end="url(#arrow)"
• For sequence diagrams, use lifeline <line> elements with stroke-dasharray: 4 4
• For class diagrams, partition the node rectangle into three sections with horizontal <line> dividers
• For ER diagrams, render crow's foot notation with custom marker paths

Additional Resources

Reference Files

For detailed patterns and specifications, consult:

• references/layout-patterns.md — Layout algorithms per diagram type: rank assignment, edge routing, crossing minimization, subgraph nesting, sequence diagram column allocation, and grid placement strategies
• references/style-guide.md — Complete color palette, typography scale, node styling rules, edge styling, shadow/filter definitions, and accessibility considerations
• references/svg-elements.md — Copy-ready SVG snippets for every node shape, edge style, arrowhead marker, text layout pattern, and diagram-specific elements (lifelines, crow's feet, state indicators)