Tech & Leadership
Your Git History Is a Better Design Portfolio Than Figma
My wife’s a product designer, and over lunch the other day she asked me: “How do you keep track of decisions when you’re building stuff?”
Her company had been pushing designers to use AI coding tools for prototypes lately, and she was trying to figure out where the decision-making goes. I’ve been noticing the same trend across the industry. Designers are increasingly expected to deliver fully clickable prototypes with shareable URLs, not just static screens. The deliverable is shifting from “here’s a Figma file” to “here’s a working thing you can click through.” And that means the work is moving into code, whether designers planned for it or not.
In Figma, there’s version history, comments, and old explorations all sitting in one file. When the work moves into code, all of that disappears.
I pulled up my GitHub commit history on a side project and we spent the next five minutes going through it. Every decision, every dead end, every pivot was right there in the log. Then I asked Claude Code to summarize those commits and piece together a narrative, and it was able to tell the story of the project back to us better than I could have from memory.
The Archaeology Problem
Here’s the problem as my wife described it. When a new designer joins a team, they inherit the current state of the product. If the team had been working in Figma, there’s a record of decisions. Old files, abandoned explorations, version history, comments explaining why a card layout was rejected in favor of a list view. It’s a little scattered and messy, but it’s still there, and a new designer can dig through that and piece together the reasoning with some narration.
When the work moves into agentic coding, that record disappears. The new designer sees the live app and suddenly has to reverse-engineer intent from the code. Why is the checkout three steps instead of two? Why does the nav use this information architecture? Why is one component custom when everything else has a design system counterpart?
The answers to those questions are the actual craft.
The final product doesn’t show you the five things that were tried and rejected, it just shows you what survived and made the cut.
Hearing all this, I think it’s valid. But I think the solution was sitting right there in the workflow. GitHub commits, honestly.
Five Pivots in Three Weeks
This one time at work, my team went through a major product consolidation. Two separate payment flows needed to become one. The kind of project where the end result looks obvious in hindsight, but the path to get there was pretty complex.
Over three weeks, the team made five significantly different directional changes. Each one had a clear “why we chose this instead of that” behind it.
Pivot 1: “Build it” became “Map it first.” The team had a spec and was ready to start building. Then during review, they realized the two systems they were merging behaved more differently than anyone expected. Instead of coding from assumptions, they stopped and spent a week documenting how things actually worked. A new designer joining today would see that final architecture and think it was always the plan. It wasn’t. It was a course correction because the spec was wrong, in ways that were only discovered through more investigation.
Pivot 2: Accepting a later deadline on purpose. The launch date had slipped. We were working with another cross-team dependency, and it happens. Not because of a failure, but because the team chose to use the extra time to get their edge cases right. A timeline change like that is really invisible in the shipped product.
Pivot 3: Shipping with known gaps. Three specific features couldn’t be built in time. The team ended up documenting each gap, the mitigation for each one, and why full parity would have blown the deadline. These were all in the PR descriptions, including the trade-offs and fast follows that we’d need to do post-launch.
Pivot 4: Choosing not to decide. The team debated two technical approaches, started leaning toward one, then realized they didn’t have enough information to commit. Instead of guessing, they documented the options and deferred. That restraint of intentionally choosing not to pick a direction until they had real data ended up in the PR descriptions as well.
Pivot 5: Drawing a line on ownership. Some members of the team had no experience with the platform we were building for, and a previous cross-platform effort had been painful with lengthy code reviews and lots of required pairing time. Instead of repeating that, we split ownership cleanly. We owned the decisioning service, they owned the customer-facing experience. If a new designer inherited this project, they might think the product ownership lines were always that way.
All of those pivots were captured in the commit history. The reasoning, alternatives considered, even the reverts. Timestamped and searchable.
Commits as Design Journals
The final product shows what survived. The commit history shows what was tried.
I ended up giving this advice to my wife, and I’d share it with anyone worried about losing design intent in code-based workflows.
Commit like you’re narrating decisions, not logging output. Claude Code is more than capable of writing commit messages how you want it. It can bake the “why” into the message, it takes minutes to set up, and it creates permanent context that persists for every single project from then on.
Don’t clean up the dead ends outside of commits. Each change should be a separate commit, and that history becomes the design rationale. A designer’s instinct may be to tidy up and only show the polished version, but the messy history is part of the iterative process that makes any given project.
Commit the rejection, not just the selection. Frequently in my work, I’ll add something, realize it created more problems than it solved, and replace it with something more refined in the very next commit. All of those commits end up in the history, and now anyone reviewing can see the direction I explored, why I abandoned it, and what I chose instead.
Branch names and commit scopes tell a story at a glance. When I look back at my project history, the commits naturally group into arcs: audio feel, difficulty balancing, visual theme, core mechanic tuning. Designers could do the same thing. style(onboarding): ..., fix(accessibility): ..., explore(dark-mode): .... Someone skimming the log immediately sees the shape of the thinking.
The Fear Is Backwards
Designers have always struggled to show process. Mood boards, sticky notes, whiteboards, Slack threads. These are all fragile artifacts that get stale quickly. Commits are better than all of them because they’re timestamped, diffable, and permanent. They don’t end up lost in a folder reorg or when someone leaves the company.
I ran git log on my weekend project and got a complete narrative of every creative decision I made, the experiments that failed, the moments I changed direction, and the reasoning behind each choice.
I didn’t write any of that as documentation. It just emerged from working in a commit-friendly way.
The new designer joining your team doesn’t need a graveyard of old Figma boards. They need to know what was tried, what was rejected, and why. That’s what good commit hygiene gives them, an archaeological record that’s richer than any static mockup.