Best Practices for Mermaid Diagrams

Practical guidelines for creating clear, maintainable, and professional diagrams that your team will actually use.

A well-crafted diagram communicates in seconds what paragraphs of text cannot. But a poorly structured diagram can be worse than no diagram at all: it misleads, confuses, and quickly becomes outdated. This guide collects the patterns and principles that lead to diagrams people genuinely find useful. If you are new to Mermaid.js syntax, start with the Learn page first, then return here to refine your approach.

Choosing the Right Diagram Type

The first decision is which diagram type best represents the information you want to convey. Choosing the wrong type forces readers to mentally translate the diagram, which defeats the purpose of visual communication. Here is a quick reference for common scenarios:

You want to show...	Use this type	Mermaid keyword
Process steps or decision logic	Flowchart	`flowchart`
Request/response between systems	Sequence Diagram	`sequenceDiagram`
Project schedule with dependencies	Gantt Chart	`gantt`
Object relationships and methods	Class Diagram	`classDiagram`
System states and transitions	State Diagram	`stateDiagram-v2`
Database tables and relationships	ER Diagram	`erDiagram`
User experience touchpoints	User Journey	`journey`

Tip: When in doubt, start with a flowchart. It is the most flexible type and works for the widest range of situations. You can always convert to a more specific type later. Explore the Diagram Gallery for examples of each type.

Layout and Flow Direction

Mermaid supports four flow directions: TB (top to bottom), BT (bottom to top), LR (left to right), and RL (right to left). Choosing the right direction makes your diagram feel natural to read.

As a general rule, use top-down (TD/TB) for hierarchical relationships like org charts, architecture layers, and decision trees. Use left-to-right (LR) for sequential processes like pipelines, timelines, and data flows. Readers in left-to-right languages naturally expect time and sequence to flow horizontally.

Good: LR for a pipeline

flowchart LR
    Code --> Build --> Test --> Deploy

Avoid: TD for a pipeline

flowchart TD
    Code --> Build --> Test --> Deploy

Vertical layouts work better when the diagram has many branches or when nodes have long labels, because vertical space is usually more abundant on screen than horizontal space. Horizontal layouts shine when the primary relationship is a sequence of steps happening in order.

Labeling Conventions

Good labels are short, descriptive, and consistent. Every node and edge label should answer one question: "What is this?" or "What happens here?" Avoid abbreviations that are not universally understood by your audience, and avoid verbose sentences that clutter the diagram.

Good: Clear, concise labels

flowchart LR
    A[User Request] -->|Authenticate| B[Auth Service]
    B -->|Valid Token| C[API Gateway]
    C -->|Route| D[Order Service]

Avoid: Vague or overlong labels

flowchart LR
    A[req] -->|do auth| B[svc1]
    B -->|The token has been validated
    and the user is confirmed| C[gw]
    C -->|send to the appropriate
    downstream microservice| D[svc2]

Additional labeling tips:

Use noun phrases for nodes (e.g., "Auth Service," "User DB") and verb phrases for edge labels (e.g., "Validate," "Send Request").
Keep edge labels under 5 words. If you need more context, add a note or link to documentation instead.
Use consistent casing. Title Case for node names and lowercase for edge labels is a common convention.
Assign meaningful node IDs (e.g., AuthSvc instead of A) so the raw code is readable even without rendering.

Using Color Effectively

Color is a powerful tool for drawing attention and grouping related elements, but overusing it creates visual noise. Limit your palette to 3-4 colors and assign each one a clear meaning. Common conventions include green for success or healthy states, red for errors or critical paths, blue for informational elements, and gray for background or inactive components.

flowchart TD
    A[Request] --> B{Validate}
    B -->|Pass| C[Process]
    B -->|Fail| D[Reject]
    C --> E[Respond 200]
    D --> F[Respond 400]

    style C fill:#dcfce7,stroke:#16a34a,color:#166534
    style E fill:#dcfce7,stroke:#16a34a,color:#166534
    style D fill:#fef2f2,stroke:#dc2626,color:#991b1b
    style F fill:#fef2f2,stroke:#dc2626,color:#991b1b

Use classDef to define reusable style classes instead of applying inline styles to every node. This keeps your code DRY and makes it easy to update colors across the entire diagram:

flowchart TD
    classDef success fill:#dcfce7,stroke:#16a34a,color:#166534
    classDef error fill:#fef2f2,stroke:#dc2626,color:#991b1b

    A[Request] --> B{Validate}
    B -->|Pass| C[Process]:::success
    B -->|Fail| D[Reject]:::error

Tip: Always test your color choices in both light and dark mode. SimpleMermaid applies automatic theme adjustments to SVG diagrams, but inline colors override those defaults. Ensure sufficient contrast in both themes.

Managing Complexity

A diagram with more than 15-20 nodes starts to lose its value as a communication tool. When a diagram grows beyond that threshold, readers spend more time deciphering the layout than understanding the system. Here are strategies for managing complexity:

Use subgraphs to group related nodes. Subgraphs create visual boundaries that help readers process the diagram in logical chunks rather than as a flat network of connections.

flowchart TB
    subgraph Frontend
        UI[React App]
        CDN[CDN]
    end

    subgraph Backend
        API[API Server]
        Worker[Background Worker]
    end

    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    UI --> CDN
    UI --> API
    API --> DB
    API --> Cache
    API --> Worker
    Worker --> DB

Create multiple focused diagrams instead of one monolithic one. A high-level architecture overview should show service boundaries and major data flows. Separate diagrams can then zoom into each service's internal structure, specific API flows, or database schemas. Link between these diagrams in your documentation.

Remove decorative elements. Every node, edge, and label should earn its place in the diagram. If removing an element does not reduce understanding, remove it. Simplicity is not about dumbing down; it is about focusing attention on what matters.

Team Standards and Consistency

When multiple people on a team create diagrams, inconsistency creeps in quickly. Different naming conventions, flow directions, and styling choices make the diagram collection feel chaotic rather than cohesive. Establishing lightweight standards prevents this.

Consider defining these conventions for your team:

Flow direction: Agree on LR for processes and TD for hierarchies.
Node ID naming: Use PascalCase for services (e.g., AuthService) and lowercase with underscores for data stores (e.g., user_db).
Color palette: Define a shared set of classDef declarations that everyone copies into their diagrams.
Granularity guidelines: Define what belongs in a "Level 1" overview versus a "Level 2" detail diagram. A common approach is to follow the C4 model (Context, Container, Component, Code).
Storage location: Store diagram source files alongside the code they describe, such as in a docs/ or diagrams/ directory in the same repository.

Store your team conventions in a shared document or wiki page, and include a template diagram that new team members can copy as a starting point. The Use Cases guide provides scenario-specific templates that can serve as that foundation.

Tip: Treat diagrams like code. Review them in pull requests, version them alongside your source code, and update them when the system changes. A stale diagram is worse than no diagram because it actively misleads.

Put these practices to work

Open the editor and apply these guidelines to your next diagram. Start from one of the 45+ built-in examples and refine it using the principles above.

Open the Editor