The Design System Is a Contract, Not a Component Library

Two engineers build the same button the same week. Neither is wrong. One reads the design file and sets the highlight around it at two pixels, the other inherits three from the framework. Nobody notices for a quarter. Then a designer files a bug, and the argument that follows is not about pixels. It is about who decides.

That argument is the real subject of every design system. The components are downstream.

The problem was never handoff

Most writing on this topic treats a design system as a translation device: designers make things, engineers rebuild them, a shared library reduces the loss in between. Search the term and the first page is almost entirely definitional. All accurate. None of it useful to a team that already has a library and still ships inconsistent products.

Handoff is a symptom. The disease is two functions making the same kind of decision independently, repeatedly, faster than informal agreement can absorb. A component library gives them a shared noun. It does not give them a shared rule for what happens when the label is translated into German, or when somebody needs a variant that does not exist yet.

Growing a frontend and QA team from four engineers to fifteen changes what a design system is for. At four, consistency is a conversation — everyone is in the same review, and the person who set that highlight is sitting there. At fifteen, across time zones and feature teams, the conversation stops happening and the decisions still get made. Culture has to become a document with an owner. That is the move from library to contract, and it is organisational before it is technical.

What the contract has to cover

A contract is only as good as its clauses. Most systems write one — here are the components — and leave the rest to inference. There are nine.

The named values and, more importantly, the rule for when each applies. Component behaviour: states, keyboard interaction, focus order, error handling, what happens with content the designer never mocked up. Accessibility: the floor below which nothing ships. Responsive rules: what may change across screen sizes and input methods. Ownership: who is accountable when the answer is unclear. Contribution: how something new gets in. Review: what has to be true before it does. Release: how change reaches people without breaking them. Adoption: whether anyone is actually using it.

Every clause you leave unwritten becomes a recurring meeting. That is the cost of an incomplete system, charged weekly.

Named values are the clause everyone writes first and reads last

Design tokens — the named values behind every colour, size and spacing decision — finally have a shared format. The Design Tokens Community Group published its first stable version in October 2025, so design tools, build tools and documentation platforms can exchange the same data without custom glue. Stated plainly: it is a community report rather than a ratified web standard. Widely implemented, binding on nobody.

The format is the simple part. The contract is in the naming. blue-600 records a fact. surface-interactive-pressed records a decision, and a decision is the only thing a second person can apply without asking. Teams that stop at the palette have written a variables file and called it a system.

The stress test is how many surfaces you ship to. We have owned UI and UX for a product that shipped to a phone, a television and an industrial panel from one codebase — a phone at arm’s length, a television at three metres, a panel operated with gloves on under glare. Contrast, target size and spacing cannot be one value each in that world. They have to be one rule each, expressed per context — exactly the thing a component library has nowhere to put. Our connected TV and mobile work starts there.

Behaviour is the clause that ends arguments

The most expensive ambiguity is behavioural, not visual. What does this control do when someone presses Escape, when the network is slow, on the third failed attempt.

Two external references do most of this work. The W3C publishes a guide to how each common pattern — dialogs, tabs, dropdowns — should behave for someone using a keyboard; it settles arguments by convention rather than force. WCAG 2.2 is firmer: pages must stay usable when zoomed right in, and targets must be big enough to hit reliably. Both are properties of components. Encode them once and they leave every future design review.

Then there is text. The shortest interface labels expand most in translation, often to two or three times their English length. When we wired translation into a product whose components had been designed against English labels, the result was not a translation bug. It was a component bug, in every component that had assumed its own width.

Accessibility belongs in the clause, not the addendum

Accessibility in an end-of-project checklist gets renegotiated every project, usually by whoever has the least leverage that week. Put it in the component and it is negotiated once. That is why our brand and design systems work treats the WCAG 2.2 AA baseline as a property of the building blocks rather than a phase of the build — the operational half of the argument in accessibility became operational. Regulation set the deadline. The design system is where an organisation meets it.

Contribution, review and release are where systems die

A 2026 practitioner survey — self-selected, 147 respondents, a signal rather than a census — reports adoption as the top challenge for the fifth year running. It finds 69 per cent of teams allow anyone to contribute while only 36 per cent are satisfied with how that works, and 5 per cent measure return at all. That describes systems built as artefacts and never given an operating model.

Public systems that survive publish their acceptance bar. The GOV.UK Design System requires a proposal to prove it is useful across services and not a duplicate, then tested with real users including disabled users. Whatever you make of that bar, it is written down — so a rejection is a process outcome rather than a personal one.

Governance answers an unfashionable question: when the person who built this leaves, who approves the next change. We ship systems as code plus documentation, in the client’s repository, so the answer can be someone on their team — and where it stays with us, it stays with a named engineer under platform care.

A five-person team needs none of this

A five-person team shipping one product needs none of this, and telling them otherwise is how consultancies sell work nobody asked for.

At that size the contract already exists, in the heads of the people writing the code, and it is cheaper there. A formal programme adds proposal templates, review queues, versioning discipline and a maintainer whose time is not going into features. With most system teams already short of people, adding ceremony to a team of five is a real cost against a speculative benefit.

The threshold is not headcount, though headcount correlates. It is the point at which the same decision gets made independently more than once. Three signals: two teams ship to the same surface with no shared review; the same component exists twice and has drifted; a designer and an engineer can no longer name who decides. One is a conversation. Two is a backlog item. Three means you are already paying for a system informally and getting none of the return.

A maturity model for deciding what you actually need

This is judgment, not a researched finding, but it holds across the engineering work we take on.

Tier 1 — the values. Named colours, type and spacing, in code, named after intent. No component library, no governance. Correct for a single product with one delivery team. Cost: days. Skipping it defers a rename rather than saving time.

Tier 2 — a component library with a written contract. The values plus components carrying their own states, keyboard behaviour, accessibility floor and responsive rules, documented where engineers actually read. No formal contribution process — the maintainers are the builders. Correct when two or more teams use the same interface, or one team ships to several surfaces. Most organisations should stop here.

Tier 3 — an operating model. Everything above plus named ownership, a written acceptance bar, versioned releases with a path for retiring things, a route for contributions and a measure of adoption. Correct when the system’s users cannot all fit in one room and the drift is costing visible delivery time. It requires funded people; without them you get the worst outcome available — rules with nobody to apply them.

Diagnose by the tier your problems are at, not your ambition. A team arguing about hex values needs Tier 1. One arguing about how a dialog handles the keyboard needs Tier 2. One arguing about who gets to say no needs Tier 3, and no quantity of components substitutes for it.