The Taxonomy of Clarity: A Comprehensive Guide to Naming in Design and Development

Naming is arguably the most difficult task in software engineering and interface design. It is the bridge between abstract intent and concrete reality. Whether you are defining a CSS class, a JavaScript variable, a design token, or a user-facing feature, the words you choose shape not only the code you write but the very conversation your team has about your product.

Inconsistent naming leads to "dialect silos," where designers, developers, and product managers speak different languages despite working on the same project. This article explores the art and science of naming, providing a roadmap to building a robust, scalable taxonomy that minimizes confusion and maximizes clarity.

The Core Philosophy: Why Naming Matters

Language shapes thought. When a naming convention is too generic, it becomes an enigma that requires constant documentation. When it is too specific, it becomes brittle, resisting reuse and forcing developers to create redundant components. The goal is to find the "Goldilocks zone"—a naming structure that is meaningful, predictable, and flexible.

Effective naming reduces the cognitive load on your team. It allows a new developer to understand a codebase by merely reading the labels. It allows a designer to hand off a file without needing to explain every layer group. When we prioritize naming, we are essentially investing in the long-term maintainability of our digital architecture.

Chronology of Best Practices: Evolving Your System

The evolution of a design system usually follows a predictable path:

1. The Wild West: Everyone names components based on personal preference or immediate need.
2. The Realization: Discrepancies between documentation, code, and design files cause bottlenecks.
3. The Standardization: Teams adopt naming conventions (e.g., BEM, OOCSS).
4. The Maturity: A formal taxonomy is established, often driven by design tokens that connect design intent to technical implementation.

To guide this journey, several resources have emerged as industry standards. Classnames is a primary starting point for those stuck in a creative rut. It provides thematically grouped lists of words that help engineers think outside the box—drawing inspiration from nature, architecture, and music to name functions and classes that are more descriptive than standard technical jargon.

Supporting Data: Strategies for Every Element

1. The Color Spectrum

Naming colors is notoriously subjective. Should a variable be named blue-500 or action-primary? David Aerne’s Color Parrot repository offers a data-driven approach, housing over 30,000 unique color names. By leveraging such a repository, teams can move away from arbitrary naming and toward a standardized vocabulary that ensures every shade of "blue" is identified consistently across platforms.

2. Layers and Groups

Javier Cuello, a prominent voice in design systems, has synthesized best practices for naming layers and groups. The consensus is clear: avoid visual properties. Naming a layer "Bold-Red-Text" is a trap; if you change the design, the name becomes a lie. Instead, focus on the purpose or role of the component. A good name is:

• Logical: It follows a hierarchy (e.g., component/element/state).
• Meaningful: It describes what the item does, not how it looks.
• Universal: It is understood by both the design team and the engineering team.

3. Design Tokens: The Backbone of Multi-Brand Systems

As organizations scale, they often need to support multiple brands or themes. The challenge at companies like Intuit—which manages disparate products like Mailchimp and QuickBooks—is creating a token system that is flexible enough to accommodate different visual identities while maintaining a unified core.

Nate Baldwin’s research on Intuit’s token taxonomy highlights the shift from "hard-coded" values to a layered system:

• Global Tokens: Base values (e.g., color-blue-500).
• Alias Tokens: Semantic roles (e.g., action-color-background).
• Component Tokens: Implementation-specific values (e.g., button-primary-background).

This "map" ensures that if a brand color changes, the update cascades through the system without breaking individual component logic.

Industry Perspectives and Expert Responses

The professional community has responded to the "naming crisis" by building collaborative tools. The Component Gallery, curated by Iain Bean, acts as a living dictionary for UI components. By aggregating names from top-tier design systems, it allows teams to see how industry leaders label elements like accordions, modals, or tooltips.

Furthermore, the Vodafone UK Design System team has provided a template for complex organizations. Their Variables Taxonomy Map serves as an industry-leading example of how to document a multi-brand system. By breaking down tokens into categories—from primitives to page-level implementation—they have created a system that allows for "discovery through naming." If a developer knows the context, they can guess the name of the token, which is the hallmark of a truly intuitive system.

Implications for Product Adoption

A critical, yet often overlooked, aspect of naming is the relationship between nomenclature and feature adoption. Erin Gannon’s research into feature naming emphasizes that users do not see "features"; they see "outcomes."

When a feature has a technical or abstract name, it suffers from poor discoverability. If a user cannot understand what a feature does by its name, they will not invest the time to learn how to use it. The implication is simple: use the user’s language. Conduct user interviews, listen to the words they use to describe their problems, and reflect that language in your product labels.

Poor naming is a "silent killer" of product engagement. If your analytics show low adoption for a new tool, it is often not a failure of the design or the engineering—it is a failure of communication.

Building Your Own Taxonomy: A Tactical Checklist

To implement these findings in your own organization, follow this step-by-step approach:

1. Audit Existing Names: Identify the top 20 most confusing components or tokens.
2. Establish a Shared Vocabulary: Use resources like the Design Token Naming Guide by Romina Kavcic to build a structure that includes categories, states, and roles.
3. Create a "Source of Truth": Use a spreadsheet or a dedicated design token management tool (like those linked in the Figma resources) to track your taxonomy.
4. Review and Iterate: Naming is not a "set it and forget it" task. Schedule quarterly reviews to prune unused names and address naming conflicts before they become technical debt.
5. Standardize via Documentation: Ensure your naming conventions are not just in the code, but in a shared space (Notion, zeroheight, or Confluence) accessible to all cross-functional partners.

Final Thoughts: The Human Element

At the heart of the web are the people who build it. The frustration of working with poorly named code or inconsistent design files is universal. However, the solutions provided by the open-source community demonstrate that we are moving toward a more collaborative and communicative era of development.

Whether you are a solo developer or part of a global enterprise team, the time invested in naming is never wasted. It is an act of empathy for your future self and for the teammates who will interact with your work. By choosing names that are clear, functional, and consistent, you are not just labeling components—you are creating a more accessible, usable, and efficient web for everyone.

Editor’s Note: We encourage you to explore the resources mentioned above. A special thanks to the contributors—like David Aerne, Javier Cuello, Nate Baldwin, and Romina Kavcic—whose work makes our digital ecosystems more organized and approachable. The web thrives on this spirit of shared knowledge, and we are proud to help amplify these efforts. If your team is interested in diving deeper into these topics, consider joining one of our upcoming online workshops to sharpen your design system expertise.