Mermaid Diagram Patterns Skill

Mermaid Diagram Patterns

Create clear, professional Mermaid diagrams for technical documentation.

When to Use

Database schema visualization (ERD)
API interaction sequences
Process and workflow flowcharts
System architecture diagrams
State machines and user journeys
Decision trees

Diagram Type Selection

| Scenario | Diagram Type | Mermaid Syntax | |----------|--------------|----------------| | Database schema | ERD | erDiagram | | API calls | Sequence | sequenceDiagram | | Process flow | Flowchart | graph TD or flowchart TD | | Component architecture | Flowchart | graph LR | | State transitions | State | stateDiagram-v2 | | User workflow | Journey | journey | | Project timeline | Gantt | gantt | | Class relationships | Class | classDiagram |

ERD Pattern (Database Schema)

Use for entity definitions in technical design documents.

erDiagram
    %% Entity definitions with attributes
    PATIENT {
        uuid Id PK
        string FirstName
        string LastName
        string Email UK
        string Phone
        date DateOfBirth
        timestamp CreationTime
        uuid CreatorId FK
        boolean IsDeleted
    }

    DOCTOR {
        uuid Id PK
        string FullName
        string Specialization
        string Email UK
        string Phone
    }

    APPOINTMENT {
        uuid Id PK
        uuid PatientId FK
        uuid DoctorId FK
        timestamp AppointmentDate
        string Description
        smallint Status "0=Scheduled,1=Completed,2=Cancelled"
    }

    %% Relationships
    PATIENT ||--o{ APPOINTMENT : "has"
    DOCTOR ||--o{ APPOINTMENT : "conducts"

ERD Conventions

| Symbol | Meaning | |--------|---------| | PK | Primary Key | | FK | Foreign Key | | UK | Unique Key | | ||--o{ | One-to-Many | | ||--|| | One-to-One | | }o--o{ | Many-to-Many |

Sequence Diagram Pattern (API Interactions)

Use for documenting API flows in technical design.

sequenceDiagram
    autonumber
    participant C as Client
    participant API as API Gateway
    participant S as AppService
    participant DB as Database

    C->>+API: POST /api/app/patients
    API->>API: Validate JWT
    API->>+S: CreateAsync(dto)
    S->>S: Validate input
    S->>+DB: Insert Patient
    DB-->>-S: Patient entity
    S-->>-API: PatientDto
    API-->>-C: 201 Created

    Note over C,DB: Error handling
    C->>+API: POST /api/app/patients (invalid)
    API->>+S: CreateAsync(dto)
    S-->>-API: ValidationException
    API-->>-C: 400 Bad Request

Sequence Conventions

| Arrow | Meaning | |-------|---------| | ->> | Sync request | | -->> | Sync response | | --) | Async message | | + / - | Activation/deactivation |

Flowchart Pattern (Process Flow)

Use for business processes and decision flows.

flowchart TD
    A[Start: New Appointment Request] --> B{Patient Exists?}
    B -->|Yes| C[Load Patient]
    B -->|No| D[Create Patient]
    D --> C
    C --> E{Doctor Available?}
    E -->|Yes| F[Create Appointment]
    E -->|No| G[Show Available Slots]
    G --> H[User Selects Slot]
    H --> F
    F --> I[Send Confirmation]
    I --> J[End]

    style A fill:#e1f5fe
    style J fill:#c8e6c9
    style B fill:#fff3e0
    style E fill:#fff3e0

Flowchart Conventions

| Shape | Syntax | Use For | |-------|--------|---------| | Rectangle | [text] | Process/Action | | Diamond | {text} | Decision | | Stadium | ([text]) | Start/End | | Parallelogram | [/text/] | Input/Output | | Circle | ((text)) | Connector |

Architecture Diagram Pattern

Use for system component visualization.

graph LR
    subgraph Client
        UI[React App]
    end

    subgraph API["API Layer"]
        GW[API Gateway]
        AUTH[AuthServer]
    end

    subgraph Services["Application Services"]
        PS[PatientService]
        DS[DoctorService]
        AS[AppointmentService]
    end

    subgraph Data["Data Layer"]
        PG[(PostgreSQL)]
        RD[(Redis Cache)]
    end

    UI --> GW
    UI --> AUTH
    GW --> PS & DS & AS
    PS & DS & AS --> PG
    PS & DS & AS --> RD

    style PG fill:#336791,color:#fff
    style RD fill:#dc382d,color:#fff

State Diagram Pattern

Use for entity lifecycle documentation.

stateDiagram-v2
    [*] --> Scheduled: Create

    Scheduled --> Confirmed: Patient Confirms
    Scheduled --> Cancelled: Cancel

    Confirmed --> InProgress: Check-in
    Confirmed --> Cancelled: Cancel
    Confirmed --> NoShow: No Check-in

    InProgress --> Completed: Finish

    Completed --> [*]
    Cancelled --> [*]
    NoShow --> [*]

    note right of Scheduled: Initial state
    note right of Completed: Triggers billing

Styling Guidelines

Color Palette (ABP/Healthcare Theme)

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#1976d2',
    'primaryTextColor': '#fff',
    'primaryBorderColor': '#1565c0',
    'lineColor': '#424242',
    'secondaryColor': '#f5f5f5',
    'tertiaryColor': '#e3f2fd'
}}}%%

Styling Classes

style NodeId fill:#color,stroke:#color,color:#textcolor
classDef className fill:#color,stroke:#color
class NodeId className

Quality Checklist

[ ] Correct diagram type for the scenario
[ ] Clear, descriptive labels
[ ] Consistent arrow directions (TD=top-down, LR=left-right)
[ ] Proper relationship cardinality (ERD)
[ ] Activation bars for long operations (sequence)
[ ] Decision points clearly marked (flowchart)
[ ] Subgraphs for logical grouping
[ ] Comments for complex sections (%%)

Integration Points

This skill is used by:

backend-architect: ERD in technical-design.md, API sequences
business-analyst: Process flows in requirements.md, user journeys

References

Mermaid Official Docs
references/diagram-examples.md - Additional examples

Agent Skills: Mermaid Diagram Patterns

Install this agent skill to your local

Skill Files