mermaid-creator

name

mermaid-creator

description

Use proactively whenever generating Mermaid diagram code in any context (markdown blocks, .md files, docs). Covers flowcharts, sequence, class, state, ER, gantt, pie, mindmaps, timelines, and all Mermaid types. Applies strict syntax rules to prevent rendering errors (HTML tags, style directives, invalid escapes). No explicit request needed — load automatically when Mermaid syntax is being produced.

Mermaid Creator

Generate valid, error-free Mermaid diagrams following strict syntax rules and best practices.

Core Principles

1. NO HTML tags - Never use <br/>, <br>, or any HTML in any part of the diagram
2. NO style directives - Never use style, fill, stroke, classDef, or color specifications
3. Simple labels - Keep text concise, avoid special characters or escape them properly
4. Validate syntax - Always check against common error patterns before finalizing

Quick Start

When generating any Mermaid diagram:

1. Identify the diagram type (sequence, flowchart, class, state, ER)
2. Use only the patterns from syntax-guide.md
3. Avoid all forbidden patterns listed below
4. Keep labels short and simple

Forbidden Patterns

These ALWAYS cause errors - never use:

❌ participant User<br/>Browser          (HTML tags)
❌ A[Label<br/>with breaks]              (HTML in labels)
❌ style A fill:#ff0000                  (Style directives)
❌ classDef myClass fill:#f9f            (Color definitions)
❌ A --> B: Very long message<br/>text   (Line breaks in text)

Safe Patterns

Use these instead:

✅ participant UserBrowser as User Browser    (Aliases)
✅ A[Short label]                             (Concise text)
✅ A --> B: Concise message                   (Single-line text)
✅ Note over A,B: Descriptive note            (Notes for details)

Diagram Type Selection

Choose based on use case:

• Sequence diagrams: Authentication flows, API calls, time-based interactions
• Flowcharts: Decision logic, processes, algorithms, step-by-step workflows
• Class diagrams: Object-oriented design, data structures, type hierarchies
• State diagrams: State machines, status lifecycles, transition logic
• ER diagrams: Database schemas, entity relationships, data models

Generating Diagrams

Sequence Diagrams

Use for showing interactions over time (auth flows, API calls):

sequenceDiagram
    participant Client
    participant Auth0
    participant Backend

    Client->>Auth0: Login request
    Auth0-->>Client: Authorization code
    Client->>Backend: POST /create-session
    Backend-->>Client: Set-Cookie (session)

Key rules:

• Use participant X as Long Name for readable labels
• Arrow types: ->, -->, ->>, -->> (solid/dotted, with/without arrow)
• Keep messages concise (no line breaks)
• Use Note over X,Y: Text for additional context

See syntax-guide.md for complete sequence diagram syntax.

Flowcharts

Use for decision trees and processes:

flowchart TD
    A[Start]
    B{Authenticated?}
    C[Call API]
    D[Redirect to login]

    A --> B
    B -->|Yes| C
    B -->|No| D

Key rules:

• Direction: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)
• Shapes: [] rectangle, () rounded, {} diamond, [[]] subroutine
• Use quotes for labels with special chars: A["Label: special"]

See syntax-guide.md for complete flowchart syntax.

Class Diagrams

Use for object-oriented design:

classDiagram
    class User {
        +String id
        +String email
        +login()
        +logout()
    }

    class Session {
        +String token
        +Date expires
        +validate()
    }

    User --> Session

Key rules:

• Visibility: + public, - private, # protected
• Relationships: <|-- inheritance, *-- composition, --> association
• Keep type annotations simple

See syntax-guide.md for complete class diagram syntax.

State Diagrams

Use for state machines and lifecycles:

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing
    Processing --> Success
    Processing --> Failed
    Success --> [*]
    Failed --> [*]

Key rules:

• Use stateDiagram-v2 (v2 is current version)
• [*] represents start/end states
• Avoid special characters in state names

See syntax-guide.md for complete state diagram syntax.

ER Diagrams

Use for database schemas:

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

    USER {
        string id
        string email
    }

    ORDER {
        string id
        date created_at
    }

Key rules:

• Cardinality: ||--|| one-to-one, ||--o{ one-to-many, }o--o{ many-to-many
• Use hyphens in multi-word entity names: USER-ACCOUNT
• Keep attribute types simple

See syntax-guide.md for complete ER diagram syntax.

Error Prevention Workflow

Before finalizing any Mermaid diagram:

1. Check for HTML tags - Search for <br, <div, or any < character
2. Check for style directives - Search for style, fill:, stroke:
3. Check labels - Ensure all text is concise (no manual line breaks)
4. Check special chars - Escape or quote labels with :, #, {}, [], ()
5. Verify syntax - Match exactly against patterns in syntax-guide.md

Common Fixes

Error Pattern	Fix
participant A<br/>B	participant AB as A B
A->>B: Long<br/>text	A->>B: Long text (keep single line)
style A fill:#f00	Delete entirely (no styling)
A[Label #1]	A["Label #1"] (quote special chars)
A --> B: text<br/>more	Split into two arrows or use Note

Resources

references/syntax-guide.md

Comprehensive syntax reference with:

• Detailed syntax for all diagram types
• Common pitfalls with examples
• Validation checklist
• Quick reference for diagram type selection

Load this file when encountering syntax questions or edge cases.