creating-mermaid-diagrams

NAGAGroup's avatarfrom NAGAGroup

Use when creating architecture diagrams, sequence diagrams, flowcharts, or any visual documentation from code analysis

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026⬇️3downloads
[Architecture Design]

When & Why to Use This Skill

This Claude skill automates the generation of professional Mermaid diagrams—including architecture, sequence, and flowcharts—directly from source code analysis. It streamlines technical documentation by ensuring precise mapping of code identifiers to visual elements while adhering to styling best practices and avoiding common syntax pitfalls.

Use Cases

  • Documenting Legacy Codebases: Automatically generate architecture and class diagrams to help developers quickly understand the structure and relationships of existing code.
  • Visualizing System Logic: Create detailed sequence diagrams to map out complex API interactions and data flows between different services or components.
  • Database & State Management: Generate ER diagrams and state machine visualizations directly from source code to maintain up-to-date technical documentation.
  • Technical Communication: Produce high-quality flowcharts and mind maps to explain complex business logic or project roadmaps to stakeholders and team members.
namecreating-mermaid-diagrams
descriptionUse when creating architecture diagrams, sequence diagrams, flowcharts, or any visual documentation from code analysis

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