What actually belongs in a design system

Ask ten designers what a design system is and you'll get ten answers. Principles, voice and tone, accessibility guidelines, governance, contribution models, documentation sites. All valid. None of it is what this post is about ...

I'm talking about the hands-on part. The tokens and components in your Figma library that designers work with every day and developers turn into code. That's the part that actually ships, and it's where most systems get messy first.

Open most of these libraries and you'll find things that don't belong there. An exchange widget. A calculator UI. Components built for a single feature, sitting next to the button and the input.

It happens for understandable reasons. A deadline hits, a component gets built, and the library is the nearest shelf to put it on. But every use-case specific component you add makes it less of a system and more of a project archive.

A design system outputs building blocks, not features

The job of a design system is to define the language. The project's job is to use that language to say something specific.

A button is language. A calculator is a sentence. The button belongs in the system because every product needs buttons. The calculator belongs in the project because only that product needs a calculator.

Mix the two and the system stops being reusable. It gets tied to the product it was built for, and the next project either inherits irrelevant components or forks the whole thing. Either way, you've lost the point of having a system.

The three layers

1. Design tokens. The raw scale: colors, spacing, radius, typography. The primitives everything else inherits from.
2. Core components. Button, input, badge, card, label, dialog. Anything reusable across any project, product or context.
3. Use-case specific components. The calculator, the exchange widget, the checkout form. Built with the design system, never inside it.

The first two are the system. The third is the project.

Where use-case components actually live

At Boiling Brains we build use-case specific components in the project, not the library. Here's how we set up our Figma files:

1. Design library. Tokens and core components. This is the source of truth, and it stays generic.
2. Local components. Use-case specific components for this project. The calculator lives here. It pulls core components from the design library, extends them and adds the variants the feature needs.
3. User flows. Screens mapped together with their interactions. The actual product experience.

The calculator uses the system but lives one layer up. The design library never knows it exists, which is exactly how it should be. Update a token and the change cascades through the core components into the calculator, without the system ever being aware of it.

A simple test

Ask one question: could this component appear in a completely different product, for a completely different company, without changes?

• If yes, it's a core component. It belongs in the system.
• If no, it's use-case specific. It belongs in the project.

A button passes. A "convert USD to EUR" widget doesn't. That's the whole test.

Why this matters more now

AI agents read your Figma metadata to generate code. A clean system of predictable core components, named to match the code, is easy for an agent to work with. It maps what it sees to real components and produces clean output.

A system bloated with one-off components is noise. The agent has to guess what's reusable and what's a one-time feature, and the output gets worse. Keeping the system generic isn't just good hygiene anymore. It directly affects how well your design-to-code pipeline works.

Start from a clean system

This is the thinking behind BBUI, our Figma component library inspired by shadcn/ui and Tailwind. It deliberately ships only what belongs in a system: design tokens and core components, named to match the code and ready to build on.

It doesn't ship use-case components, because that's not its job. It gives you the building blocks, so you can build whatever your product needs in the project layer, on a foundation that's already clean and code-aligned. We built it for our own client work. Now we're opening it up.

Join the early access waitlist

The takeaway

The design system is the foundation, not the building. Keep it generic, keep it reusable, and push everything product-specific up into the project layer. The systems that stay clean are the ones that outlive the project they were built for.