Diagram Tools Comparison¶

This page demonstrates different diagram rendering options available in this documentation.

Quick Comparison¶

Tool	Strengths	Best For
Mermaid	Built-in, simple syntax, GitHub compatible	Quick diagrams, flowcharts
D2	Professional output, unified syntax, sketch mode	Architecture, polished docs
Kroki	24+ diagram types via one API	Specialized diagrams (future)

Example: Agent Workflow¶

Mermaid Version¶

flowchart LR
    classDef orchestrator fill:#303F9F,stroke:#1A237E,color:#E8EAF6
    classDef research fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD
    classDef design fill:#5D4037,stroke:#3E2723,color:#FFF8E1
    classDef validate fill:#B71C1C,stroke:#7F0000,color:#FFEBEE
    classDef complete fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9

    O[ORCHESTRATOR]:::orchestrator
    P1[Phase 1: Research]:::research
    P2[Phase 2: Strategy]:::research
    P3[Phase 3: Solution]:::research
    P4[Phase 4: UI Design]:::design
    P5[Phase 5: Critique]:::validate
    P6[Phase 6: Polish]:::complete

    O --> P1 --> P2 --> P3 --> P4 --> P5 --> P6

D2 Version¶

Example: Build-Measure-Learn Loop¶

Mermaid Version¶

flowchart TB
    classDef ideate fill:#5D4037,stroke:#3E2723,color:#FFF8E1
    classDef build fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD
    classDef measure fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9

    IDEAS[Ideas]:::ideate
    BUILD[Build]:::build
    PRODUCT[Product / Prototype]:::build
    MEASURE[Measure]:::measure
    DATA[Data]:::measure

    IDEAS --> BUILD --> PRODUCT --> MEASURE --> DATA
    DATA -.->|Learn| IDEAS

D2 Version¶

Example: Architecture Diagram¶

Mermaid Version¶

flowchart TB
    classDef client fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD
    classDef api fill:#303F9F,stroke:#1A237E,color:#E8EAF6
    classDef service fill:#5D4037,stroke:#3E2723,color:#FFF8E1
    classDef data fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9

    Web[Web App]:::client
    Mobile[Mobile App]:::client
    Gateway[API Gateway]:::api
    Auth[Auth Service]:::api
    Users[User Service]:::service
    Products[Product Service]:::service
    Orders[Order Service]:::service
    DB[(PostgreSQL)]:::data
    Cache[(Redis)]:::data

    Web --> Gateway
    Mobile --> Gateway
    Gateway --> Auth
    Gateway --> Users
    Gateway --> Products
    Gateway --> Orders
    Users --> DB
    Products --> DB
    Orders --> DB
    Users --> Cache

D2 Version¶

Example: D2 Sketch Mode¶

D2 supports a hand-drawn "sketch" mode for a more informal feel:

Mermaid Styling Patterns¶

Using classDef (Recommended)¶

Define reusable style classes for semantic meaning:

flowchart LR
    classDef primary fill:#303F9F,stroke:#1A237E,color:#E8EAF6
    classDef secondary fill:#37474F,stroke:#263238,color:#ECEFF1
    classDef success fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9
    classDef warning fill:#E65100,stroke:#BF360C,color:#FFF3E0
    classDef errorStyle fill:#B71C1C,stroke:#7F0000,color:#FFEBEE

    A[Start]:::primary
    B{Check}:::secondary
    C[Success]:::success
    D[Review]:::warning
    E[Error]:::errorStyle

    A --> B
    B -->|Pass| C
    B -->|Warn| D
    B -->|Fail| E

Workflow Phases Example¶

flowchart LR
    classDef research fill:#1E3A5F,stroke:#0D47A1,color:#E3F2FD
    classDef design fill:#5D4037,stroke:#3E2723,color:#FFF8E1
    classDef validate fill:#B71C1C,stroke:#7F0000,color:#FFEBEE
    classDef complete fill:#1B5E20,stroke:#0D3D13,color:#E8F5E9

    R[Research]:::research
    D[Design]:::design
    V[Validate]:::validate
    C[Complete]:::complete

    R --> D --> V --> C

Built-in Themes¶

MkDocs Material automatically handles light/dark mode. For reference, Mermaid's built-in themes:

Theme	Best For
`default`	Standard light documentation
`dark`	Dark mode interfaces
`neutral`	Print/black-white
`forest`	Green-themed
`base`	Custom styling only

Recommendations¶

Use Mermaid When:¶

Quick diagrams needed
GitHub README compatibility required
Simple flowcharts or sequence diagrams
Built-in theme integration is sufficient

Use D2 When:¶

Professional/polished output needed
Complex architecture diagrams
Consistent styling across many diagrams
Hand-drawn sketch style desired

Future: Kroki Integration¶

Kroki provides a unified API for 24+ diagram types. See Kroki Setup Guide for future integration instructions.

Supported diagram types include: - BlockDiag, SeqDiag, ActDiag, NwDiag - PlantUML (all UML types) - C4 architecture diagrams - Graphviz/DOT - Mermaid - D2 - Excalidraw - And many more...