Design System

With five screens nobody needed a word for this. Drawing a button meant copying the button from the previous screen, and if a color drifted a little, laying five screens side by side made it obvious. The standard was never written down anywhere. It lived in the head of the one person doing the drawing.

At a hundred screens with three people drawing, that arrangement broke. Buttons everyone assumed were the same blue turned out slightly different from screen to screen, and nobody could say which one was correct. One person had copied from a mockup six months old, and another had picked a blue by eye on the day.

At Pagedeck the problem surfaced while a new document sharing screen was being built. Noa was drawing a delete button, opened the existing screens to check, and found three different reds. She asked which one was right, and since all three were shipping in the live product, nobody could answer. Meanwhile Theo had been writing fresh button code on every screen. The mockups differed just enough that nothing could be reused, so changing one button meant opening twelve files. Over the same stretch Noa pushed a new screen back three days because she couldn't settle which of the three reds to follow. That's why raising the contrast on gray text for accessibility went from a two-day job to a two-week one.

The problem isn't that anyone was lazy. When a standard lives only in memory, it splits as fast as the team grows. Three people remember three blues, and when a fourth person joins there's nobody to ask, so a fourth blue gets picked by eye. The splitting never happens on one dramatic day. It accumulates a little each week, and three years later the product uses seventeen shades of gray.

A design system is the machinery for putting that standard outside people's heads. Values like colors, type sizes and spacing get names and get written down, the screen parts used most often get built once, and a document records when to use what. The point is that designers and engineers use the same names, so the system only earns its keep once the color chosen in a mockup and the color baked into the code resolve to the same source. Tidy the mockups while the code stays as it was and all you've built is a second standard.

The terms under this one fall into three groups: what the system is made of (building blocks), the order in which those pieces are stacked up (method), and how the thing is run once it exists (operations).

Building blocks covers the material that actually goes into a system. There are six terms, layered by whether the thing is a value, a part, or a document.

1. Design token — the smallest unit, a name attached to a value such as a color, a spacing step or a type size. Instead of writing #2F6BFF, you write color-accent-default, and both the mockup and the code call that name. Names mean a value can change in one place and the whole product follows, and they make things like dark mode possible, where the same name has to carry a different value.
2. Component library — the place where screen parts such as buttons, inputs and modals are built once and collected. Parts are made out of tokens as raw material, and screens are assembled by picking parts. It's also where most of the hands-on work goes.
3. Pattern library — a collection of solutions to recurring situations rather than of parts. Asking once before deleting, what to show when a list has nothing in it, how to tell someone a save failed. If parts are nouns, these are closer to sentences.
4. Style guide — the document describing when and how to use colors, typefaces and spacing. Where tokens attach names to values, this decides the situations those names belong in. A sentence like "use the accent color once per screen" goes here.
5. Variant — the several forms one part takes depending on its role. One button might carry primary, secondary and danger, plus large, medium and small. Branching inside one part instead of multiplying part types means whoever uses it answers two questions rather than scanning a list of thirty buttons.
6. Component spec — the document recording a part's properties, states and rules. What it looks like when disabled, whether long text wraps or gets cut off, what the minimum width is. A mockup only shows the one case that worked out neatly, so without this document the engineer decides every other case alone.

Method covers the order in which that material gets stacked. Atomic design is the most widely used frame. Rather than drawing a whole screen, you settle the smallest pieces first and combine upward: start with pieces like type and color, build clusters such as a search field with an input and a button attached, gather those clusters into a header, and only then fill in the screen. The bet is that settling small things first leaves fewer decisions when the large screen arrives. Hold strictly to five layers, though, and teams end up spending more time arguing about which layer a new part belongs to, so many teams trim the layer count to about three or rename the layers in their own words.

Operations covers running the system after it's built. There are two terms, one being the rules and the other being what shows up when those rules go slack.

1. Design system governance — the operating rules for who is allowed to change what. Who decides when someone requests a new part, who gets told when an existing part changes, and what justifies an exception. Let anyone change anything and the standard splits again within six months; let one person hold the keys and that person becomes the bottleneck the team routes around.
2. Design debt — the cleanup cost accumulated by postponing consistency. Building a one-off part outside the system to hit a deadline saves two days that week, and once that part has spread across six screens, fixing it costs two weeks. The postponed amount grows over time the way a loan does, which is where the name comes from. So does the fact that at the moment of postponing, nobody knows what the amount will turn out to be.

The three groups stack in order. Building blocks have to exist before method has anything to stack, method has to be settled before the order of work is clear, and without operating rules the first two scatter within six months. Each individual part built here is a UI component, and a design system is the name for those parts bundled together with the rules for using them. The difference between a team that has all three groups and a team that doesn't shows up the moment a new screen gets built. With them, a new screen is a matter of choosing among things that already exist. Without them, it starts again at how tall the button should be.

"Don't redraw that one, use the button in the library. There's a danger red in the variants."

You're rebuilding something that exists, so take what the system already has.

"Don't hardcode the color value, call the token name. Otherwise we redo all of it when dark mode lands."

The convenient move today is the one that forces a full pass later.

"No new parts this quarter, we're cleaning up first. We have seventeen grays."

Feature work pauses while time gets booked to pay down accumulated design debt.

Pagedeck built its first design system right after the Series A. Noa spent two months sorting colors and type sizes into twenty-six names and building four parts to begin with: button, input, modal and table. Four, because those were the ones that showed up most often in the actual screens; the rest were added one at a time as they became necessary.

Theo built the code-side parts under the same names. Half the work was making sure color-accent-default in a mockup and the identical name in the code resolved to the same value. After that, raising contrast for accessibility became a matter of changing three token values. It's the same job that had stretched from two days into two weeks.

Adding a new part means asking Noa. Using something outside the system on an urgent screen is allowed, as long as that spot goes on a list. Every quarter the list gets opened and split into what comes into the system and what simply gets deleted. Mia puts that cleanup time into the quarterly plan in advance, having confirmed in the first year that time set aside for leftover hours never arrives. The first quarter's list held nine exceptions: four came into the system, and five were deleted along with the screens they lived on.

The most common mistake is reading a design system as a deliverable you finish once. A file and a set of documents give you something tangible, so it looks like a project, and wanting to declare it complete comes naturally. But the system changes when the product changes. New features need new parts, unused parts linger, and polishing the brand shifts the colors. Leave it sitting as a finished thing and within six months it's a document describing something other than the live product, at which point nobody opens it again. Teams where this actually works attach an owner and a change procedure to the system, and book time each quarter to compare it against the real screens. Pagedeck pins that comparison to a two-hour slot in the first week of the quarter. It's where someone walks the live screens, finds the parts built outside the system, and adds them to the list.

The second mistake is believing a design system limits creativity. It sounds like an instruction to use only the approved parts, which feels like a narrower range to draw in. What actually narrows is the number of decisions that have to be made again from scratch. The time that went into choosing a button height, a corner radius and a type size on every screen gets freed, and it goes toward questions like which layout gets the user's task done faster. The version without constraints is the one that tends to flatten the result, because different people make different choices and the differences are accidental rather than intended. When a genuinely new screen is needed, it gets built outside the system and the fact gets written down. The difference between the two stories is that this is a default, not a prohibition.