creating-mermaid-flowcharts

Original source / Raw SKILL.md

---
name: creating-mermaid-flowcharts
description: Use when creating or editing Mermaid flowchart diagrams, encountering parse errors, or unsure about node shapes, connection syntax, or styling - provides syntax guardrails using modern shape syntax for Obsidian-compatible diagrams
---

# Creating Mermaid Flowcharts

## Overview

Mermaid has strict syntax rules: node identifiers must be simple alphanumeric (a, b, node1), while labels can contain any text. Modern `@{ shape: ..., label: "..." }` syntax is preferred over legacy shorthand for clarity and reliability.

## When to Use

**Use this skill when:**
- Creating new Mermaid flowchart diagrams
- Encountering parse errors ("Expecting 'SEMI'", syntax errors)
- Converting diagrams from other formats (dot, graphviz)
- Unsure about shape syntax, connection types, or styling
- Need to add colors or classes to nodes

**Don't use for:**
- Other Mermaid diagram types (sequence, gantt, class diagrams)
- Complex state machines (use stateDiagram instead)

## Quick Reference

### Common Shapes

| Shape | Modern Syntax | Use Case |
|-------|---------------|----------|
| Diamond | `a@{ shape: diam, label: "Decision?" }` | Decisions, questions |
| Rectangle | `a@{ shape: rect, label: "Action" }` | Process steps, actions |
| Stadium | `a@{ shape: stadium, label: "Start/End" }` | Start/end points (preferred) |
| Circle | `a@{ shape: circle, label: "Start" }` | Alternative for start/end |
| Rounded | `a@{ shape: rounded, label: "Event" }` | Events, states |

**Note:** Use `stadium` for start/end nodes (more readable). Use `circle` for compact diagrams.

See [mermaid-flowchart-reference.md](mermaid-flowchart-reference.md) for complete shape list.

### Connections

| Type | Syntax | Example |
|------|--------|---------|
| Solid arrow | `-->` | `a --> b` |
| Labeled arrow | `-->\|label\|` | `a -->\|yes\| b` |
| Dotted | `-.->` | `a -.-> b` |
| Thick | `==>` | `a ==> b` |

### Styling

| Pattern | Syntax | Purpose |
|---------|--------|---------|
| Define class | `classDef name fill:#color` | Create reusable style |
| Apply class | `node:::className` | Style specific node |

## Core Pattern

**❌ WRONG - Spaces in identifiers:**

```mermaid
graph LR
    "New constraint revealed?" --> "Return to Phase 1"
```

**Error:** Identifiers can't have spaces. Parse will fail.

**✅ CORRECT - Simple IDs + Labels:**

```mermaid
graph LR
    a@{ shape: diam, label: "New constraint revealed?" }
    b@{ shape: rect, label: "Return to Phase 1" }
    a -->\|yes\| b
```

## Implementation

### Step 1: Choose Graph Direction

```mermaid
graph TD    ← Top-down (vertical flow)
graph LR    ← Left-right (horizontal flow)
```

**Choose based on flow:**
- `TD` (or `TB`) = Top-down for sequential processes, workflows
- `LR` = Left-right for timelines, state transitions
- `BT` = Bottom-up (rare)
- `RL` = Right-left (rare)

### Step 2: Define Nodes with Modern Syntax

```mermaid
graph TD
    a@{ shape: diam, label: "Your question here?" }
    b@{ shape: rect, label: "Your action here" }
```

**Rules:**
- **Identifier** = simple alphanumeric only (a, b, node1, step2)
- **Label** = any text in quotes after `label:`
- **Shape** = from reference list (diam, rect, circle, stadium, etc.)

### Step 3: Connect Nodes

```mermaid
    a -->\|yes\| b
    a -->\|no\| c
```

**Always label decision branches** (yes/no, true/false, etc.)

### Step 4: Apply Styling (Optional)

```mermaid
    classDef highlight fill:#ffcccc
    classDef success fill:#ccffcc

    b:::highlight
    c:::success
```

**Define classes before applying them.** Each node can only have one class applied.

**Styling patterns:**
- Multiple end nodes: Use separate end nodes when paths have different outcomes; use single end node when all paths converge naturally
- Decision nodes: Keep neutral (no styling) or style based on their context (error flow vs success flow)
- Need composite styles? Create a new class combining properties rather than applying multiple classes

## Common Mistakes

### Mistake 1: Spaces in Identifiers

**Problem:**

```mermaid
"My Node" --> "Other Node"
```

**Fix:** Use simple IDs with labels:

```mermaid
a@{ shape: rect, label: "My Node" } --> b@{ shape: rect, label: "Other Node" }
```

### Mistake 2: Missing Edge Labels on Decisions

**Problem:**

```mermaid
decision --> optionA
decision --> optionB
```

**Fix:** Label your decision branches:

```mermaid
decision -->\|yes\| optionA
decision -->\|no\| optionB
```

### Mistake 3: Applying Undefined Classes

**Problem:**

```mermaid
a:::highlight  ← Class never defined
```

**Fix:** Define before applying:

```mermaid
classDef highlight fill:#ffcccc
a:::highlight
```

### Mistake 4: Mixing Legacy and Modern Syntax

**Problem:**

```mermaid
a@{ shape: diam, label: "Modern" }
b{"Legacy"}  ← Inconsistent
```

**Fix:** Use modern syntax consistently throughout diagram.

## Debugging Checklist

When you get parse errors:
- [ ] All identifiers are simple alphanumeric (no spaces, no special chars)
- [ ] Modern `@{ shape: ..., label: "..." }` syntax used consistently
- [ ] Decision nodes have labeled edges
- [ ] Classes defined before applied
- [ ] No trailing semicolons or extra whitespace
- [ ] Graph direction specified (LR, TD, etc.)

## Real-World Impact

Using modern syntax eliminates 90% of parse errors. Proper identifier naming allows diagrams to render on first attempt in Obsidian without web lookups or trial-and-error debugging.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### mermaid-flowchart-reference.md

```markdown
# Mermaid Flowchart Complete Shape Reference

This is a comprehensive reference for all Mermaid flowchart shapes using modern syntax.

## Complete Shape List

| Semantic Name | Shape Name | Short Name | Modern Syntax | Use Case |
|---------------|------------|------------|---------------|----------|
| Start | Circle | `circle` | `a@{ shape: circle, label: "Start" }` | Starting point |
| Start | Small Circle | `sm-circ` | `a@{ shape: sm-circ, label: "Start" }` | Small starting point |
| Stop | Double Circle | `dbl-circ` | `a@{ shape: dbl-circ, label: "Stop" }` | Stop point |
| Stop | Framed Circle | `fr-circ` | `a@{ shape: fr-circ, label: "Stop" }` | Stop point |
| Terminal Point | Stadium | `stadium` | `a@{ shape: stadium, label: "Terminal" }` | Terminal point |
| Process | Rectangle | `rect` | `a@{ shape: rect, label: "Process" }` | Standard process |
| Subprocess | Framed Rectangle | `fr-rect` | `a@{ shape: fr-rect, label: "Subprocess" }` | Subprocess |
| Decision | Diamond | `diam` | `a@{ shape: diam, label: "Decision?" }` | Decision/question |
| Event | Rounded Rectangle | `rounded` | `a@{ shape: rounded, label: "Event" }` | Event |
| Prepare | Hexagon | `hex` | `a@{ shape: hex, label: "Prepare" }` | Preparation step |
| Data Input/Output | Lean Right | `lean-r` | `a@{ shape: lean-r, label: "Input" }` | Input/output |
| Data Input/Output | Lean Left | `lean-l` | `a@{ shape: lean-l, label: "Output" }` | Output/input |
| Document | Document | `doc` | `a@{ shape: doc, label: "Document" }` | Document |
| Multi-Document | Stacked Document | `docs` | `a@{ shape: docs, label: "Docs" }` | Multiple documents |
| Database | Cylinder | `cyl` | `a@{ shape: cyl, label: "Database" }` | Database storage |
| Disk Storage | Lined Cylinder | `lin-cyl` | `a@{ shape: lin-cyl, label: "Disk" }` | Disk storage |
| Direct Access Storage | Horizontal Cylinder | `h-cyl` | `a@{ shape: h-cyl, label: "Storage" }` | Direct access |
| Manual Input | Sloped Rectangle | `sl-rect` | `a@{ shape: sl-rect, label: "Manual" }` | Manual input |
| Manual Operation | Trapezoid Top | `trap-t` | `a@{ shape: trap-t, label: "Manual" }` | Manual task |
| Manual File | Flipped Triangle | `flip-tri` | `a@{ shape: flip-tri, label: "File" }` | Manual file |
| Priority Action | Trapezoid Bottom | `trap-b` | `a@{ shape: trap-b, label: "Priority" }` | Priority action |
| Comment | Curly Brace | `brace` | `a@{ shape: brace, label: "Comment" }` | Comment |
| Comment Right | Curly Brace Right | `brace-r` | `a@{ shape: brace-r, label: "Comment" }` | Right comment |
| Comment Both | Curly Braces | `braces` | `a@{ shape: braces, label: "Comment" }` | Both sides comment |
| Junction | Filled Circle | `f-circ` | `a@{ shape: f-circ, label: "Join" }` | Junction point |
| Fork/Join | Filled Rectangle | `fork` | `a@{ shape: fork, label: "Fork" }` | Fork/join |
| Collate | Hourglass | `hourglass` | `a@{ shape: hourglass, label: "Collate" }` | Collate operation |
| Extract | Triangle | `tri` | `a@{ shape: tri, label: "Extract" }` | Extraction |
| Card | Notched Rectangle | `notch-rect` | `a@{ shape: notch-rect, label: "Card" }` | Card |
| Delay | Half-Rounded Rectangle | `delay` | `a@{ shape: delay, label: "Delay" }` | Delay |
| Display | Curved Trapezoid | `curv-trap` | `a@{ shape: curv-trap, label: "Display" }` | Display |
| Divided Process | Divided Rectangle | `div-rect` | `a@{ shape: div-rect, label: "Divided" }` | Divided process |
| Internal Storage | Window Pane | `win-pane` | `a@{ shape: win-pane, label: "Storage" }` | Internal storage |
| Lined Document | Lined Document | `lin-doc` | `a@{ shape: lin-doc, label: "Document" }` | Lined document |
| Lined Process | Lined Rectangle | `lin-rect` | `a@{ shape: lin-rect, label: "Process" }` | Lined process |
| Loop Limit | Notched Pentagon | `notch-pent` | `a@{ shape: notch-pent, label: "Loop" }` | Loop limit |
| Multi-Process | Stacked Rectangle | `st-rect` | `a@{ shape: st-rect, label: "Processes" }` | Multiple processes |
| Odd | Odd | `odd` | `a@{ shape: odd, label: "Odd" }` | Odd shape |
| Paper Tape | Flag | `flag` | `a@{ shape: flag, label: "Paper" }` | Paper tape |
| Stored Data | Bow Tie Rectangle | `bow-rect` | `a@{ shape: bow-rect, label: "Data" }` | Stored data |
| Summary | Crossed Circle | `cross-circ` | `a@{ shape: cross-circ, label: "Summary" }` | Summary |
| Tagged Document | Tagged Document | `tag-doc` | `a@{ shape: tag-doc, label: "Tagged" }` | Tagged document |
| Tagged Process | Tagged Rectangle | `tag-rect` | `a@{ shape: tag-rect, label: "Tagged" }` | Tagged process |
| Text Block | Text Block | `text` | `a@{ shape: text, label: "Text" }` | Text block |
| Com Link | Lightning Bolt | `bolt` | `a@{ shape: bolt, label: "Link" }` | Communication link |

## Connection Types

| Type | Syntax | Visual | Use Case |
|------|--------|--------|----------|
| Solid arrow | `a --> b` | ──> | Standard flow |
| Labeled arrow | `a -->\|label\| b` | ─label─> | Decision branches |
| Dotted arrow | `a -.-> b` | ····> | Optional/weak |
| Thick arrow | `a ==> b` | ══> | Emphasis |
| Open link | `a --- b` | ─── | Undirected |
| Dotted link | `a -.- b` | ···· | Weak connection |
| Thick link | `a === b` | ═══ | Strong connection |
| Chained | `a --> b --> c` | Multiple hops | Sequential flow |

## Styling Reference

### Defining Classes

```mermaid
classDef className fill:#color,stroke:#color,stroke-width:2px,color:#textcolor
```

**Common color patterns:**

```mermaid
classDef success fill:#ccffcc,stroke:#00cc00
classDef error fill:#ffcccc,stroke:#cc0000
classDef warning fill:#ffffcc,stroke:#cccc00
classDef info fill:#ccccff,stroke:#0000cc
```

### Applying Classes

**To single node:**

```mermaid
a:::className
```

**To multiple nodes:**

```mermaid
a:::className
b:::className
c:::className
```

## Graph Directions

| Direction | Code | Layout |
|-----------|------|--------|
| Left to Right | `graph LR` | Horizontal |
| Right to Left | `graph RL` | Horizontal (reverse) |
| Top to Bottom | `graph TD` or `graph TB` | Vertical |
| Bottom to Top | `graph BT` | Vertical (reverse) |

## Example: Complete Workflow

```mermaid
graph TD
    start@{ shape: circle, label: "Start" }
    input@{ shape: lean-r, label: "Get Input" }
    process@{ shape: rect, label: "Process Data" }
    decision@{ shape: diam, label: "Valid?" }
    output@{ shape: doc, label: "Generate Report" }
    error@{ shape: rounded, label: "Error Handler" }
    stop@{ shape: dbl-circ, label: "End" }

    start --> input
    input --> process
    process --> decision
    decision -->|yes| output
    decision -->|no| error
    output --> stop
    error --> stop

    classDef successPath fill:#ccffcc
    classDef errorPath fill:#ffcccc

    output:::successPath
    error:::errorPath
```

## Obsidian Compatibility Notes

- Modern `@{ shape: ... }` syntax works in Obsidian with Mermaid plugin v10+
- If using older Obsidian versions, may need to use legacy syntax
- Always test diagrams in your specific Obsidian environment

## Source

Based on Mermaid documentation: <https://docs.mermaidchart.com/mermaid-oss/syntax/flowchart.html>

```