Mermaid Graph Writer

Mermaid Graph Writer

Writes precise, well-structured Mermaid diagrams. Selects the optimal diagram type for the content, uses correct syntax, and produces diagrams that are readable by both humans (rendered) and agents (text DSL).

---

When to Use

✅ Use for:

• Creating any Mermaid diagram from a description or data
• Choosing the right diagram type for a visualization need
• Refactoring prose decision trees into Mermaid flowcharts
• Modeling system architectures, protocols, state machines, data models
• Encoding temporal knowledge as timeline diagrams

❌ NOT for:

• Rendering/exporting Mermaid to PNG/SVG/PDF (use mermaid-graph-renderer)
• ASCII art or Unicode box-drawing (use diagramming-expert)
• GUI-based design tools (Figma, etc.)

---

Diagram Type Selection

flowchart TD
  A{What are you modeling?} -->|Branching logic| B[flowchart]
  A -->|Request/response over time| C[sequenceDiagram]
  A -->|States and transitions| D[stateDiagram-v2]
  A -->|Entities and relationships| E[erDiagram]
  A -->|Chronological evolution| F[timeline]
  A -->|Concept hierarchy| G[mindmap]
  A -->|Time-sequenced tasks| H[gantt]
  A -->|Proportions| I[pie]
  A -->|2-axis comparison| J[quadrantChart]
  A -->|Branch/merge history| K[gitGraph]
  A -->|Type hierarchy / OO| L[classDiagram]
  A -->|User experience steps| M[journey]
  A -->|Quantity flows| N[sankey-beta]
  A -->|Numeric data| O[xychart-beta]
  A -->|System components| P[block-beta]
  A -->|Infrastructure| Q[architecture-beta]
  A -->|Task board| R[kanban]
  A -->|Requirements traceability| S[requirementDiagram]
  A -->|System context / containers| T[C4Context]
  A -->|Protocol packets / headers| U[packet-beta]
  A -->|Multi-axis comparison| V[radar]
  A -->|Hierarchical proportions| W[treemap]
  A -->|Code-style sequences| X[zenuml]

Quick Reference

---

Flowchart Deep Dive (Most Common)

Direction

• TD / TB — top-down (best for decision trees)
• LR — left-right (best for processes, pipelines)
• BT — bottom-up (rare, for dependency graphs)
• RL — right-left (rare)

Node Shapes

[text]       Rectangle (default action)
(text)       Rounded rectangle (soft step)
{text}       Diamond (decision/condition)
([text])     Stadium/pill (start/end)
[[text]]     Subroutine (subprocess)
[(text)]     Cylinder (database/storage)
((text))     Circle (event/trigger)
>text]       Flag (async/signal)
{{text}}     Hexagon (preparation)
[/text/]     Parallelogram (input/output)
[\text\]     Reverse parallelogram
[/text\]     Trapezoid
[\text/]     Reverse trapezoid

Edge Styles

-->          Solid arrow (main flow)
---          Solid line (association)
-.->         Dotted arrow (optional/async)
==>          Thick arrow (emphasis/critical path)
--text-->    Labeled edge
~~~          Invisible link (layout control only)

Subgraphs

flowchart TD
  subgraph Backend
    A[API] --> B[DB]
  end
  subgraph Frontend
    C[UI] --> D[State]
  end
  C -->|fetch| A

---

Sequence Diagram Essentials

Messages

->>    Solid arrow (sync request)
-->>   Dotted arrow (async response)
-)     Open arrow (async fire-and-forget)
-x     Cross (failed/rejected)

Blocks

activate / deactivate    Lifeline activation
alt / else / end         Conditional branching
loop / end               Repetition
par / and / end          Parallel execution
critical / end           Critical section
break / end              Break-out flow
rect rgb(...)  / end     Background highlight

Numbering

Add autonumber after the first line to auto-number all messages.

---

State Diagram Essentials

[*] --> State1           Start transition
State1 --> State2        Named transition
State1 --> State2: event Labeled transition
State2 --> [*]           End transition

state State1 {          Nested states
  [*] --> SubA
  SubA --> SubB
}

state fork <<fork>>      Fork pseudostate
state join <<join>>      Join pseudostate
state choice <<choice>>  Choice pseudostate

---

ER Diagram Essentials

Cardinality

||--||    Exactly one to exactly one
||--o{    One to zero-or-many
}o--o{    Zero-or-many to zero-or-many
||--|{    One to one-or-many

Attributes

erDiagram
  USER {
    int id PK
    string name
    string email UK
  }
  ORDER {
    int id PK
    int user_id FK
    date created_at
  }
  USER ||--o{ ORDER : places

---

Writing Principles

1. Descriptive Labels, Not Codes

• ✅ A[Check if tests pass]
• ❌ A[Step 2.3]

2. Consistent Direction

Pick one direction for the whole diagram. Don't mix TD and LR within the same flowchart.

3. Max 15 Nodes per Diagram

Beyond 15 nodes, split into multiple diagrams or use subgraphs. A crowded diagram is worse than no diagram.

4. Use Subgraphs for Grouping

When a diagram has natural clusters (frontend/backend, phases, teams), use subgraphs to group them visually.

5. Label All Decision Edges

Every edge leaving a diamond ({decision}) node must have a label:

• ✅ A{Ready?} -->|Yes| B and A -->|No| C
• ❌ A{Ready?} --> B and A --> C (which is yes? which is no?)

6. Use Appropriate Edge Styles

• Solid arrows for main flow
• Dotted arrows for optional/async paths
• Thick arrows for critical paths or emphasis
• Invisible links (~~~) only for layout tweaking

---

Anti-Patterns

Wrong Diagram Type

Novice: Using a flowchart for everything — even protocols, state machines, and data models. Expert: Match diagram type to content structure. Sequence diagrams for protocols. State diagrams for lifecycle. ER for data models. Each type exists because flowcharts can't express that structure well.

Overcrowded Diagram

Novice: One diagram with 30 nodes and crossing edges. Expert: Split into overview diagram + detail diagrams. Use subgraphs. Max ~15 nodes per diagram.

Unlabeled Decision Edges

Novice: {Decision} --> A and {Decision} --> B — which condition leads where? Expert: Always label edges from decision diamonds: -->|Yes| and -->|No| (or -->|Success| and -->|Failure|, etc.)

Prose That Should Be a Diagram

Novice: "First check if X. If X then do A, otherwise do B. Then if A succeeds, do C, otherwise retry A." Expert: That's a flowchart. Write it as one. The formal graph is more precise AND more readable.

---

References

• references/diagram-types.md — Consult for comprehensive syntax, features, and examples for all 23 Mermaid diagram types: timeline, mindmap, quadrant, sankey, XY chart, block, architecture, kanban, pie, gitgraph, class, journey, requirementDiagram, C4 (5 sub-types), packet-beta, radar, treemap, and zenuml
• scripts/validate_mermaid.py — Validates Mermaid syntax in any file: checks diagram type declarations, matching fences, structural correctness

Changelog: mermaid-graph-writer

v1.0.0 (2026-02-05)

Created

• Diagram type selection decision tree (Mermaid flowchart)
• Quick reference table for all 16+ diagram types
• Deep dive on flowchart (node shapes, edge styles, subgraphs, direction)
• Sequence diagram essentials (messages, blocks, autonumber)
• State diagram essentials (transitions, nesting, pseudostates)
• ER diagram essentials (cardinality, attributes)
• 6 writing principles (descriptive labels, max 15 nodes, subgraphs, etc.)
• 4 anti-patterns (wrong type, overcrowded, unlabeled edges, prose-that-should-be-diagram)

Complete Mermaid Diagram Type Reference

Comprehensive syntax reference for all 23 Mermaid diagram types. Each section includes the declaration syntax, key features, gotchas, and a working example.

Last updated: 2026-03

---

1. Flowchart

Declaration: flowchart TD (or TB, LR, BT, RL)

Covered in detail in SKILL.md. See the Flowchart Deep Dive section.

---

2. Sequence Diagram

Declaration: sequenceDiagram

Covered in detail in SKILL.md. See the Sequence Diagram Essentials section.

---

3. Class Diagram

Declaration: classDiagram

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    class Cat {
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends
    Animal "1" --> "*" Food : eats

Key Syntax

class ClassName {
    +publicField type       # + public
    -privateField type      # - private
    #protectedField type    # # protected
    ~packageField type      # ~ package/internal
    +methodName() returnType
    +abstractMethod()* void   # * = abstract
    +staticMethod()$ void     # $ = static
}

Relationships

<|--    Inheritance (extends)
*--     Composition (has, owns lifecycle)
o--     Aggregation (has, separate lifecycle)
-->     Association (uses)
--      Link (bidirectional)
..>     Dependency (uses temporarily)
..|>    Realization (implements)

Cardinality

"1" --> "*"       One to many
"1" --> "0..1"    One to zero-or-one
"*" --> "*"       Many to many

Gotchas

• Generic types need HTML encoding: List~String~ not List<String>
• Mermaid uses ~ for generics, not angle brackets
• Namespace support: wrap classes in namespace MyNamespace { ... }

---

4. State Diagram

Declaration: stateDiagram-v2

Covered in detail in SKILL.md. See the State Diagram Essentials section.

---

5. Entity Relationship Diagram

Declaration: erDiagram

Covered in detail in SKILL.md. See the ER Diagram Essentials section.

---

6. User Journey

Declaration: journey

journey
    title User Onboarding Flow
    section Sign Up
        Visit landing page: 5: User
        Click sign up: 4: User
        Fill form: 2: User
        Verify email: 3: User
    section First Use
        Complete tutorial: 4: User
        Create first project: 5: User
        Invite team member: 3: User

Syntax

journey
    title [Title text]
    section [Section Name]
        [Task description]: [score 1-5]: [Actor1, Actor2]

• Score: 1 (frustrated) to 5 (delighted)
• Multiple actors: comma-separated
• Sections group related tasks visually

Gotchas

• No colons in task descriptions (use dashes instead)
• Actors must be consistent across the diagram
• Score is required for every task

---

7. Gantt Chart

Declaration: gantt

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    excludes weekends

    section Planning
        Requirements     :done, req, 2026-01-01, 14d
        Design           :active, des, after req, 10d

    section Development
        Backend API      :dev1, after des, 21d
        Frontend         :dev2, after des, 18d
        Integration      :int, after dev1, 7d

    section Launch
        Testing          :test, after int, 14d
        Deployment       :milestone, deploy, after test, 0d

Task Syntax

Task name :status, id, start, duration

• Status: done, active, crit (critical), or omit for default
• Start: YYYY-MM-DD or after taskId
• Duration: Nd (days), Nw (weeks), or end date
• Milestone: Duration of 0d

Date Formats

dateFormat YYYY-MM-DD       # Default
dateFormat DD-MM-YYYY       # European
dateFormat X                # Unix timestamp
axisFormat %b %d            # Axis display format

Gotchas

• excludes weekends is separate from excludes 2026-12-25
• Task IDs are optional but needed for after references
• Commas in task names break parsing — avoid them

---

8. Pie Chart

Declaration: pie

pie title Skills by Category
    "SWE" : 30
    "Domain" : 80
    "Creative" : 25
    "WinDAGs" : 7
    "Recovery" : 12

Syntax

pie [showData] [title Title Text]
    "Label" : value

• showData — optional, shows percentages on slices
• Values are absolute — Mermaid calculates percentages
• Labels must be quoted

Gotchas

• No negative values
• Labels MUST be in quotes
• showData keyword goes BEFORE title

---

9. Quadrant Chart

Declaration: quadrantChart

quadrantChart
    title Skill Priority Matrix
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Schedule
    quadrant-3 Delegate
    quadrant-4 Eliminate
    Add NOT clauses: [0.2, 0.8]
    Add Mermaid diagrams: [0.3, 0.9]
    Rewrite descriptions: [0.5, 0.7]
    Create reference files: [0.7, 0.6]
    Add CHANGELOGs: [0.1, 0.3]

Syntax

quadrantChart
    title [Title]
    x-axis [Low Label] --> [High Label]
    y-axis [Low Label] --> [High Label]
    quadrant-1 [Top-right label]
    quadrant-2 [Top-left label]
    quadrant-3 [Bottom-left label]
    quadrant-4 [Bottom-right label]
    [Point name]: [x, y]        # x and y are 0.0 to 1.0

Gotchas

• Quadrant numbering: 1=top-right, 2=top-left, 3=bottom-left, 4=bottom-right (counterclockwise from top-right)
• Coordinates are 0.0 to 1.0 (normalized)
• Point names cannot contain colons

---

10. Requirement Diagram

Declaration: requirementDiagram

requirementDiagram
    requirement Auth System {
        id: REQ-001
        text: Users must authenticate before accessing protected resources
        risk: high
        verifymethod: test
    }
    requirement Token Expiry {
        id: REQ-002
        text: Auth tokens must expire within 24 hours
        risk: medium
        verifymethod: inspection
    }
    element Auth Service {
        type: microservice
    }
    Auth Service - satisfies -> Auth System
    Auth Service - satisfies -> Token Expiry

Element Types

requirement       Standard requirement
functionalRequirement
performanceRequirement
interfaceRequirement
physicalRequirement
designConstraint
element           Implementation element

Relationship Types

- contains ->       Parent contains child
- copies ->         Derived copy
- derives ->        Derived requirement
- satisfies ->      Element satisfies requirement
- verifies ->       Element verifies requirement
- refines ->        More specific version
- traces ->         Traceability link

Verify Methods

verifymethod: analysis | demonstration | inspection | test

Risk Levels

risk: low | medium | high

Gotchas

• All fields (id, text, risk, verifymethod) are required
• Relationship arrows use - verb -> with spaces around the dash
• Element type is freeform text

---

11. Git Graph

Declaration: gitGraph

gitGraph
    commit id: "initial"
    branch develop
    checkout develop
    commit id: "feature-start"
    branch feature/auth
    checkout feature/auth
    commit id: "add-login"
    commit id: "add-oauth"
    checkout develop
    merge feature/auth
    checkout main
    merge develop tag: "v1.0"

Commands

commit [id: "label"] [tag: "tag"] [type: NORMAL|REVERSE|HIGHLIGHT]
branch branchName
checkout branchName
merge branchName [id: "label"] [tag: "tag"]
cherry-pick id: "commitId"

Gotchas

• Branch names cannot contain spaces
• checkout is required before committing to a branch
• merge merges INTO the currently checked-out branch
• Cherry-pick requires the commit to have an explicit id

---

12. Mindmap

Declaration: mindmap

mindmap
    root((Claude Skills))
        SWE
            error-handling
            caching
            database-design
            TypeScript patterns
        Domain
            Legal
            Medical
            Recovery
        Creative
            Pixel art
            Design systems
            Typography
        WinDAGs
            Architect
            Evaluator
            Decomposer

Node Shapes

root((text))    Circle (root node)
text            Rectangle (default)
(text)          Rounded rectangle
[text]          Square
{{text}}        Bang/hexagon
)text(          Cloud

Structure

• Indentation defines hierarchy (spaces, not tabs)
• Each deeper indent = child of the line above
• No explicit edge syntax — hierarchy IS the structure

Gotchas

• Indentation MUST be consistent (use spaces)
• No edge labels or styling
• Cannot add links between non-parent/child nodes
• Special characters in text need escaping

---

13. Timeline

Declaration: timeline

timeline
    title Mermaid Version History
    2019 : Mermaid 8.0
         : Class diagrams added
    2021 : Mermaid 9.0
         : State diagrams v2
    2023 : Mermaid 10.0
         : Mindmaps, timelines
         : Quadrant charts
    2025 : Mermaid 11.0
         : Kanban, radar, treemap

Syntax

timeline
    title [Title]
    [Time Period] : [Event 1]
                  : [Event 2]

• Time periods are left-aligned
• Events are indented with : prefix
• Multiple events per time period by repeating : lines

Sections

timeline
    section Phase 1
        2024 : Event A
    section Phase 2
        2025 : Event B

Gotchas

• Time periods are strings (free text, not parsed as dates)
• No links or connections between events
• Keep events concise — long text wraps poorly

---

14. Sankey Diagram

Declaration: sankey-beta

sankey-beta

Source A,Target X,50
Source A,Target Y,30
Source B,Target X,20
Source B,Target Z,40
Target X,Final,70
Target Y,Final,30
Target Z,Final,40

Syntax

sankey-beta

Source,Target,Value

• CSV format: source node, target node, flow value
• Nodes are created implicitly from source/target names
• Flow width proportional to value

Gotchas

• Header line sankey-beta must be followed by a blank line
• No spaces around commas in data rows
• Node names cannot contain commas
• Values must be positive numbers
• Flows go left-to-right (cannot reverse)

---

15. XY Chart

Declaration: xychart-beta

xychart-beta
    title "Skills by Month"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Count" 0 --> 50
    bar [10, 15, 22, 30, 35, 42]
    line [10, 15, 22, 30, 35, 42]

Syntax

xychart-beta [horizontal]
    title "Chart Title"
    x-axis "Label" [val1, val2, ...]       # Categorical
    x-axis "Label" min --> max              # Numeric range
    y-axis "Label" min --> max
    bar [data1, data2, ...]
    line [data1, data2, ...]

• horizontal keyword rotates the chart 90 degrees
• Multiple bar and line series supported
• Data arrays must match x-axis category count

Gotchas

• Category labels and data arrays use square brackets
• Numeric ranges use --> (not .. or -)
• Title and axis labels should be quoted
• horizontal goes on the declaration line, not inside

---

16. Block Diagram

Declaration: block-beta

block-beta
    columns 3
    A["Frontend"] B["API Gateway"] C["Auth Service"]
    D["Database"]:3

    A --> B
    B --> C
    B --> D

Syntax

block-beta
    columns N                    # Grid columns
    A["Label"]                   # Block with label
    A["Label"]:N                 # Block spanning N columns
    space                        # Empty grid cell
    space:N                      # N empty cells

    block:groupId
        E["Child"]
    end

    A --> B                      # Connection

Block Shapes

A["text"]       Rectangle (default)
A("text")       Rounded
A(("text"))     Circle
A{"text"}       Diamond
A{{"text"}}     Hexagon
A[/"text"/]     Parallelogram
A>"text"]       Flag

Gotchas

• columns must be declared before any blocks
• Blocks fill left-to-right, top-to-bottom in the grid
• :N span syntax MUST be adjacent to the block (no space)
• Connections must reference block IDs, not labels

---

17. Architecture Diagram

Declaration: architecture-beta

architecture-beta
    group cloud(cloud)[Cloud Infrastructure]
    group api(server)[API Layer] in cloud

    service web(internet)[Web App] in cloud
    service gateway(server)[API Gateway] in api
    service auth(lock)[Auth] in api
    service db(database)[PostgreSQL] in cloud

    web:R --> L:gateway
    gateway:R --> L:auth
    gateway:B --> T:db

Syntax

architecture-beta
    group groupId(icon)[Label]
    group groupId(icon)[Label] in parentGroup

    service serviceId(icon)[Label]
    service serviceId(icon)[Label] in groupId

    serviceA:edge --> edge:serviceB

Edge Positions

T = Top, B = Bottom, L = Left, R = Right

Icons

Built-in: cloud, database, disk, internet, server, lock

Custom icons via iconify (requires configuration).

Gotchas

• Edge syntax uses :position on BOTH sides: A:R --> L:B
• Groups can nest (use in parentGroup)
• Only --> edges (no dotted, no labels)
• Icon names are from a limited built-in set

---

18. Kanban

Declaration: kanban

kanban
    Todo
        task1[Add NOT clauses]
        task2[Create reference files]
    In Progress
        task3[Update Mermaid coverage]
    Done
        task4[Grade all skills]
        task5[Fix bottom 8 skills]

Syntax

kanban
    Column Name
        taskId[Task Label]
        taskId[Task Label]@{ priority: high }
    Another Column
        taskId[Task Label]

Metadata (Optional)

taskId[Label]@{ assignee: "name", priority: "high", ticket: "PROJ-123" }

Gotchas

• Column names are unindented, tasks are indented
• Task IDs must be unique across all columns
• No connections between tasks
• Column order = display order (left to right)
• Metadata support varies by renderer

---

19. C4 Diagram (5 Sub-Types)

C4 Context

Declaration: C4Context

C4Context
    title System Context Diagram
    Person(user, "End User", "Uses the web app")
    System(webapp, "Web Application", "Main product")
    System_Ext(email, "Email Service", "Sends notifications")
    System_Ext(payment, "Payment Gateway", "Processes payments")

    Rel(user, webapp, "Uses", "HTTPS")
    Rel(webapp, email, "Sends emails via", "SMTP")
    Rel(webapp, payment, "Processes payments", "API")

C4 Container

Declaration: C4Container

C4Container
    title Container Diagram
    Person(user, "User")

    System_Boundary(webapp, "Web Application") {
        Container(spa, "SPA", "React", "User interface")
        Container(api, "API", "Node.js", "Business logic")
        ContainerDb(db, "Database", "PostgreSQL", "Stores data")
    }

    Rel(user, spa, "Uses")
    Rel(spa, api, "Calls", "JSON/HTTPS")
    Rel(api, db, "Reads/Writes", "SQL")

All 5 C4 Sub-Types

Elements

Person(id, "Label", "Description")
Person_Ext(id, "Label", "Description")
System(id, "Label", "Description")
System_Ext(id, "Label", "Description")
System_Boundary(id, "Label") { ... }
Container(id, "Label", "Technology", "Description")
ContainerDb(id, "Label", "Technology", "Description")
ContainerQueue(id, "Label", "Technology", "Description")
Component(id, "Label", "Technology", "Description")

Relationships

Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
Rel_D(from, to, "Label")     # Down
Rel_U(from, to, "Label")     # Up
Rel_L(from, to, "Label")     # Left
Rel_R(from, to, "Label")     # Right

Gotchas

• C4 diagrams use FUNCTION CALL syntax, not Mermaid's usual A --> B
• System_Boundary uses curly braces { }, not end
• Description and technology fields are optional but recommended
• _Ext suffix marks external systems/people (different styling)

---

20. Packet Diagram

Declaration: packet-beta

packet-beta
    0-15: "Source Port"
    16-31: "Destination Port"
    32-63: "Sequence Number"
    64-95: "Acknowledgment Number"
    96-99: "Data Offset"
    100-103: "Reserved"
    104-104: "CWR"
    105-105: "ECE"
    106-106: "URG"
    107-107: "ACK"
    108-108: "PSH"
    109-109: "RST"
    110-110: "SYN"
    111-111: "FIN"
    112-127: "Window Size"

Syntax

packet-beta
    start-end: "Label"

• Bit ranges define field positions
• Single-bit fields: N-N: "Label"
• Multi-bit fields: start-end: "Label"
• Fields render as a grid showing bit positions

Gotchas

• Bit ranges must be non-overlapping and sequential
• Labels must be quoted
• Row width defaults to 32 bits (configurable via bitWidth in config)
• Primarily used for network protocol documentation

---

21. Radar Chart

Declaration: radar

radar
    title Skill Quality Assessment
    axis Description, Scope, Disclosure, Anti-Patterns, Tools, Activation, Visual, Output, Temporal, Docs
    curve skill-architect [95, 97, 90, 92, 88, 96, 93, 85, 82, 88]
    curve code-architecture [87, 90, 80, 82, 70, 85, 88, 75, 60, 72]
    curve mermaid-graph-writer [90, 92, 85, 88, 70, 90, 95, 80, 65, 78]

Syntax

radar
    title [Title]
    axis Label1, Label2, Label3, ...
    curve SeriesName [val1, val2, val3, ...]
    curve AnotherSeries [val1, val2, val3, ...]

• Multiple curves overlay on the same radar
• Values should be on the same scale (e.g., 0-100)
• Axis count must match value count per curve

Gotchas

• Axis labels are comma-separated on ONE line
• Curve values use square brackets
• Series name cannot contain spaces (use hyphens)
• Minimum 3 axes for a meaningful radar

---

22. Treemap

Declaration: treemap

treemap
    root[Skill Library]
        SWE[SWE Skills]
            error-handling[Error Handling]
            caching[Caching]
            database[Database Design]
            typescript[TypeScript]
        Domain[Domain Skills]
            legal[Legal]
            medical[Medical]
            recovery[Recovery]
        Creative[Creative Skills]
            pixel-art[Pixel Art]
            design[Design Systems]

Syntax

treemap
    root[Root Label]
        child1[Child Label]
            grandchild1[Label]
        child2[Child Label]

• Indentation defines hierarchy (like mindmap)
• Rectangle sizes proportional to leaf count or values
• Labels use square brackets

Gotchas

• Indentation must be consistent
• No explicit size values in basic syntax (proportional to children)
• No connections or links
• Best for showing hierarchical composition

---

23. ZenUML (Plugin)

Declaration: zenuml

zenuml
    @Actor User
    @Boundary WebApp
    @Service AuthService
    @Database UserDB

    User->WebApp.login(username, password) {
        WebApp->AuthService.validate(username, password) {
            AuthService->UserDB.findUser(username)
            if (valid) {
                return token
            } else {
                throw AuthError
            }
        }
    }

Syntax

ZenUML uses a code-like syntax instead of Mermaid's usual DSL:

@Actor ParticipantName
@Boundary ParticipantName
@Service ParticipantName
@Database ParticipantName

ParticipantA->ParticipantB.methodName(args) {
    // Nested calls
    if (condition) {
        return value
    }
}

Participant Stereotypes

@Actor       Person/user
@Boundary    System boundary (UI, API gateway)
@Control     Controller/coordinator
@Entity      Domain entity
@Service     Service component
@Database    Data store

Control Flow

if (condition) { ... } else { ... }
while (condition) { ... }
try { ... } catch (error) { ... }
par { ... }                          # Parallel

Gotchas

• Plugin: ZenUML is an external Mermaid plugin — not available in all renderers
• Uses curly braces { } for nesting (code-like), not activate/deactivate
• Method call syntax: A->B.method(args) not A->>B: method(args)
• Check renderer compatibility before using

---

Summary Table

---

Stability Tiers