Why design system naming feels impossible
The real problem isn't the name itself – it's the mental overhead
"We spend more time naming our design tokens than we do our kids and pets," Dan Mall once quipped. He wasn't joking. I've watched teams spend three-hour meetings debating whether something should be called ButtonPrimary or PrimaryButton or PrimaryActionButton – only to revisit the same conversation six months later because nobody remembers why they chose what they did.
Naming kills design system adoption. Teams obsess over component APIs and documentation while overlooking the cognitive load from inconsistent, unclear names. Every confusing label creates friction. Every inconsistent pattern erodes trust. Friction scales linearly; mistrust scales exponentially.
And naming debt? It compounds invisibly until it cripples everything.
Why naming is harder than it looks
Here's the uncomfortable truth: naming isn't a design problem or a development problem. It's a human psychology problem disguised as a technical decision.
When a developer encounters card-variant-02 in code, they have to stop. Search documentation. Rebuild their mental model of what that variant actually represents. Designers carry the same burden with InfoBoxAlt in Figma. What makes it "alt"? Alternative to what?
This isn't pedantry. Working memory is limited. Every ambiguous name steals mental cycles you need elsewhere.
The problem gets worse at scale. Small teams work around TempButton2 through Slack and tribal knowledge. But coordinate across a dozen product teams, three time zones, and rotating contractors? Those workarounds collapse. The naming chaos you could previously ignore becomes what blocks adoption.
Five naming traps
Five patterns keep showing up. Not isolated mistakes – system failures that undermine everything.
The premature precision trap
Teams name components before understanding scope. You call something BillingModule in the first design session. Everyone immediately assumes they know what it does. Nobody tests these assumptions.
Six months later, billing needs to handle subscriptions, one-time payments, invoices. The name says "billing" but the component has become payment orchestration. Mismatch creates confusion. Changing it means updating references everywhere.
The better approach? Use placeholder names during early development, until you understand true scope. Then – only then – pick the right name.
The visual description trap
Naming components based on how they look rather than what they do creates brittleness that reveals itself during the first redesign.
BlueButton works perfectly until your rebrand changes the primary colour to green. Do you rename it to GreenButton and update every reference? Or do you keep the name BlueButton even though it's now green, creating permanent confusion for every new team member?
The same applies to structural names. ThreeColumnLayout becomes a liability when responsive design requires it to be two columns on tablets and one on mobile. ArrowToggle makes no sense when your accessibility audit requires you to replace the arrow icon with a plus/minus indicator.
Function-based naming survives these changes. PrimaryButton remains accurate regardless of colour. ExpandableSection describes behaviour that persists through visual redesigns. This isn't about being pedantic – it's about building names that won't betray you the moment design trends shift.
The abbreviation trap
Teams abbreviate to save characters, but they're actually creating exclusive knowledge silos. S12, G03v1, and nav-prim-dk-mob might make perfect sense to the team that created them, but they create a brutal onboarding experience for everyone else.
The team using these codes was incredibly efficient – once you learned the system. They could reference components in meetings with cryptic shorthand everyone understood. But this created a barrier for newcomers. New team members spent weeks learning the codification before they could contribute effectively. External collaborators struggled to keep up.
Yes, primary-button-large-destructive-hover is verbose. But PrimaryButtonLargeDestructiveHover or even ButtonPrimaryLgDestructiveHover maintains clarity while managing length. The few extra characters are a small price to pay for immediate comprehension.
The drift trap
When names calcify but components evolve
Component names start clear, then accumulate responsibilities until the name becomes a lie. At one client, we shipped a Notification that secretly handled 13 behaviours. New hires treated it like a banner. Engineering treated it like an alert. Support thought it was a toast. We weren't misaligned – we were misnamed.
When does Notification become Alert? Or Message? Or StatusIndicator?
The original creators understand the evolution because they lived it. Anyone new sees a simple name and expects simple functionality. Then they discover 14 modes. The name stopped being accurate months ago, but nobody caught the moment it happened.
Pattern: names calcify while components evolve. Eventually the mismatch gets so bad that teams either ignore the system or waste hours trying to retrofit meaning onto misleading labels.
Fix? Quarterly naming audits. When a component outgrows its name, that's not a documentation problem. It's a signal to refactor or rename. Leave the mismatch and you teach teams that names don't matter. That quietly kills system credibility.
Building a naming framework
Good naming isn't about perfect labels. It's about systematic approach that reduces cognitive load and survives org changes.
Start with the naming taxonomy
Nathan Curtis's framework provides the foundation most teams need: namespace, object, base, and modifier. This structure scales from simple tokens to complex component variants while maintaining consistency.
For a button component, this might look like:
Namespace:
ds(your system identifier)Object:
button(what it is)Base:
primary(its category or function)Modifier:
large(size, state, or variant)
Result: ds-button-primary-large
The beauty of this structure is its flexibility. Not every name needs all four levels. A simple colour token might only need namespace and base: ds-color-primary. But when you need to be specific, the framework provides a clear path: ds-button-primary-large-disabled.
Prioritise function over form
Every naming decision should answer "what does this do?" before "what does this look like?" This principle keeps names resilient through redesigns and rebrandings.
Compare these approaches:
Visual:
RedButton,ThreeColumnGrid,ArrowDropdownFunctional:
ButtonDestructive,LayoutWithSidebar,MenuExpandable
The functional names survive when red becomes purple, three columns become responsive, and arrows become chevrons. They describe purpose, which remains stable even when presentation evolves.
For design tokens specifically, avoid the colour name trap. Don't use color-blue-500 when you mean color-primary. Don't use spacing-24 when you mean spacing-large. The semantic layer provides abstraction that lets you change values without changing names.
Use the "three times" rule
Dan Mall's guidance here is invaluable: if one team needs a component, wait. If two teams need it, note the pattern. If three teams need it, add it to the system.
This same principle applies to naming. Don't establish a naming convention based on a single use case. Wait until you have three similar scenarios, then extract the pattern that works for all of them. This prevents premature abstraction and ensures your naming system reflects actual usage patterns rather than theoretical completeness.
Make it pronounceable and scannable
Names exist to be read and spoken. If your team can't discuss a component in a meeting without checking documentation, the name has failed.
Test this literally. Take a component name and say it out loud. ButtonPrimaryLarge is clear and pronounceable. btn-prim-lg sounds like alphabet soup and requires mental translation. If you can't comfortably say the name in conversation, you've optimised for the wrong thing.
Similarly, names should be scannable at a glance. PascalCase generally works better than kebab-case for visual scanning of component names, though coding conventions may dictate otherwise for CSS classes or HTML attributes. Aim for instant recognition without conscious decoding.
Document the "why" behind naming decisions
Names carry context that isn't always obvious. When you choose Notification over Alert or Toast, document why. When you decide on PrimaryButton instead of ButtonPrimary, explain the reasoning.
This documentation serves two purposes. First, it prevents the same debates from recurring every six months when someone questions the convention. Second, it helps new team members understand the system faster because they can see the reasoning, not just the rules.
The documentation doesn't need to be exhaustive. Often a simple decision log or naming rationale document is enough: "We use function-first naming (ButtonPrimary not PrimaryButton) to group related components alphabetically in most tools. We use PascalCase for components and kebab-case for tokens to match React and CSS conventions respectively".
The cost of getting it wrong
Poor naming isn't just aesthetic or documentation issue. It's measurable drag across your organisation.
In retrospectives and audits, inconsistent naming shows up as root cause of rework and delays. Developers can't identify the right component? Time searching or duplicate builds. Designers can't understand variants? Wrong guesses or unnecessary new patterns.
Efficiency loss compounds with team size. Five people work around bad names through constant communication. Fifty people across distributed teams? Can't compensate. Cognitive overhead multiplies across everyone touching the system.
Worse? Trust erosion. Teams encounter misleading names, discover exceptions and edge cases in conventions. They learn the system isn't reliable. Kills adoption faster than missing features or incomplete docs. People forgive technical debt in systems they trust. They won't touch systems they don't, regardless of completeness.
Making naming sustainable
The goal isn't perfect names from day one – it's a naming system that evolves without chaos.
Run quarterly audits. Review most-used components. Ask: Does this name still describe what this does? Added functionality that violates original meaning? Do new people get confused? Find a problem name? Fix it. Yes, coordination required. Yes, short-term disruption. But permanent confusion growing with every hire is worse.
Create glossary explaining convention logic. Include correct usage examples, common mistakes, reasoning behind controversial decisions. Most important: involve whole team. Naming isn't handed down from design system team. Requires input from everyone using it.
Systems that scale don't rely on clever names. They treat naming as continuous practice, not one-time decision.
This connects to everything else about design systems. Bad names accelerate system entropy – inconsistencies compound faster when nobody can tell components apart. It breaks machine readability too – AI agents as users need semantic clarity more than humans. Agents can't infer InfoBoxAlt. Semantic names are machine fuel.
Naming is infrastructure work. Like any infrastructure, it either supports what you build on top of it, or it becomes the reason things collapse.
Here's your next step: run a naming audit this quarter.
Pick the top 10 used components
Ask 5 people (design, eng, PM, support, contractor) what each does – no screenshots
Flag any hesitation in <10 seconds → rename or refactor
Log rationale in a single doc
Re-run in 90 days
Every confusing name is friction. Every clear name is velocity. Start there.
Thanks for reading! This article is also available on Medium, where I share more posts like this. If you're active there, feel free to follow me for updates.
I'd love to stay connected – join the conversation on X, Bluesky, or connect with me on LinkedIn to talk design, digital products, and everything in between.