| name | Mermaid to SVG |
| version | 0.1.0 |
| description | This skill should be used when the user asks to "convert mermaid to SVG", "render this mermaid diagram", "create an SVG from mermaid", "draw this diagram as SVG", "generate SVG from mermaid", "make an SVG diagram", "turn this mermaid into an image", "layout this diagram", or any task involving converting Mermaid diagram syntax into hand-crafted SVG markup. Produces clean, professionally styled SVGs with logical layout, efficient edge routing, and consistent visual design. |
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>
</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 strategiesreferences/style-guide.md — Complete color palette, typography scale, node styling rules, edge styling, shadow/filter definitions, and accessibility considerationsreferences/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)
