A design system small enough to actually use

Many design systems start with ambition and end as a file nobody opens. The ones that last tend to be small: a handful of decisions, written down clearly, and shared by design and code.

Why design systems stall

The usual pattern is familiar. A team spends weeks documenting every possible component and variant before the product needs them. The library grows faster than anyone can maintain it, the code drifts from the design file, and people quietly go back to copying the nearest screen.

A system is only useful if it is the easiest way to build the next screen. That means it has to be small enough to learn, and close enough to the code that it stays true.

The smallest useful set

Tokens

Tokens are the named values everything else is built from. Start with:

• Color: a background, a surface, text in two or three strengths, one accent, and states for success, warning, and error. Define a dark theme at the same time if you need one.
• Type: one or two typefaces and a short scale, such as five or six sizes with matching line heights.
• Space: a single spacing scale used for padding, gaps, and layout.
• Shape: one or two corner radii and a border style.
• Motion: a couple of durations and easing curves, so animation feels consistent.

Name tokens by purpose, such as "text-muted" or "surface-raised", rather than by value. Purpose names survive a rebrand; "grey-400" does not.

Components

Most products are built from a short list: button, link, text input, select, checkbox, card, modal, toast, navigation, table, and empty state. Build those well, with every state covered: default, hover, focus, disabled, loading, and error.

Rules beat components

A single page of rules often does more than another dozen components. For example:

1. One primary action per screen.
2. Headings follow the type scale; no one-off sizes.
3. Spacing comes from the scale; if a value is missing, add it to the scale or reconsider the layout.
4. Every interactive element has a visible focus style.
5. Error messages say what happened and what to do next.

Rules give people a way to make good decisions in situations the library did not anticipate.

Tip: write each rule so a reviewer can check it in a pull request. If it cannot be checked, it is a preference, not a rule.

Accessibility built in

Put accessibility into the tokens and components, so every screen inherits it:

• Choose text and background pairs that meet WCAG AA contrast, and check them in both themes.
• Give every component a visible focus state and full keyboard support.
• Keep touch targets comfortably large on mobile.
• Respect reduced-motion settings in the motion tokens.
• Use real semantic elements in code, such as buttons for actions and links for navigation.

Fixing these once in the system is far easier than fixing them screen by screen.

Keep it in step, and keep it small

Design and code in step

The design file and the code should describe the same thing.

Growing it without bloat

Add a component when the same pattern has appeared in a few real screens, not when it might be needed someday. Remove variants nobody uses. Review the system on a regular schedule and treat deletions as progress.

The aim is a system people reach for because it saves them time, not one they work around.

Where to start

Audit three of your most-used screens and list the colors, sizes, and spacing values they actually use. That list, cleaned up, is your first set of tokens. If you want help shaping a visual system or building one that matches your code, see our visual and brand design work, or tell us about your product.