Component Library

Teams agree quickly that a part should be built once and reused. The question that stalls them is the next one: where does that part live?

Pagedeck tripped over exactly this. Noa drew a proper button while building the document list screen, and that original ended up inside the document list design file. Two months later she started the billing screen in a new file and copied the button over from the old one. Six months in there were seven files and seven versions of the button. Some were 40 tall and some were 44, and nobody knew which was correct.

A new designer's question made the situation plain. "Where do I get the button from?" got the answer "the one in the billing file is probably the newest." Having a part and being able to find a part turned out to be two different things. When people can't find it they copy from the screen next door, and that copy is another version.

If a UI component is one part, a component library is the place those parts are gathered so they can be taken out and used. Building parts and keeping them in one managed place are separate jobs, which is why they have separate names.

A library holds more than the parts themselves. Five things travel together.

1. The parts. Buttons, inputs, modals, tabs — whatever gets placed on a screen. A product usually has between 30 and 60, and that list becomes the set of choices available when a screen gets made.
2. The forms and states of each part. Variants split a part by character — primary, secondary, destructive — and states cover rest, hover, pressed, disabled, and loading. Three characters by three sizes by five states means a single button is really 45 cells.
3. The raw values the parts are built from. Colors and spacing are not written into a part directly; the part calls a design token, a named unit standing in for a value. That's what makes adding dark mode a matter of swapping tokens instead of rebuilding parts.
4. How to use them. Each part carries a component spec covering whether long text wraps or truncates, and which situations call for a different part entirely.
5. Version numbers and a change log. Going from 3.2 to 3.3 comes with a note about what moved. People using the library read that note to decide whether to take the update now or after this release.

A library exists as a pair rather than a single artifact: the design file the designers work from, and the package developers import in code. On the code side one part is called a component, and the tool that renders a single part on its own so every state can be checked is Storybook. When the names drift apart, the pair breaks. If the design file's Accent Button is MainButton in code, whether they are the same thing lives only in somebody's memory.

Two people build it; the whole team reads it. At Pagedeck, Noa and Theo own the library as a pair. Built by one side alone it tilts: a designer working solo lands on shapes that are awkward to implement, and a developer working solo accumulates parts that are tidy in code and that nobody looks for in the design file. At 45 people there is no dedicated team, so the two of them carve the work out of their regular jobs.

Three groups read it.

1. Designers making screens. They check the list before drawing anything. When the available parts are fixed, making a screen turns from drawing into choosing.
2. Developers building screens. They look up the code part by the name written on the design. Matching names make a screen an assembly job; a part that isn't in the library means building that one spot from scratch.
3. Whoever sets the schedule. When Mia gets a new design, the first thing she counts is how many parts aren't in the library. Two of them means a few extra days of engineering, so the list becomes material for the schedule conversation.

What goes in and what comes out isn't left to the two owners' discretion. Who decides on a request for a new part, and who gets told when an existing one changes, is settled in advance — those operating rules are called design system governance. Without them there are twelve kinds of button within six months, and once the list gets long enough people stop searching it and go back to copying from the screen next door.

"That one's already in the library. Don't draw a new one."

A part for this already exists, so don't build a second one.

"Library 3.3 is out. The error text on inputs moved below the field."

The source changed, so files and code need to take the update.

"Two of the parts on this screen aren't in the library, so we need more time."

Something has to be built from scratch, which stretches the implementation estimate.

All three showed up in one meeting about the pricing revamp. Mia asked when it could ship. Noa scanned the design and pointed out that the sort toggle in the table header wasn't in the library. Theo said a proper new part would take three days and bending an existing button into shape would take one. The three of them decided to bend the button this time and add the sort toggle as a real part next quarter.

That conversation works because the list sits in one place. With parts scattered across seven files, just counting what's missing takes half a day.

It's easy to assume that building the library makes the parts get used. Good parts are gathered, so using them seems like the obvious outcome. What actually decides it isn't quality but findability. If names are internal shorthand or the categories follow the maker's mental model, someone searches for thirty seconds, gives up, and copies from the screen next door. Once copying starts a second set grows outside the library, and the original problem is back.

The other common belief is that this is a one-time build. A list of parts looks like the kind of thing that gets finished. But a growing product produces screens that didn't exist before, and new screens usually want one part the list doesn't have. A library that stops being updated diverges from the real screens within six months, and after that people treat the most recent screen as the reference instead. Keeping it current costs more than building it, so the decision to build one includes deciding who maintains it.