Why the First Version of Every Component Is Always Wrong
The first version of a component is always wrong.
Not wrong like bad design wrong. Wrong like “this is how you find out what the real problem is” wrong.
This is true for every component on every product I’ve ever worked on. The first version is the price of admission — the thing you build to learn what you should have built instead. You don’t know enough at the start. You know exactly enough at the end of the first cycle. By then, it’s too late to go back and document the reasoning while it’s still live in your head.
Which is exactly when you should.
The iteration is the knowledge
Most design teams treat the iteration as a cost. The first version wasn’t good enough, so you improve it. That’s the story.
What most teams miss: the gap between version one and version two is where the design system knowledge actually lives.
Not in the current component. In the specific thing that was wrong about the first one — and why it was wrong in a way you couldn’t have predicted at the start.
Version two doesn’t make version one irrelevant. It makes version one the most interesting document in the system. “We tried X, and X failed because of Y, and we didn’t know about Y until [specific situation] happened” — that’s the documentation that stops the next person from rebuilding version one from scratch.
Without it, someone will. Probably in six months. Probably with a lot of enthusiasm.
What to capture, and when
The window is short. Two weeks after you ship version two, you won’t remember why version one failed. You’ll remember that it did. The specific constraint — the technical edge case, the user behavior you hadn’t anticipated, the brand rule that didn’t surface until the second round of stakeholder review — that’s what disappears.
Three things worth capturing before the memory goes:
- The assumption you started with — not the goal, but the underlying assumption about the problem that turned out to be wrong
- The specific situation that revealed it — a real example, one sentence, concrete enough to be reproducible
- What version two preserves — sometimes you fixed the failure but kept a constraint from version one; document which constraints survived and why
That’s it. Not a post-mortem. Not a design spec. A record of what version one got wrong and what you actually learned from it.
The uncomfortable part
Documenting failure is psychologically harder than documenting success. Version two exists because version one failed at something. Writing that down means admitting the first version failed.
It did. That’s not an indictment — it’s how design works. The first version is always a hypothesis. The iteration is how you test it.
But only one of those things tends to end up in the documentation.
The first version of a component is always wrong. That’s not the problem. The problem is treating it as something to move past instead of something to understand.