Mermaid Diagrams Skill

This skill provides patterns and best practices for creating high-quality Mermaid diagrams that accurately document software architecture.

When to Use

• •Creating C4 zoom-in diagrams for services
• •Documenting sequence flows with parallel execution
• •Visualizing component dependencies
• •Building flowcharts for decision logic

Diagram Types

1. Sequence Diagrams (Temporal Flow)

Best for showing how components interact over time.

sequenceDiagram
    autonumber
    participant A as ComponentA
    participant B as ComponentB
    participant C as ExternalService

    A->>B: method_call(args)
    activate B

    par Parallel Operations
        B->>C: async_operation_1()
        C-->>B: result_1
    and
        B->>C: async_operation_2()
        C-->>B: result_2
    end

    B-->>A: combined_result
    deactivate B

Key elements:

• •autonumber: Adds step numbers for reference
• •activate/deactivate: Shows component lifecycle
• •par/and/end: Visualizes parallel execution
• •Note over X: Adds contextual annotations

2. Flowchart (Component Diagram)

Best for showing static dependencies between components.

flowchart TB
    subgraph Service["ServiceName"]
        direction TB
        method1["public_method()"]
        method2["_private_method()"]
        method1 --> method2
    end

    subgraph Interfaces["Abstractions"]
        direction LR
        IInterface1([Interface1])
        IInterface2[(Interface2)]
    end

    method1 -.->|uses| IInterface1
    method2 -.->|calls| IInterface2

    %% Styling
    style Service fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#eaeaea
    style Interfaces fill:#0f3460,stroke:#1a1a2e,stroke-width:2px,color:#eaeaea
    style method1 fill:#e94560,stroke:#1a1a2e,color:#fff
    style method2 fill:#533483,stroke:#1a1a2e,color:#fff

Key elements:

• •subgraph: Groups related components
• •direction TB/LR: Controls flow direction
• •-.->: Dashed arrows for dependencies
• •style: Custom colors per node

3. C4 Container Diagram

For high-level system architecture:

flowchart TB
    subgraph System["System Boundary"]
        subgraph Layer1["Presentation Layer"]
            UI[Web UI]
            CLI[CLI Tool]
        end

        subgraph Layer2["Service Layer"]
            SVC[Core Service]
        end

        subgraph Layer3["Data Layer"]
            DB[(Database)]
            Cache[(Cache)]
        end
    end

    UI --> SVC
    CLI --> SVC
    SVC --> DB
    SVC --> Cache

    %% Layer colors
    style Layer1 fill:#2d3436,stroke:#636e72
    style Layer2 fill:#0984e3,stroke:#74b9ff
    style Layer3 fill:#00b894,stroke:#55efc4

Styling Guidelines

Color Palette (Dark Theme)

Node Shapes

Best Practices

1. •Match the code: Use actual method/class names from the implementation
2. •Show parallelism: Use par blocks for concurrent operations
3. •Layer by abstraction: Group by architectural layer (UI, Service, Data)
4. •Consistent styling: Apply the same color scheme across all diagrams
5. •Add context: Use Note annotations for non-obvious logic
6. •Test rendering: Verify in mermaid.live before committing

Documentation Template

When documenting a service, include:

1. •Responsibility: One-paragraph description of the component's role
2. •Sequence Diagram: For the primary use case flow
3. •Component Diagram: For static dependencies
4. •Method Table: Key methods with brief descriptions

Verification Checklist

• • Diagram renders without errors in Mermaid preview
• • All node names match actual code identifiers
• • Parallel operations are properly visualized
• • Colors are consistent with the project palette
• • Arrows correctly show dependency direction