← Go Back

Decision Records

What are decision records?

Decision records are short documents that capture an important decision: the context, the options considered, the choice made, and the rationale. They’re used for design, product, or technical decisions so that later (or new joiners) can understand why something was done and whether to revisit it. Common formats include ADR (Architecture Decision Record), DDR (Design Decision Record), or a generic “decision record.”

Use it when: a decision has lasting impact or will be questioned later (e.g. “Why did we choose this pattern?” “Why don’t we support X?”). They’re especially useful for design systems, architecture, and product strategy.

Copy/paste template

  • Title – Short, specific (e.g. “Use primary button for one CTA per screen”).
  • Status – Proposed | Accepted | Deprecated | Superseded (and by what).
  • Context – What situation or problem led to this decision.
  • Options – 2–4 options you considered (briefly).
  • Decision – What you chose.
  • Rationale – Why; what would have to change to revisit.
  • Consequences – What follows (e.g. “All new screens must follow this”; “We will not support Y”).

Keep it to one page. Date and author (or team) help.

Why decision records matter

  • Context for the future – “Why did we do this?” is answered without hunting through chat or memory.
  • Onboarding – New joiners see the reasoning behind patterns and product choices.
  • Revisiting – When context changes, you can see what would need to change to reverse or update the decision.
  • Consistency – Design and product decisions are documented so they’re applied consistently (e.g. design standards, design system rules).
  • Fewer repeated debates – “We already decided this; here’s why” with a link.

What a good decision record includes

Checklist

  • [ ] Context – What problem or situation; enough that someone later understands the “why now.”
  • [ ] Options – At least 2; what you considered and (briefly) why you didn’t pick the others.
  • [ ] Decision – Clear statement of what was chosen.
  • [ ] Rationale – Why; what evidence or principle. “What would have to change for us to revisit?” is useful.
  • [ ] Consequences – What this means in practice (e.g. for design system, backlog, or architecture).
  • [ ] Findable – In a repo, wiki, or design system doc; linked where the decision is applied.
  • [ ] Status – So you know if it’s still current or superseded.

Common formats

  • ADR (Architecture Decision Record): For technical/architecture decisions. Same structure: context, options, decision, consequences.
  • DDR (Design Decision Record): For design choices (e.g. component behaviour, design system rules). Same structure.
  • Lightweight: Title, context, decision, rationale, consequences. No formal status if you don’t need it.
  • Superseded: When you change the decision, add a new record that says “Supersedes [link to old]” and update the old one to “Superseded by [link].”

Examples

Example (the realistic one)

Title: One primary CTA per screen. Status: Accepted. Context: We had screens with 3–4 equally prominent buttons; users didn’t know what to do first. Options: (1) Keep multiple primary; (2) One primary, rest secondary; (3) No primary, only links. Decision: One primary CTA per screen or section; others secondary or text. Rationale: Usability and hierarchy research; reduces decision fatigue. We’d revisit if we had evidence that multiple primaries performed better for a specific pattern. Consequences: Design system and design standards document this; new screens are reviewed against it. Date and author. Stored in the design system repo or wiki and linked from the button component doc.

Common pitfalls

  • No context: “We decided X.” → Do this instead: Explain the situation and problem so the “why” is clear.
  • No options: Only the chosen option. → Do this instead: List 2–4 options (even briefly) so the decision is defensible and revisitable.
  • Never updated: Decision changed but record not. → Do this instead: When you reverse or change, add a new record and mark the old one superseded.
  • Too long: Essay instead of one page. → Do this instead: Keep context and options to a few bullets; rationale 1–2 paragraphs.
  • Unfindable: Buried in a folder nobody uses. → Do this instead: Put records where the team looks (e.g. design system, architecture repo); link from the thing the decision affects.
  • Decision records vs design standards: Design standards are the rules; decision records explain why a rule or pattern was chosen. Records support standards.
  • Decision records vs design system: Design system docs can include or link to decision records for component and pattern choices.
  • Decision records vs backlog: Backlog is what to do; decision records are why we decided something (e.g. why we’re not doing Y). Different purposes.

Next step

Pick one recent decision that will be asked about again (e.g. a design system rule, a product “we’re not doing X,” or an architecture choice). Write a one-page decision record (context, options, decision, rationale, consequences) and put it where the team will find it. Link it from the relevant design standards or doc.

Related Terms