Mermaid Diagrams
Default: Dark mode colors from references/color-palettes.md.
Choosing Diagram Type
| Concept | Diagram Type |
|---|---|
| Process flows, decisions | Flowchart (TB direction) |
| API calls, message passing | Sequence diagram |
| Lifecycle states | State diagram |
| Data models, relationships | Class diagram or ERD |
| System architecture | Flowchart with subgraphs (LR direction) |
Core Principles
- •Visual hierarchy over decoration - Color/size guide the eye to what matters
- •Semantic color - Colors have meaning (grouping, state, criticality)
- •Simplicity over completeness - 80% clearly beats 100% confusingly
- •7-12 nodes max - Human working memory limit; break larger systems into drill-downs
Quick Styling Guide
Do:
- •Use fills to group related components
- •Highlight critical paths with stroke width
- •Different shapes = different component types (cylinders for DBs, diamonds for decisions)
- •Keep labels to 1-4 words; use
<br/>for longer
Don't:
- •Pure black (
#000000) - too harsh, use dark gray - •Saturated background colors - tire the eyes
- •More than 5 colors per diagram
- •Low-contrast combinations
Shape Semantics
- •Rectangles: Services, processes
- •Rounded rectangles: APIs, interfaces
- •Circles: Start/end points, external systems
- •Diamonds: Decision points
- •Cylinders: Databases
- •Hexagons: Queues, message brokers
Layout
LR (left-to-right): Pipelines, architecture diagrams TB (top-to-bottom): Hierarchies, decision flows
Use subgraphs for: deployment boundaries, logical layers, team ownership, trust boundaries.
Resources
- •Color palettes: See references/color-palettes.md
- •Pattern examples: See references/examples.md for architecture, state machines, data flows, ERDs
Workflow
- •Purpose - What decision/understanding should this enable?
- •Type - Choose based on what you're showing
- •Structure - Identify components, relationships, groupings
- •Style - Apply semantic colors, highlight critical paths
- •Review - Can someone understand it in 10 seconds?