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](references/syntax-guide.md)
3. Avoid all forbidden patterns listed below
4. Keep labels short and simple

## Forbidden Patterns

These ALWAYS cause errors - never use:

```mermaid
❌ 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:

```mermaid
✅ 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):

```mermaid
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](references/syntax-guide.md) for complete sequence diagram syntax.

### Flowcharts

Use for decision trees and processes:

```mermaid
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](references/syntax-guide.md) for complete flowchart syntax.

### Class Diagrams

Use for object-oriented design:

```mermaid
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](references/syntax-guide.md) for complete class diagram syntax.

### State Diagrams

Use for state machines and lifecycles:

```mermaid
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](references/syntax-guide.md) for complete state diagram syntax.

### ER Diagrams

Use for database schemas:

```mermaid
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](references/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.