How to Write a Design Decision That's Still Legible Five Years Later
Most design decisions live in three places: a Slack thread that’s been archived, a Figma comment that’s been resolved, and the head of someone who’s no longer at the company.
None of those are documentation.
The best design documentation I’ve ever seen does one thing well: it answers the question a future collaborator will actually ask. Not “what did you choose?” — that’s usually visible in the design. The question they’ll ask is “why didn’t you do the obvious thing?”
That’s the question that kills velocity. Someone joins six months later. They look at the component, think of a cleaner approach, spend two weeks prototyping it — and then get told in review that you tried that in March. Two weeks gone. One Notion doc could have prevented it.
What decays and what doesn’t
Design decisions have a hierarchy of legibility. Some things age well. Some things become useless without the context that surrounded them.
What ages badly:
- “The client wanted it this way.” (Client is gone.)
- “It felt right in testing.” (Which sessions? What did you measure?)
- “We couldn’t figure out a better approach.” (Someone else will try again.)
What ages well:
- The alternatives you seriously considered — and the specific reason you ruled each one out
- The actual constraint driving the decision (a technical limit, a brand rule, an accessibility requirement)
- The success criteria you were optimizing against at the time
The “alternatives considered” sentence is the highest-leverage line in any design doc. Not because the alternatives were bad — sometimes they were better. But because it shows the decision was a decision, not a default.
The four questions
I’ve landed on a format: four questions, answered in under 200 words total.
- What did we decide? (One sentence. The artifact or behavior.)
- What were we trying to solve? (The constraint or user problem — not the business goal.)
- What else did we consider? (Two or three alternatives, one sentence each, with the disqualifying factor.)
- What would make us revisit this? (The condition under which this decision expires.)
That last question is the most underrated. A decision without an expiry condition tends to calcify. Writing “this holds until we support multi-tenancy” means it ages gracefully instead of becoming technical debt nobody’s willing to touch because nobody knows where it came from.
The real test
Hand the doc to someone who joined after the decision was made. Tell them nothing. Ask what they’d change.
If they come back with something you already considered — documented right there — the doc worked. They might still disagree with your reasoning. But they’re arguing with your reasoning instead of rebuilding it from scratch.
If they come back with the same alternative you ruled out and wrote up three months ago, there’s a documentation problem. Not a design one.
The goal isn’t a comprehensive record. It’s a legible one.
Five years from now, someone reading your decision doesn’t need the full story. They need enough to not redo the work — and enough to know when it’s finally time to redo it anyway.