Design decisions

Design decisions documents help teams understand not just what was decided, but why — making it easier to revisit choices as requirements change and to avoid re-litigating settled questions. They create a permanent record of decisions that might otherwise be scattered across Slack threads, tickets, or meeting notes.

We use the Architecture Decision Record (ADR) format to structure these documents. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

Components with design decisions

Patterns with design decisions