Naming components, colors, and tokens correctly avoids rework and speeds up onboarding

Why no one agrees on what to call a button

Anyone who has sat through a design system meeting knows the scene: the debate over whether to call a component Button, Btn, or ActionTrigger eats up more time than it should. It's not gratuitous bikeshedding. A guide published this month by Smashing Magazine, written by Vitaly Friedman, brings together practical references for naming UI components, colors, design tokens, and features, starting from a simple diagnosis: the language a team uses shapes how it thinks about the product.

One of the central points of the material, and the one that matters most to developers, is that an overly generic name hides intent (it becomes hard to understand exactly what something is), while an overly specific name blocks reuse, leaving little flexibility. Between these two extremes lies much of the technical debt that shows up years later, when no one remembers why a class, variable, or component was named that way.

Where to look for component and class names

For those who run out of options when naming a function, an HTML class, or a CSS property, the guide points to Classnames, a catalog of words grouped by theme (behavior, similarity, order, grouping), including fields that don't normally come to a developer's mind, such as architecture, fashion, and editorial publishing. It's a list, not a convention: the value lies in pulling the developer away from the obvious vocabulary (item, box, wrapper) before it becomes a prefix across half the codebase.

To name things consistently across layers (layer, group, component), the reference is Javier Cuello's material on naming best practices in design files. The criteria he lists apply both to those designing in Figma and to those organizing components in code:

• Logical, predictable structure, without case-by-case variation
• A short name, but one that doesn't force the reader to guess what it describes
• Vocabulary shared across the whole team, not just by whoever created it
• Independence from visual properties (the name doesn't describe color, size, or position)

This last point is what causes the most rework in production: naming something blue-button works until the day the button changes color in a redesign, and no one wants to go hunting down every occurrence of the class in the repository.

Color has a name, and there are 30,000 of them

For colors specifically, the guide cites the repository maintained by David Aerne, which brings together 30,355 unique color names drawn from various references and thousands of user contributions. The associated tool, Color Parrot, returns a readable name for any hexadecimal value typed into the URL. It doesn't replace a semantic token (color-brand-primary), but it helps give a memorable label to a palette before it becomes a system variable, which makes communication between design and code easier when documenting the reasoning behind each choice.

Design tokens: from theory to real-world cases at Intuit and Vodafone

The densest part of the material, and the one that matters most to those dealing with front-end architecture at scale, is the section on design token taxonomy. Intuit, which owns products like Mailchimp, QuickBooks, and TurboTax, needed a token system flexible enough to serve different brands without rewriting the base for every new product. Nate Baldwin documented the process in a case study that details the problems with the old taxonomy, the criteria set for the new one, and how it was built, with the trade-offs explained at each decision.

Vodafone UK's design system team took a complementary path, building on Nathan Curtis's work on token naming. The result, called the Variables Taxonomy Map, organizes tokens into four interconnected layers (brand, primitives, semantics, and pages), allowing anyone on the team to understand where a token is used and what it represents just from its name.

The practical advantage of this layered separation shows up when the product needs a rebrand: the value changes in the brand layer, without needing to touch the layers the code actually consumes. It's the same reasoning behind any well-built design token system (Style Dictionary, Tokens Studio, and the like): separating what changes frequently from what changes rarely.

For those who want to build this structure from scratch without copying another company's system, the guide also recommends two open tools: the Design Token Naming Guide + Builder, by Romina Kavcic, which helps configure categories, states, and roles before settling on a convention; and a four-level inventory spreadsheet for mapping all existing tokens without losing control as the number of themes and modes grows.

A badly named feature is a feature nobody uses

A point that goes beyond CSS and token architecture, but directly affects whoever decides the text of a release note or the label of a feature flag, is the section on naming new features. Erin Gannon argues that low adoption of a feature is often, in part, a naming problem: before it can be used, a feature needs to be discovered, understood, and only then tested and incorporated into the workflow of whoever uses the product.

The practical recommendation is testable by any team: ask a user to explain the feature in their own words, and use those words in the name, not the technical term that was born in the planning meeting. This has a direct implication for code too, because the name that appears in the interface rarely matches the flag's internal name (feature_flag_v2_beta), and keeping both recorded somewhere documented avoids the archaeology dig three months later, when someone asks what that flag actually controls.

What a wrong name breaks (and what that has to do with accessibility)

The Smashing Magazine material doesn't address accessibility directly, but the connection is direct for those working with semantic HTML and ARIA. A component named inconsistently in the design system tends to have an inconsistent aria-label in implementation: if Figma calls it a "product card" and the code calls it "item-tile", it's common for the alternative text read by a screen reader to also vary between screens in the same flow, confusing those who depend on assistive technology to navigate.

In short: consistent naming between design and code isn't about aesthetics, it's the contract that guarantees the label a person with visual impairment hears is the same throughout the journey, because it comes from the same semantic token instead of being rewritten on each screen by whoever implemented it.

When it's not worth formalizing everything

Not every project needs a four-layer Variables Taxonomy Map. For a small team or an early-stage product, the cost of maintaining this structure can outweigh the benefit, and it's worth investing instead in a simple glossary, a Notion page, or a design system README listing the agreed-upon terms.

The risk of skipping this step, for a team of any size, is the same one the guide describes: people talking about the same thing in different dialects (design's, developers', product's), until the confusion turns into a naming conflict within the repository itself, and only then does it become a backlog item that no one prioritizes.

The complete guide, with the list of resources and direct links to each tool mentioned, is available on Smashing Magazine.