Mermaid Diagrams

Default: Dark mode colors from references/color-palettes.md.

Choosing Diagram Type

Core Principles

1. Visual hierarchy over decoration – Color/size guide the eye to what matters
2. Semantic color – Colors have meaning (grouping, state, criticality)
3. Simplicity over completeness – 80% clearly beats 100% confusingly
4. 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

1. Purpose – What decision/understanding should this enable?
2. Type – Choose based on what you’re showing
3. Structure – Identify components, relationships, groupings
4. Style – Apply semantic colors, highlight critical paths
5. Review – Can someone understand it in 10 seconds?