Nov 2, 2025
When I first started building the Gameplan Design System, a lot of what I did was trial and error. Sure, there was research behind many of the decisions, but when it came time to actually make choices - names, tokens, structure - I often had to just go for it.
Anyone who’s built a design system knows that the naming and structure of components are just as important as the components themselves. In a way, you’re not just designing buttons, modals, or inputs, you’re designing a user experience for designers and developers. I like to call it designer experience.
Early on, I focused on getting things to work visually. When it came to naming colors and styles in Gameplan, the system looked something like this:
PrimaryPrimary LightSecondarySecondary LightSuccessSuccess Light
It worked. It was simple. It made sense, to me, at least.
But over time, problems started to show. When a new designer joined the team or a developer jumped in to apply these styles, they’d often ask:
“What exactly is Primary Light used for?”
And that’s when I realized that the naming itself was a UX problem. It wasn’t intuitive. You had to already know the context to use it correctly.
One of the hardest but most valuable skills in design (and in life) is admitting when you’ve made a mistake. It’s uncomfortable, but it’s also the first step toward learning something better.
When I started my next project, Rankat, I decided to revisit the color naming problem from scratch. I wanted something that didn’t just describe color variations but actually described usage and intent.
Here’s what I landed on for Rankat:
--background--foreground--card--card-foreground--popover--popover-foreground--primary--primary-foreground--secondary--secondary-foreground--muted--muted-foreground--accent--accent-foreground--destructive--border--input
At first glance, it might look more complex, but it’s actually the opposite. These names describe purpose, not appearance.
Creating a card? Use --card and --card-foreground. Need text color on a primary button? Use --primary-foreground. Adding a subtle border? Use --border.
No memorization, no ambiguity, just semantic, intention-driven naming.
This approach works because it’s clear, scalable, and accessible.
If I could go back and give my past self one piece of advice, it would be this:
Design your design system like you design your products - for people, not for yourself.
A design system isn’t just a library of components; it’s a living product that other designers and developers use every day. Every naming choice, every color token, every small decision affects how easily others can create, scale, and collaborate.
Of course, I’m not the only one using this naming convention. Variations of it have existed for a while, many great systems and frameworks have arrived at similar ideas. I’m not claiming to have invented anything new here. But I decided to write about it because this particular approach is the one that’s worked best for me, for how I think, design, and collaborate.
Ultimately, design systems aren’t about being “right”, they’re about creating something that helps people do their best work.