# What a design system is actually for > A component library is not a design system. The difference shows up eighteen months later, when the people who built it have moved on. *Published 2026-07-21 · 9 min read · Design systems, Process* Source: https://www.linesandframes.com/blog/what-a-design-system-is-actually-for ## The short version - A design system is a set of written decisions; the component library is only where those decisions became visible. - Name tokens for their role (surface-raised, text-muted), never for their value (grey-200). - Track local style overrides — each one is a bug report about the system. - Document how a new pattern gets in, or the system becomes a snapshot. Most design systems are commissioned as a library and judged as a library: how many components, how well documented, how closely the code matches the design file. Then eighteen months pass, the original team disperses, and the real test arrives — can someone who was not in the room ship a new screen that looks like it belongs? That test is failed constantly by systems with excellent component coverage, because coverage was never the thing under strain. What fails is the reasoning: nobody remembers which of the three card variants was meant for what, so a fourth appears. ## The system is the decisions, not the components A button is not a decision. The decision is that this product has exactly three levels of emphasis, that destructive actions never sit adjacent to primary ones, and that nothing gets a fourth level without deleting one first. The button is just where the decision became visible. Systems that survive write the decisions down somewhere harder to ignore than a wiki: in token names, in prop APIs, in lint rules, in the shape of the component itself. A system where the wrong thing is inconvenient to build outlasts a system where the wrong thing is merely discouraged. ### Make the constraint structural If there are three emphasis levels, the prop should be an enum of three values, not a string. If spacing comes from a scale, the component should not accept arbitrary margins. Every place you accept a free-form value is a place the system will drift, and no amount of documentation closes that gap under deadline. ## Tokens carry intent or they carry nothing A token named for its value — grey-200, blue-500 — tells the next person what it is and nothing about when to use it. A token named for its role — surface-raised, text-muted, border-strong — makes the misuse visible in review. The renaming cost is a day. The confusion cost of the first naming scheme compounds for years. - Name by role, not by value or hue. - Keep one layer of raw primitives that feature code never touches directly, and one layer of semantic tokens that it always does. - Make a theme swap prove the naming: if a token cannot survive a palette change, it was a value in disguise. - Include state in the name where state matters — surface-hover, border-focus — so nobody hand-rolls a hover colour. The theme-swap test is worth running even if you never ship a second theme. It is the cheapest way to find tokens that encode an appearance rather than a purpose, and it takes an afternoon. ## Document the edges, not the obvious Component documentation tends to explain what a well-named component already communicates, and to go silent exactly where people get stuck: what to do when nothing fits. That is the page worth writing. It should say who decides, how long that takes, and what to do in the meantime — because the alternative to an answer is not patience, it is a local override. 1. Try the closest existing component and note what it cannot do. 2. If the gap is a missing option, propose an additive prop rather than a new component. 3. If it is genuinely new, build it locally first, ship it, and promote it into the system once a second team needs it. 4. Record the decision either way, so the next person finds the reasoning instead of repeating the argument. ## Adoption is a design problem too Teams do not skip the system because they dislike it. They skip it because the component is missing a prop, the docs example does not match their case, or the workaround is faster on a deadline. Every one of those is a fixable design problem, and none of them get fixed by a memo about compliance. > Track the overrides. A local style override is not a violation — it is a bug report about the system, filed in the only language a busy engineer has time for. A practical version of this: grep the codebase for inline styles and one-off class names touching colour, spacing and radius, then rank by frequency. The top five tell you what the system is missing, in priority order, with no meetings required. ## How to tell whether yours is working - Time to ship a new screen by someone who has never shipped one before. - Number of local overrides added per month, trending down without enforcement. - Share of new patterns that were promoted into the system rather than abandoned in a feature branch. - Whether a designer and an engineer describe the same component the same way, unprompted. None of those are component counts, and none require a survey. The systems we hand over are deliberately smaller than clients expect, with more written about the edges: what to do when nothing fits, who decides, and how a new pattern gets in. That last part is what makes it a system rather than a snapshot. ## Questions we get asked ### What is the difference between a design system and a component library? A component library is a set of reusable UI parts. A design system is the set of decisions those parts encode — how many levels of emphasis exist, what a surface means, when a pattern is allowed — plus the process for changing them. A library without the decisions drifts as soon as its authors leave. ### How should design tokens be named? By role rather than by value. surface-raised, text-muted and border-strong make misuse visible in review; grey-200 and blue-500 tell you what a colour is but nothing about when to use it. A useful test: if a token cannot survive a palette change, it was a value in disguise. ### How do you get a team to adopt a design system? Treat non-adoption as a design problem, not a compliance one. Teams skip a system when a prop is missing, the docs do not match their case, or the workaround is faster under deadline. Track local overrides and fix what they point at. --- © Lines & Frames — https://www.linesandframes.com