A design system is a set of decisions

We have handed over design systems with 200 components and watched them fall apart within a year. We have handed over systems with 30 components that are still in good shape. The difference was never the number of components. It was whether the team understood the decisions underneath.

Write down the why

Every token in a system is a decision. A colour that is only used for large text. A corner radius that applies to buttons but not to images. A duration that is fast because it gives feedback, not because it looks nice.

If those reasons live only in a designer’s head, the next person will make a reasonable choice that quietly breaks the system. So we write them next to the values:

--signal-text: #8a5708; /* Accent as text. Passes 4.5:1 on paper. */
--radius-ui: 12px; /* Buttons and chips only. Images use --radius-media. */
--dur-fast: 180ms; /* Feedback for hover and press. Never for entrances. */

Fewer components, clearer rules

We would rather ship a small set of components with firm rules than a large set with none. For Marisol, that meant 64 components and one page of rules, including:

• One accent colour per screen.
• Every error message says what happened, why, and what to do next.
• If a new component is needed, it replaces an old one or it does not ship.

Make it visible

A system nobody looks at is a system nobody follows. We build a living style guide into every project: a page that renders the real tokens and components from production code, in every theme. This site has one at /styleguide.

The goal is not a perfect library. It is a team that can make the next decision without us.