How to Document Design Decisions

Design decisions get made all day, every day. Why the navigation is on the left instead of the top. Why you chose this pattern over the alternative. Why the button copy says "Start free trial" and not "Sign up."

Most of these decisions live in the designer's head, in a meeting recording nobody will watch, or nowhere at all. Then a new team member joins, a stakeholder asks why something works the way it does, or you revisit the same decision six months later having forgotten the rationale.

Documenting decisions doesn't mean documenting everything. It means documenting the ones that matter — and doing it in a way that's fast enough that people actually do it.

Why documenting decisions matters

New team members. A designer who joins your team can read decision logs and understand why the product looks the way it does — without booking four hours of meetings to get the background.

Future you. You will revisit design decisions you made six months ago and want to know the rationale. "I remember we discussed this but I can't remember why we chose this approach" is a universally shared experience. Decision logs prevent that.

Stakeholder alignment. When a stakeholder asks "why does the onboarding work this way?", a documented decision is faster and more credible than reconstructing the answer from memory. It also shows that decisions were made thoughtfully, not arbitrarily.

Preventing repeated debates. Undocumented decisions get relitigated. Someone new joins the project and raises the same question that was resolved two months ago. If the decision is documented with rationale, you can close the debate by sharing the document.

What to capture

For each significant decision, record four things:

The decision. What was chosen. "We will use a sidebar navigation instead of a top navigation bar."

The alternatives considered. What else was on the table. "We evaluated top navigation (discarded because of limited horizontal space on 1280px viewports), tab bar (discarded because we have more than 5 primary sections), and a hamburger menu (discarded due to discoverability concerns)."

The rationale. Why this option won. "Sidebar navigation gives us expandable submenus, maps to how power users think about the product sections, and has precedent in comparable B2B tools our users already use."

The date. When the decision was made. This matters when circumstances change — a decision made based on a constraint that no longer exists might be worth revisiting.

You don't need to write an essay. Four short paragraphs or a two-column table handles most decisions.

Where to document

The right location depends on the type of decision.

Notion is best for standalone decision documents — anything that benefits from being findable, linkable, and searchable outside of a specific design file. Design system decisions ("why we use this spacing scale"), product direction decisions ("why we're prioritizing desktop over mobile this quarter"), and process decisions ("how design reviews work") all belong in Notion.

Create a "Design Decisions" database in Notion with columns for: Title, Date, Project/Feature, Decision Status (Current/Superseded), and a link to the relevant design file. Filter by project to see all decisions for a specific feature.

Figma is best for design-adjacent decisions — notes that belong close to the screens they affect. Use Figma comments to capture a decision at the exact frame it relates to. If you're making a decision about why a specific component works a certain way, a comment on that component is the right place for a brief note. For more substantial documentation, link to a Notion page from the Figma comment.

Linear is best for implementation decisions — choices made at the point where design hands off to engineering. When you create a Linear issue for an engineering task, document in the issue description any design decisions that directly affect implementation: "The hover state uses a 200ms ease-out transition, not instant." This keeps developers from having to ask.

Try Notion Free

Templates that actually get used

The reason most documentation systems fail: the template is too long. A seven-section template for a decision that took five minutes to make is disproportionate effort.

A template that works:

**Decision:** [one sentence]

**Why:** [two to three sentences — the reasoning]

**Alternatives we considered:** [list, one line each]

**Date:** [date]

**Owner:** [who made or owns this decision]

That's it. It takes three minutes to fill in and contains everything someone will actually need to understand the decision later.

Decisions worth documenting vs decisions that aren't

You can't document every micro-decision. Prioritize decisions that:

• Had real alternatives (there was a choice to be made)
• Affect multiple screens or features
• Were debated before being resolved
• Might be questioned by stakeholders or new team members
• Will affect how future work is done

Don't document:

• Taste-based choices with no functional implication
• Decisions that are obvious from the design itself
• Temporary decisions (clearly mark anything that is temporary and why, then revisit)

Design in Figma

The goal is a lightweight record of reasoning, not an audit trail of every click. Ten well-documented decisions from a project are far more valuable than a hundred poorly-documented ones that nobody reads.