Mermaid to SVG

What this skill does

# 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:**

```xml
<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)