mermaid

Original source / Raw SKILL.md

---
name: mermaid
description: Create, edit, update, modify, and customize mermaid diagrams and architecture diagrams. Always use when working with mermaid diagrams, architecture diagrams, flowcharts, sequence diagrams, or when creating/editing/updating/customizing mermaid diagrams in markdown files.
---

# Mermaid Diagrams

## Basic Frontmatter Syntax

All diagram customization uses frontmatter at the top of the diagram:

```
%%{init: {'theme':'dark'}}%%
```

For details on all configuration options, see `configuration.md` and `styling.md`.

## Workflow Selection

Determine whether the user wants to **create** a new diagram or **edit** an existing diagram:

- **Creating:** User requests a new diagram, asks to "draw", "create", "make", or "generate" a diagram
- **Editing:** User requests changes to an existing diagram, asks to "change theme", "update", "modify", "customize", or "edit"

Follow the appropriate workflow below based on the user's intent.

---

## Creating New Diagrams

Follow this workflow when creating new Mermaid diagrams:

### 1. Determine Diagram Type and Theme

If the user's request doesn't clearly indicate which diagram type or theme to use, **use the AskUserQuestion tool once** to ask both questions:

**Question 1 - Diagram Type:**
- **Flowchart** - Decision trees, algorithms, process flows
- **Sequence** - Time-ordered interactions between actors/components
- **State** - State machines, workflows, state transitions
- **Architecture** - System components and relationships
- **Entity Relationship** - Database schemas and data models
- **Gantt** - Project schedules and task dependencies
- **Timeline** - Chronological events and milestones
- **Mindmap** - Hierarchical concepts and brainstorming
- **User Journey** - User experience flows and touchpoints
- **Sankey** - Flow quantities and value relationships

**Question 2 - Theme:**
- **Default** - Most use cases, web documentation
- **Neutral** - Black and white printing or high contrast needs
- **Dark** - Dark mode websites, presentations on dark backgrounds
- **Forest** - Softer, nature-inspired aesthetic

Reference the selection flowchart below to guide your questions, or consult `diagrams/` for detailed examples of each type.

### 2. Create the Diagram

1. **Read the diagram type reference** in `diagrams/` for syntax examples and conventions
2. Apply the selected theme using frontmatter: `%%{init: {'theme':'selected-theme'}}%%`
3. Create the diagram in a markdown file

**Common Issues:**
- If encountering syntax errors or special character issues, read `conventions.md`
- For custom colors or theme variables, read `styling.md`
- For diagram-specific configuration options, read `configuration.md`

## Diagram Type Selection Guide

Use this flowchart to determine the appropriate diagram type:

```mermaid
flowchart TD
    Start[What are you trying to show?] --> Question1{Process or<br/>Structure?}

    Question1 -->|Process| Question2{Does time<br/>matter?}
    Question1 -->|Structure| Question3{System or<br/>Data?}

    Question2 -->|Yes, sequential| Question4{Multiple actors<br/>interacting?}
    Question2 -->|No, just logic| Flowchart[Flowchart]
    Question2 -->|Time-based events| Question5{Project plan<br/>or events?}

    Question4 -->|Yes| Sequence[Sequence Diagram]
    Question4 -->|No, state changes| State[State Diagram]

    Question3 -->|System| Architecture[Architecture Diagram]
    Question3 -->|Data model| Entity[Entity Relationship]
    Question3 -->|Flow quantities| Sankey[Sankey Diagram]

    Question5 -->|Project plan| Gantt[Gantt Chart]
    Question5 -->|Events| Timeline[Timeline]

    Start --> Question6{Concept or<br/>Experience?}
    Question6 -->|Concepts/Ideas| Mindmap[Mindmap]
    Question6 -->|User experience| UserJourney[User Journey]
```


---

## Editing Existing Diagrams

Follow this workflow when editing or customizing existing Mermaid diagrams:

### 1. Read the Existing Diagram

Use the Read tool to view the current diagram file and understand its structure.

### 2. Identify the Change Type

Determine what the user wants to modify:

- **Theme/Styling** - Change colors, fonts, visual appearance
- **Configuration** - Modify diagram-specific settings (layout, spacing, options)
- **Content** - Update nodes, edges, text, structure
- **Icons** - Add or change icons (architecture diagrams)

### 3. Apply Changes Based on Type

- **Theme/Styling** - Read `styling.md` for theme options, color customization, and theme variables
- **Configuration** - Read `configuration.md` for diagram settings, frontmatter syntax, and options
- **Content** - Read the diagram type reference in `diagrams/` for syntax
- **Icons** - Read `configuration.md` "Icon Registration" section (architecture diagrams only)

### 4. Make the Edit

Use the Edit tool to update the diagram file with the changes, preserving the existing structure and only modifying what the user requested.

---

## Reference Files

### Diagram Type References

Located in `diagrams/`, each file includes use cases, complete examples with themes, and conventions:

- **Process & Flow**: `flowchart.md`, `sequence.md`, `state.md`, `sankey.md`
- **System Design**: `architecture.md`, `entity-relationship.md`
- **Planning & Timeline**: `gantt.md`, `timeline.md`
- **Conceptual**: `mindmap.md`, `user-journey.md`

### Configuration & Styling

- **`configuration.md`** - Complete configuration options, frontmatter syntax, icon registration. Read when user wants to modify diagram settings, add icons, or change configuration.
- **`styling.md`** - Theming capabilities, all theme variables, color customization, examples. Read when user wants to change colors, themes, or visual appearance.
- **`conventions.md`** - Syntax guide, escaping special characters, layout best practices, performance tips, accessibility. Read when encountering syntax issues or layout problems.