Component Spec

A design file usually shows one version of the happy path. The button says Save, the list has five documents in it, the input holds a valid value. That's enough to explain a screen and not enough to build one. Whoever builds it has to decide what happens when the label runs to eighteen characters, when the list is empty, and when the value is wrong.

At Pagedeck the gap showed up the week Theo was implementing the button. Two hours into the design file he had five questions stacked up: whether long text truncates or the button grows, whether disabled dims the label too, what shows while the button waits for a server response. Noa was in a meeting and the answers came three hours later.

Theo didn't wait. He decided all five himself and kept going. At the review the following week, two of them were not what Noa had in mind, and fixing them took another day.

The problem was never that decisions don't get made. They always get made. Without a spec they get made quietly, by one person, at the moment of implementation, and the reasoning stays inside the code where the next person can't see it. A component spec is where that decision gets made once, in advance, in writing.

One spec covers one part. Six things go into it.

1. What it's for and when not to use it. One line on the purpose, plus the situations that call for something else. "Use a link, not a button, for navigation that leaves the screen" belongs here.
2. The values it accepts. A list of what the caller can set, each with a default. Character is one of the primary, secondary, and destructive options split out as variants; size is large, medium, or small; icon is present or absent; width is either content-sized or full.
3. How each state looks. Rest, hover, pressed, keyboard focus, disabled, and loading, described one by one. Loading is the one that goes missing most often, and without it a user presses the same button twice and pays twice.
4. Edge conditions. Whether long text truncates or wraps, how the part folds on a narrow screen, what shows when there is no content at all. This item is closest to the real reason specs get written.
5. Accessibility rules. Where the part sits in keyboard order, what name a screen reader announces, how much brightness has to separate text from background. Accessibility is expensive to retrofit — adding it later usually means rebuilding the part — so it's settled at this stage.
6. Names. The name used in the design file next to the name used in code. When the two match, design handoff, the process of passing a design to the people who build it, stops involving questions about which thing is which.

Colors and spacing here are written as design tokens, named units standing in for values, rather than as raw numbers. Write the background as #2F6BFF and the spec goes stale the day the color changes; write the token name and the sentence stays true no matter what the value becomes.

The designer writes the first lines and the rest gets filled in during implementation. Noa records the purpose, the accepted values, and the states while building the part, and the cases Theo runs into while implementing become item 4. One question turns into one line, so the document grows rather than getting authored.

Three groups read it.

1. The developer building the part. The heaviest reader by far. Questions the spec doesn't answer get asked on the spot, and once an answer is settled it goes into the spec, removing one question for the next person.
2. Whoever verifies the work. Test cases come straight out of the spec. Six states and three edge conditions written down means nine things to check; nothing written down means the list of things to check varies by whoever is doing the checking.
3. Other designers. They come here to see how far a part can be bent for their own screen. General rules about color and spacing live in the style guide; the rules specific to this one part live in the spec.

A spec lives next to the part it describes. Pick a part out of the component library and its spec opens alongside it; on the code side, the docs tab of Storybook, the tool that renders a single part on its own, plays the same role. Kept in a separate document store it takes time to find, and anything that takes time to find goes unread.

"The spec for this button has no loading state, so I made a call on it. Is that right?"

Ran into a case nobody wrote down, decided it alone, and wants it confirmed.

"Let me check the spec first. It says long text truncates."

Looking for a decision that already exists before implementing anything.

"I pulled the test cases from the spec."

What gets checked came out of a document rather than out of somebody's judgment.

The day the modal went in, Theo asked whether Escape should close it, and what happens on a click outside. Noa opened the spec and neither line was there. They decided it on the spot: if there are unsaved changes it asks first, and if there aren't it closes immediately. Noa added that sentence to the spec before the meeting ended.

The next month a different developer used the same modal on the settings screen and the question didn't come up. A spec earns its keep on the second use, not the first. The first time you can just ask the person sitting next to you; the second person doesn't know that conversation ever happened.

Specs often get read as a patch for a weak design file — if the design is thorough enough, there's supposedly nothing left to write. What a spec actually carries is what a design file can't show. A notice that disappears after three seconds, the waiting state when the server is slow, a label that stretched to twenty-two characters: none of these fit on a frozen picture of a screen. However carefully the screen is drawn, that space stays empty, and an empty space gets filled in by whoever is implementing at the time.

The other common belief is that the document has to be complete before work starts, since the word spec sounds like a blueprint signed off in advance. In practice it grows a line at a time out of questions raised during implementation. Trying to cover everything up front produces pages about cases nobody will hit while the questions that actually came up stay missing. That kind of document goes unread within two months.