Mermaid Diagramming

Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.

Core Syntax Structure

All Mermaid diagrams follow this pattern:

diagramType
  definition content

Key principles:

First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
Use %% for comments
Line breaks and indentation improve readability but aren't required
Unknown words break diagrams; parameters fail silently

Diagram Type Selection Guide

Choose the right diagram type:

Class Diagrams - Domain modeling, OOP design, entity relationships
- Domain-driven design documentation
- Object-oriented class structures
- Entity relationships and dependencies
Sequence Diagrams - Temporal interactions, message flows
- API request/response flows
- User authentication flows
- System component interactions
- Method call sequences
Flowcharts - Processes, algorithms, decision trees
- User journeys and workflows
- Business processes
- Algorithm logic
- Deployment pipelines
Entity Relationship Diagrams (ERD) - Database schemas
- Table relationships
- Data modeling
- Schema design
C4 Diagrams - Software architecture at multiple levels
- System Context (systems and users)
- Container (applications, databases, services)
- Component (internal structure)
- Code (class/interface level)
State Diagrams - State machines, lifecycle states
Git Graphs - Version control branching strategies
Gantt Charts - Project timelines, scheduling
Pie/Bar Charts - Data visualization

Quick Start Examples

Class Diagram (Domain Model)

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates
    
    class Title {
        +string name
        +int releaseYear
        +play()
    }
    
    class Genre {
        +string name
        +getTopTitles()
    }

Sequence Diagram (API Flow)

sequenceDiagram
    participant User
    participant API
    participant Database
    
    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

Flowchart (User Journey)

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD (Database Schema)

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes
    
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }
    
    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

Detailed References

For in-depth guidance on specific diagram types, see:

references/class-diagrams.md - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
references/flowcharts.md - Node shapes, connections, decision logic, subgraphs, styling
references/erd-diagrams.md - Entities, relationships, cardinality, keys, attributes
references/c4-diagrams.md - System context, container, component diagrams, boundaries
references/state-diagrams.md - Lifecycle states, labelled transitions, aliases, composite states, choice/fork/join, concurrent regions, notes
references/advanced-features.md - Themes, styling, configuration, layout options

Best Practices

Start Simple - Begin with core entities/components, add details incrementally
Use Meaningful Names - Clear labels make diagrams self-documenting
Comment Extensively - Use %% comments to explain complex relationships
Keep Focused - One diagram per concept; split large diagrams into multiple focused views
Version Control - Store .mmd files alongside code for easy updates
Add Context - Include titles and notes to explain diagram purpose
Iterate - Refine diagrams as understanding evolves

Editorial Style Rules

Mermaid 자동 레이아웃을 쓰더라도 아래 규칙을 지키면 "AI 기본 출력" 느낌을 크게 줄일 수 있습니다 (diagram-design 모듈에서 이식한 압축본. 완전한 에디토리얼 렌더링이 필요하면 skills/diagram-design/SKILL.md 표현 계층을 사용하세요).

액센트는 1~2개 노드만: classDef accent를 핵심 노드(happy path의 결정점, 최종 산출물)에만 적용. 모든 분기·에러에 색을 칠하면 신호가 사라집니다. 나머지는 기본 스타일 유지.
밀도 예산: 사람에게 보여줄 다이어그램은 노드 9개 이하 목표. 초과하면 개요 1장 + 상세 N장으로 분할합니다. (파이프라인 검증용 .mmd는 기존 20개 제한 유지 — 용도가 다름)
도형이 타입을 말하게: 시작/끝 ([ ]), 처리 [ ], 분기 { }, 서브루틴 [[ ]]. 색으로 노드 타입을 구분하지 않습니다.
분기 레이블 필수: decision에서 나가는 모든 화살표에 |Yes|/|No| 등 레이블. 출구 4개 이상인 분기는 중첩 분기로 리팩터링.
색 토큰: 순수 #000/#fff 대신 near-black(#2d3142)·off-white(#f5f5f5). 액센트는 프로젝트 DESIGN.md 토큰이 있으면 그것을, 없으면 한 가지 hue만.

---
config:
  theme: base
  themeVariables:
    primaryColor: "#f5f5f5"
    primaryTextColor: "#2d3142"
    primaryBorderColor: "#4f5d75"
    lineColor: "#4f5d75"
---
flowchart TD
    A([시작]) --> B{유효?}
    B -->|Yes| C[처리]
    B -->|No| D[거부]
    C --> E([완료])
    classDef accent stroke:#eb6c36,stroke-width:2px
    class E accent

Configuration and Theming

Configure diagrams using frontmatter:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

Available themes: default, forest, dark, neutral, base

Layout options:

layout: dagre (default) - Classic balanced layout
layout: elk - Advanced layout for complex diagrams (requires integration)

Look options:

look: classic - Traditional Mermaid style
look: handDrawn - Sketch-like appearance

Exporting and Rendering

Native support in:

GitHub/GitLab - Automatically renders in Markdown
VS Code - With Markdown Mermaid extension
Notion, Obsidian, Confluence - Built-in support

Export options:

Mermaid Live Editor - Online editor with PNG/SVG export
Mermaid CLI - npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png
Docker - docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

Common Pitfalls

Breaking characters - Avoid {} in comments, use proper escape sequences for special characters
Syntax errors - Misspellings break diagrams; validate syntax in Mermaid Live
Overcomplexity - Split complex diagrams into multiple focused views
Missing relationships - Document all important connections between entities

When to Create Diagrams

Always diagram when:

Starting new projects or features
Documenting complex systems
Explaining architecture decisions
Designing database schemas
Planning refactoring efforts
Onboarding new team members

Use diagrams to:

Align stakeholders on technical decisions
Document domain models collaboratively
Visualize data flows and system interactions
Plan before coding
Create living documentation that evolves with code

mermaid-diagrams

Files8

SKILL.mdskills/mermaid-diagrams/SKILL.md