The Decision Log: Why Top Designers Document the Calls Nobody Asked About

A senior designer and a mid-level designer can ship the same screen. The senior remembers why. The mid-level remembers what.

That gap is one artifact. A short, dated, structured record of every design call with the reasoning attached. The decision log. Most designers do not keep one because school never asked and the last team did not have one. The practice does not propagate by accident.

The teams setting the bar in 2026 already run it. Linear has design RFCs. Vercel ships product specs alongside engineering specs. Anthropic publishes research notes. Stripe runs design review docs. Brian Lovin keeps his on a public personal site. Jordan Singer ships small products with public design diaries attached. Same artifact in every room.

This is the playbook. What a log is, why hiring managers read it first, where the practice came from, the six-field template, where to keep it, real instances, the failure mode, and how to start tomorrow.

The artifact most designers do not keep

The most undervalued artifact in design is the decision log. Not the case study, not the Figma file, not the deck. A short, structured, dated record of every design call with the reasoning attached, written before the work ships.

The cost of skipping shows up quietly. Six months in, the designer cannot say why the form fields stack instead of inline, who decided, or what got cut. Three years in, the portfolio has six projects and zero defensible calls. The designer is mid-level for life.

What a decision log actually is

A structured record of design choices, alternatives considered, constraints in play, reasoning behind the call, owner, and outcome. Six fields, dated, concrete, linked to artifacts. That is the entire definition.

It is not a case study. Case studies present every choice as inevitable. A log shows the choice as it was made, with the alternatives on the table, the constraints that ruled them out, and the outcome the designer now owns.

It is not a meeting note. A log records what got decided and why, even when the call happened in a thirty-second Slack message. The roadmap looks forward. The log looks backward at every call already made, dated, signed, ready to defend.

Why hiring managers prize it more than mockups

Polished mockups show output. Decision logs show judgment. Senior hiring managers in 2026 read the log first because output is AI-cheap and judgment is not.

A model ships a polished landing page in eight minutes. The hiring manager who looks at that page learns nothing about the designer who shipped it. Same model, same prompt, same Dribbble references. The log is the only artifact that survives the AI commoditization of polish, because the log is not the output, it is the trail of choices that produced this output instead of the eighteen others.

The read takes two minutes. The hiring manager opens the log, scans five entries, and sees how the designer thinks. Specific alternatives, named constraints, concrete reasoning, owned outcomes, the willingness to write "I would do this differently now." That is the entire interview, compressed into a doc.

Where the practice came from

The decision log is older than software. Christopher Alexander wrote pattern languages that read as decision logs at the building scale, every pattern dated, named, justified, with alternatives noted. Architects have kept design books for centuries.

Software inherited it through RFC culture. The IETF has published Request for Comments documents since 1969. ADRs (architecture decision records) at Spotify, Pivotal, and Thoughtworks are the same artifact at smaller scale. The most recent inheritance is research labs. Anthropic publishes research notes that read as decision logs at the model level.

Three lineages, same artifact. Designers are the late adopter, and the bar is rising fast enough that late is starting to read as junior.

The six-field template, copy this

Six fields. Decision, Alternatives, Constraints, Reasoning, Owner, Outcome. The template is short on purpose. The discipline is in writing it, not designing it. Copy this block. Use it tomorrow.

Date: 2026-04-30
Project: Acme Onboarding v3

Decision
Stack email and password vertically on the signup screen, no inline
social login row.

Alternatives
1. Inline social login row (Google, Apple, GitHub) above the fields.
2. Two-step flow, email first then password on screen 2.
3. Magic-link only, no password field.

Constraints
- Mobile-first, 360px min width, single column.
- Engineering will not ship social OAuth this quarter.
- Support flagged 14% of tickets as password reset confusion.
- Brand voice rejects "Continue with" social patterns as generic.

Reasoning
Vertical stack ships fastest and matches the brand register. Two-step
tested cleaner in 2024 but added a screen we cannot afford given the
38% drop on screen 2. Magic-link only blocks the password manager
flow 22% of paid users rely on.

Owner
Maya Chen, design. Reviewer: Jordan Park, eng lead.

Outcome (filled 2 weeks post-ship)
Conversion +6.1% vs v2. Password reset tickets dropped 9%. Re-evaluate
magic-link as v3.1 when OAuth lands in Q3.

One entry per real call. Five to ten entries per project. Skip the cover page. The block above is the work.

How to write each field without hedging

Each field has a rule. Skip the rule and the log turns into theater.

Decision. One sentence, present tense, concrete. "Stack email and password vertically." Not "we felt vertical might work." If the call has not been made, do not write the entry yet.

Alternatives. Numbered list, two to four real options that were on the table. Not strawmen. If only one was considered, write that and explain why the search stopped.

Constraints. Bulleted list, named, sourced. Engineering capacity, brand rules, support tickets, accessibility floor, performance budget. Without them, the log reads as taste laundering.

Reasoning. Three to five sentences, no "we felt." Use because. Use compared to. Cite the constraint or the data that decided it. Link the artifact.

Owner. Name the designer. Name the reviewer. Anonymous logs do not survive contact with a senior reviewer.

Outcome. Filled in two weeks to two months after ship, dated. What the metric did, what got revisited, what would change next time. The willingness to write "I was wrong about the magic-link block" is the highest-trust signal in the log.

Where to keep the log

The log lives wherever the team will actually open it. Storage matters less than cadence.

Notion. Easiest team-wide setup. One database, one entry per decision, six fields as columns. Most product teams already pay for it and one designer can stand it up in an hour.

Linear docs. The right call if engineering and design already live there. Decisions sit next to the issues that triggered them, and the rollover into engineering RFCs is one click.

A markdown file in the repo. The right call for design engineers and design system owners. A decisions.md at the repo root or under /docs/decisions/ reads as serious because it is versioned with the code. Engineers respect this format on sight.

A small private blog or personal site. The right call for an individual designer building a public trail. Brian Lovin runs his this way. Static site, dated entries, public links. The piece doubles as portfolio surface and hiring presence.

Pick one. Run it for a quarter. The first move that fails is choosing a tool and never opening it again.

Linear's design RFCs and Vercel's product specs

Linear runs design RFCs as first-class artifacts in their docs. Every meaningful design call ships with an RFC, written before the work, reviewed by the design and engineering leads, archived with the project. The RFC is part of the work, not a write-up after.

Vercel ships product specs alongside engineering specs in the same repo. The design call and the engineering call sit in the same doc, dated, owned, reviewed. The team treats the spec as the contract. When v0 ships a new surface, the spec is part of the launch artifact.

Both teams treat the written rationale as part of the craft. Not a Wednesday afternoon write-up. Not optional. The artifact is the work the same way the Figma file is the work, and a designer who shows up without one looks unfinished.

Anthropic's research notes and Stripe's design review docs

Anthropic publishes research notes that read as decision logs at the model level. What they tried, what worked, what did not, what the next move is. Short, dated, owned, linked. Read three and the practice becomes obvious. The notes are the record, not the spin.

Stripe runs design review docs that survive across product cycles. Stripe Press is the public surface, the internal practice is older. Reviews are written, archived, and revisited when the next cycle hits a similar call. Institutional memory that compounds across years instead of leaving when a senior designer moves on.

If you want help building this into your team's craft, hire Brainy. BrandBrainy ships the craft layer that AI cannot fake. ClaudeBrainy ships the Skill packs and prompt libraries that turn the log from a discipline into a default.

Brian Lovin and Jordan Singer keep theirs in public

Brian Lovin runs a long-running personal site that reads as a public decision log on his own work. Short pages, direct writing, design choices explained in three or four sentences each, dated, linked to the live product. Years of entries. The site doubles as portfolio and hiring presence, which is the dual-use the anti-portfolio playbook leans on.

Jordan Singer ships small products with public design diaries attached. Each project has a written record of the calls behind it, posted publicly, with the willingness to say "this did not work" out loud. The diary is the marketing, the record, and the hiring artifact at once.

Both are templates any working designer can copy this week. Static site, six-field entries, dated, public, linked. Fifteen minutes per entry. Three a month. A year in, the public log reads as senior in a way no Behance case study ever does.

The cautionary part, post-hoc rationalization

A decision log written after the work shipped and the outcome is known is not a log, it is a sales pitch. Senior hiring managers read the difference in two minutes.

The tell is the alternatives field. A live log lists alternatives that were actually on the table, often with one sounding strong. A post-hoc log lists three options the writer never seriously considered, designed to make the chosen option look obvious. The hiring manager has run the same exercise a hundred times. They know what spin looks like.

The other tell is the outcome field. Live logs include outcomes that did not match the prediction. "I expected conversion lift, the test was flat, here is what went wrong." Theater logs only include wins, pre-rounded to look better than they were.

The fix is uncomfortable. Write the entry before the work ships. Date it. Submit it to a reviewer who will push back. Fill in the outcome two weeks later, even when the news is bad. Especially when the news is bad. The honest entry compounds.

How to use the log in interviews and reviews

A log earns its keep twice. Once when the work ships, again when the designer walks a hiring manager or a senior reviewer through the call.

In an interview, the log replaces the case study walkthrough. Open the doc. Pick three entries. For each, read the decision, name the strongest alternative, name the binding constraint, explain the reasoning in two sentences, share the outcome including what would change next time. Five minutes per entry, fifteen total. The hiring manager learns more about judgment than a forty-five-minute case study deck would show.

In a senior review, the log is the conversation. The reviewer reads the entry, pushes back on the reasoning, asks why the strongest alternative was cut. The discussion sharpens the next decision before it gets made. That is what good design review is. Not feedback on rendered pixels, debate on the call behind them.

A designer who can defend the log defends the work. A designer with no log defends nothing.

The new bar, senior work without a log reads as junior

The decision log is no longer a senior nice-to-have. It is the cheapest signal of senior judgment a designer can ship, and the cost of skipping it is rising.

A senior portfolio with a public log reads as senior. One without reads as work that might have been senior, hard to tell. Hiring managers read both. The first one gets the call back. A junior with a log on three small projects reads as ahead of their level. A junior with twelve perfect Dribbble shots and no log reads as the same junior they were a year ago.

Taste is the last moat in 2026 because production commoditized, and the log is the public artifact that proves taste exists in the work. If you ship as a design engineering hybrid, the log doubles as engineering RFC at the design layer. If you are climbing the new design career ladder, the log is the artifact the ladder rests on.

FAQ

What is a design decision log?

A short structured record of design choices with reasoning attached. Six fields per entry: Decision, Alternatives, Constraints, Reasoning, Owner, Outcome. Dated, concrete, linked to artifacts.

How is it different from a case study?

A case study presents every choice as inevitable. A log shows the choices as they were actually made, with the alternatives on the table, the constraints binding the call, and the outcome owned. Case studies sell. Logs document.

Where should I keep it?

Wherever your team will actually open it. Notion for product teams, Linear docs for teams already there, a markdown file in the repo for design engineers, a small private site for an individual public trail.

How long should each entry be?

Short. The full template fits in a screen. Fifteen minutes per entry.

What if my company will not adopt this?

Run it personally. A designer's individual log compounds across jobs. Brian Lovin and Jordan Singer keep theirs publicly. The practice is yours, not your employer's, and the artifact moves with you.

Start the log this week

Three moves. Set up the storage. Pick Notion, Linear, the repo, or a small site. Stand it up in thirty minutes. Pick the one you will open tomorrow.

Write three entries on calls already made. Real decisions from this quarter. Six fields each. Honest alternatives, real constraints, no hedging, outcomes dated and unspun. The first three are the hardest, the rest get faster.

Show the log to one senior reviewer. Ask them to push back on the reasoning. Take the pushback as a signal. Update the entries. The first review is where the log starts to compound.

If you want help building the decision-log practice into your team's craft, hire Brainy. BrandBrainy ships the brand and craft layer that AI cannot fake. ClaudeBrainy ships the Skill packs and prompt libraries that turn the log from a discipline into a default. The teams already running it are pulling away. The bar is rising, and the designer who starts this week is the one the named teams will be reading in a quarter.