Design system

What is in one, and what is only in the document

Most descriptions of a design system are a list of artefacts: tokens, components, patterns, documentation. The list is accurate and slightly misleading, because it describes what you produce rather than what makes it work. Every layer exists in two versions — the one written down, and the one something will actually stop you from breaking.

• Tokens — named values for colour, type, spacing and radius. Unenforced, they become a palette people copy hex codes out of.
• Components — the single implementation of a repeated element. Unenforced, a folder of examples sitting beside a dozen hand-rolled variants.
• Patterns — how components combine for a recurring job, like a page header or an empty state. Unenforced, every page solves the same problem differently.
• Documentation — the reasoning, and the cases where a rule deliberately does not apply. Unenforced, a site nobody opens after the first week.

The distinction bites hardest on small teams, where the system is usually one person's memory. Memory does not fail loudly. It fails as drift — the same heading at five sizes, the same button in three weights — and every individual instance looks defensible on its own.

The failure nobody catches: a rule that is inert

Here is one from our own product, and it is the reason this entry exists. Our display typeface ships in exactly one weight. A global rule set every heading to weight 500, and it did nothing at all, because CSS weight matching resolves a request for 500 back to the only weight the font actually has. The declaration was present, plausible and inert. What made it expensive was the workaround: about 180 of the 223 places using that typeface had gone on to hand-write a weight of 400 to fix a declaration that had never taken effect, and the same surface had drifted to 44 distinct font sizes.

None of that is visible to a type checker, because every one of those variants is a valid style object. It is barely visible in review either: each diff is one line, and each line is defensible. The repair was structural rather than cosmetic — one component became the only place a page heading size may be written, and a test now fails the build when a page hand-rolls its own. That test is the design system. The tokens were only ever a description of it.

What a small team actually needs

• Start from repetition, not from a template. The primitives worth naming are the ones you have already re-typed three times. The rest is inventory you will maintain and never use.
• Put the rule where it is enforced, not where it is read. A shared component, a lint rule or a failing test outranks a page in a wiki, because only one of those survives a hurried Friday.
• Judge changes in composite, never in isolation. A weight or a size looks fine alone and wrong beside a badge, a table header and a bold run of body text. Render the real screen with all of them on it at once.
• Watch for declarations that cannot do anything. A token pointing at something your font, your framework or your content security policy cannot honour is worse than an absent one, because it reads as solved.
• Let the system stop at the edge of your product. Marketing pages and product UI often want different type; scoping an override to one of them is a decision, and flipping the global default by accident is not.

If an AI assistant is writing your interfaces, this matters more rather than less: a model reaches for the median unless something narrows it, which is the gap that design-rule packs like UI UX Pro Max try to close. Consistency is also the cheapest kind of credibility on the pages where somebody is deciding — the same reason Core Web Vitals and conversion work tend to arrive in the same month.