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?