Building a scalable color system

Color is an essential component of any design system. Finding a consistent method for naming color tokens is crucial — especially at scale, where your tokens are tested across a large set of elements & components, impacting the whole system.

On this note, I’ll be sharing my workflow for establishing a color token taxonomy. I’ll walk you through my journey of understanding, iterating, and overcoming bottlenecks of different naming conventions. I’ll be starting from a very simple & naive approach, to a final solution that I've successfully applied to multiple products — ranging from simple websites to complex apps.

A naive approach

My initial approach for a color system was quite naive — just call the colors for their literal name. This is similar to the Tailwind approach, where color names are based on their tint/shade value:

This method was very straightforward, but I quickly realized its limitations.

When using names like blue/500 or gray/800, you're not conveying any information about the color’s purpose or context within the design system. From experience, this will lead to confusion, as your team will struggle to choose the appropriate color for specific UI elements.

Additionally, literal color tokens will be extremely limiting when you decide to implement theming (i.e. dark & light mode). For example:

With literal tokens, you can't simply swap these values. You'd need separate sets of color assignments for each mode, increasing complexity and maintenance overhead.

Finally, using a literal naming system creates a tight coupling between the design tokens and their implementation. When a color needs to be updated, it will cause changes across the entire codebase or design file — rather than a single, centralized update. This is a very error-prone and time-consuming process, especially at scale, on larger apps spanning hundreds of screens (trust me, I’ve been there).

Color categorization

After understanding the limitations of literal naming, I shifted towards a categorical approach. Instead of using literal color names, I established a set of key color categories, reflecting the semantic purpose of the color in the UI. From those categories, I created color scales based on tint/shade (similar to what we had before).

Abstracting literal color names was a step in the right direction — having tokens like positive/500 or negative/500 convey the meaning of the color, rather than its literal hue.

We’ve also detached the tight coupling between color & hue. Now, changing the brand color doesn't force us to change the token name. brand/500 can be blue, purple, or green — allowing a single, centralized update that does not affect the naming structure.

We could stop here. But we’re still failing to solve an important issue: how does your team what color to apply to a specific element? Should neutral/200 be used for a card background? Is brand/500 used for the button text, background, or border?

Adding to that, our theming issue also persists — switching from light to dark mode requires changing the color token:

This means you're still dealing with different tokens for different modes, causing token duplication.

Making it functional

It was now time to try something different — I decided to dissociate color tokens from their visual appearance. Instead, each token references a UI property, focusing on color function rather than color value.

Following this method, and distilling a UI to its core, we now have 3 distinct color groups — background, foreground, and border colors.

Inside these color groups, we fit the color categories defined earlier — neutral, brand, positive, and negative colors.

Finally, to further extend the set of color options, we incorporate modifiers that identify the visual weight & prominence of the color in the UI — subtle, strong, faded colors.

By creating a three-tiered property + category + modifier token taxonomy, we create a naming convention that is both highly descriptive and intuitively usable. Each token immediately communicates its function:

This new taxonomy also solves theming: adapting between light & dark mode can now be achieved through a single token. This eliminates the need to switch between different tokens when changing themes.

Notice how the token names remain identical in both modes — only the subjacent primitive tokens change. Abstracting the tokens into a semantic, functional level addresses our theming issues, where previously we needed to use different primitive tokens (like gray/300 vs. gray/900) to style elements for different modes.

Going too far

As we've kept on iterating on our naming system, making it easier to use & understand, it's tempting to take this approach even further — with component tokens. From my experience, component tokens bring a level of specificity that often creates more problems than it solves.

Component tokens attempt to create hyper-specific color assignments for individual UI elements.

At first sight, these tokens look great. They improve usability for design system consumers, by providing extremely specific guidance — there’s no way you wouldn’t know where to apply these. But this specificity comes with hidden costs:

Finding the sweet spot

Through years of iterating on color systems, my takeaway is that the best system isn’t necessarily the most specific or abstract — it’s the one that balances clarity, flexibility, and maintainability. I found my own sweet spot on functional, semantic tokens — they’re not over-descriptive, and from my experience, provide the right level of guidance to designers & developers.

I encourage you to find your own sweet spot — and instead of using a pre-made design system, build one yourself, from scratch.

Starting with a naive approach, as I did, allows you to face challenges firsthand. It's through facing these challenges that you’ll understand what works, and start becoming opinionated on what a great system looks & feels like.