Design decision log: how to document the why
A design decision log records what was decided, why, and which alternatives were rejected. Learn its format, when to write an entry, and how to maintain it.
What is a decision log?
It is a list of decisions, each in its own entry. The best-known format comes from software engineering: Architecture Decision Records (ADRs). Michael Nygard proposed them in 2011 as a lightweight way to document architecture decisions, aimed at agile teams. Martin Fowler describes each ADR as a short document that captures a single relevant decision, ideally on one page.
For product design the idea is the same. Illustrative example: an entry might say “We use a bottom navigation bar on mobile instead of a hamburger menu, because test participants switched sections often.” Six months later, when someone proposes a hamburger menu, the entry answers the question without a meeting.
Why does it matter to a designer?
Because most design decisions are made in conversations, screenshots, and messages that nobody saves. When the team changes, new people arrive and reopen debates that were already settled. Nygard puts it plainly: without context, whoever inherits a decision can only accept it blindly or reverse it blindly, and both options are bad.
A log also protects you in reviews. When a stakeholder asks why a feature was left out, the answer is written down, along with the alternatives that were evaluated.
What fields should an entry have?
Nygard’s model has five parts: title, status, context, decision, and consequences. Public team templates, such as the GOV.UK one, use a similar structure: status, context, decision, and consequences.
| Field | What it answers | Example |
|---|---|---|
| Title | What was decided, in a few words | “Bottom navigation on mobile” |
| Status | Where it stands | Proposed, accepted, or superseded |
| Context | Which forces motivated it | “Test participants switched sections every few minutes” |
| Decision | What was chosen, in active voice | “We will use a bottom bar with four sections” |
| Consequences | What changes, for better and worse | “Fewer taps, but less room for secondary options” |
Fowler adds two fields worth including: serious alternatives with their pros and cons, and your confidence in the decision. He also suggests noting which changes in context should trigger a re-evaluation.
The status field is not decoration. Fowler describes three values: proposed while under discussion, accepted once it is in force, and superseded when another decision replaces it (with a link to the new one). Nygard adds a fourth, deprecated.
When should you write an entry?
Write an entry when the decision is hard to reverse or affects more than one screen or team. Nygard uses the term “architecturally significant” for decisions that affect structure, non-functional characteristics, dependencies, interfaces, or construction techniques. In design, that translates to decisions about navigation patterns, the component system, voice and tone, or accessibility principles.
You do not need an entry for every visual tweak. If you record everything, the log fills with noise and nobody reads it.
How do you keep it up to date?
Fowler proposes a simple rule: once accepted, an entry is not reopened or edited. If the decision changes, you write a new entry that supersedes the old one, and you mark the old one as superseded with a link. That leaves a clear history of how long each decision governed the work. Nygard says the same: if a decision is reversed, keep the old one and mark it as superseded. This avoids the two bad outcomes he describes: blind acceptance or blind reversal.
GOV.UK keeps numbered Markdown files inside the project repository, so the documentation travels with the code. Fowler follows the same idea: each file gets a sequential number and the name of the decision, for example 0001-HTMX-for-active-web-pages. For design teams, a shared document or database works just as well, as long as it is easy to find and search.
Example
Illustrative example: a product team debates whether the cart should show prices with or without tax. In the meeting, two people argue for different options. The designer writes an entry titled “Tax-inclusive prices in the cart”, with the context (customer complaints about a final charge higher than expected), the decision, two rejected alternatives (showing the price without tax plus a note, and showing both figures in the cart), and the consequence that the cart will be longer. A month later, when finance asks to change the format, the entry shows what was evaluated and what would be lost by changing it.
Common mistakes
- Writing the decision without the context, so that a year later nobody understands why it was made.
- Documenting only what was chosen and not the rejected alternatives.
- Editing an accepted entry instead of superseding it, which erases the history.
- Logging everything, including minor decisions that do not justify the effort.
- Keeping it somewhere nobody opens, with no link from the project or the design specs.
A log works well alongside design specs and the UX design process. If your decisions come from distributed teams, remote design collaboration explains how to keep it accessible to everyone. And if a decision rests on data, cite the study in the context section.