creating-mermaid-diagrams

Overview

Core principle: general agent analyzes source first, then dispatches document-writer with precise spec.

Workflow

• Step 1: General agent explores/reads source code to get exact class names, methods, relationships
• Step 2: General agent creates detailed spec with precise identifiers from source
• Step 3: General agent dispatches document-writer with the spec
• Step 4: Review and fix any rendering issues

Diagram Types Reference

• flowchart TD/LR - process flows, decision trees
• sequenceDiagram - interactions over time, API calls
• classDiagram - class relationships, inheritance
• stateDiagram-v2 - state machines
• erDiagram - entity relationships, database schemas
• gantt - timelines, project schedules
• pie - proportions
• gitgraph - branch/merge visualization
• mindmap - hierarchical concepts
• timeline - chronological events

Common Syntax Pitfalls

• Sequence diagram participant labels with spaces must be quoted or Mermaid treats the second word as a new identifier.
  • ❌ participant Init as Device Init
  • ✅ participant Init as "Device Init"
• HTML entities (<, >, &, etc.) in sequence diagram messages break parsing because Mermaid expects the arrow token immediately after the message text.
  • ❌ Factory-->>Device: optional<UsmPoolContainer>
  • ✅ Factory-->>Device: optional UsmPoolContainer
• Avoid raw < or > in any message text―Mermaid often misinterprets them as syntax, even when not encoded.
  • ❌ A->>B: Returns List<Item>
  • ✅ A->>B: Returns List of Items
• Literal \n does not create newlines inside flowchart node labels; use <br> for line breaks.
  • ❌ A["Line 1\nLine 2"]
  • ✅ A["Line 1<br>Line 2"]
• Escape or avoid <T> generics in text (use T or HTML entities) when they are required in class/flow descriptions outside of sequence messages.
• Alt/else blocks need explicit structure with proper end
• Node IDs can't have special characters

Color & Styling Best Practices

• Always specify text color with fill: style Node fill:#color,color:#textcolor
• Suggested palette with tested contrast (light backgrounds get color:#000000, dark get color:#ffffff)
• Example palette:
  • Light fills: #e1f5fe, #f3e5f5, #fff3e0, #e8f5e9 → use color:#000000
  • Dark fills: #1565c0, #6a1b9a, #e65100, #2e7d32 → use color:#ffffff

Output Convention

• Save to docs/diagrams/ directory
• Use markdown with fenced mermaid code blocks
• Follow existing file format (see neo-architecture.md as reference)

Common Mistakes

• Dispatching document-writer without source analysis first
• Using generic placeholders instead of exact identifiers from code
• Forgetting text color on styled nodes
• Unquoted labels in sequence diagrams
• Raw angle brackets in diagram text