nickcrew/mermaid-diagramming

Mermaid Diagramming

Create clear, professional Mermaid diagrams for technical documentation. Covers all major diagram types with both basic and styled variants, rendering guidance, and export recommendations.

When to Use This Skill

• Creating flowcharts for process documentation or decision trees
• Drawing sequence diagrams for API interactions or system communication
• Building ERDs for database schema documentation
• Designing state machine diagrams for workflow states
• Producing Gantt charts for project timelines
• Documenting system architecture with C4 or network diagrams
• Adding visual aids to README files, ADRs, or design docs

Quick Reference

| Resource | Purpose | Load when | |----------|---------|-----------| | references/diagram-types.md | Syntax, patterns, and code examples for every Mermaid diagram type | Choosing or building a diagram |

---

Workflow Overview

Phase 1: Scope     → Identify what to visualize, audience, and diagram type
Phase 2: Draft     → Write base Mermaid code with correct syntax
Phase 3: Style     → Add theming, colors, and accessibility annotations
Phase 4: Deliver   → Provide rendering instructions and suggest iterations

---

Phase 1: Scope

Before writing any code, clarify:

1. What is the narrative? The diagram should tell a story or answer a question.
2. Who is the audience? Developers need detail; stakeholders need overview.
3. What entities and relationships exist? List nodes and edges before drawing.
4. Which diagram type fits? Use the selection guide below.

Diagram Type Selection

| If you need to show... | Use | |------------------------|-----| | Process flow, decisions, branching | flowchart | | Interactions over time between systems/actors | sequenceDiagram | | Data model and relationships | erDiagram | | Object structure and inheritance | classDiagram | | States and transitions | stateDiagram-v2 | | Project schedule and dependencies | gantt | | Proportions or distribution | pie | | Hierarchical idea mapping | mindmap | | Events over time | timeline | | System architecture layers | C4 context/container diagrams | | Code version history | gitGraph | | User experience flow | journey |

---

Phase 2: Draft

Structure Rules

1. One concept per diagram — split complex systems into multiple views
2. Limit nodes — keep under 15 nodes per diagram; split if larger
3. Meaningful labels — use descriptive text, not single letters
4. Consistent direction — prefer top-to-bottom (TB) or left-to-right (LR)
5. Group related nodes — use subgraph to cluster related elements

Code Conventions

%% Always start with a comment describing the diagram's purpose
%% Use consistent quoting for labels with special characters
flowchart LR
    A["User Request"] --> B{"Auth Check"}
    B -->|Valid| C["Process Request"]
    B -->|Invalid| D["Return 401"]

• Use double quotes for labels containing special characters
• Add comments (%%) explaining non-obvious relationships
• Prefer --> for solid lines, -.-> for dashed, ==> for thick
• Use descriptive edge labels: -->|"reason"| TargetNode

---

Phase 3: Style

Theming

Apply consistent styling using %%{init: ...}%% directives:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9'}}}%%
flowchart TB
    A["Start"] --> B["End"]

Node Styling

flowchart LR
    A["Normal"]
    B["Highlighted"]:::highlight
    classDef highlight fill:#f9f,stroke:#333,stroke-width:2px

Accessibility

• Use high-contrast color combinations
• Do not rely on color alone to convey meaning — add labels and shapes
• Include alt text when embedding: ![Diagram description](path)
• Provide a text summary alongside complex diagrams

---

Phase 4: Deliver

Always Provide

1. Basic version — clean, unstyled diagram that renders anywhere
2. Styled version — themed variant with colors and emphasis
3. Rendering note — where to preview (GitHub, Mermaid Live, VS Code extension)
4. Suggestions — complementary diagrams or next iterations

Rendering Options

| Platform | Support | |----------|---------| | GitHub markdown | Native rendering in .md files | | GitLab markdown | Native rendering | | Mermaid Live Editor | https://mermaid.live for interactive editing | | VS Code | Mermaid extension for preview | | Docusaurus / MkDocs | Plugin-based rendering |

Export Formats

• SVG: Best for web and docs (scalable, searchable text)
• PNG: Fallback for platforms without Mermaid support
• PDF: For print or formal documentation

---

Best Practices

• Start simple — get the structure right before adding style
• Test rendering — verify on the target platform before committing
• Version diagrams — update diagrams when the underlying system changes
• Colocate with docs — keep diagrams in the same directory as related documentation
• Use subgraphs — group related nodes to reduce visual complexity

Anti-Patterns

• Putting too many nodes in one diagram (split at 15+ nodes)
• Using single-letter node IDs without labels
• Relying on color alone to convey meaning
• Hard-coding pixel widths that break on different renderers
• Leaving diagrams out of date after system changes