Why Naming Is the Hardest Problem in Software

There's a famous joke: the two hardest problems in computer science are cache invalidation, naming things, and off-by-one errors. But naming isn't just a joke — it's a daily friction point that silently drains team productivity.

When your designer calls it a "card," your PM calls it a "tile," and your codebase calls it a BoxContainer, you've already lost. The language we use shapes how we think about the system, and inconsistent naming creates dialect fragmentation across roles.

This guide breaks down proven approaches for naming the things developers actually name every day: design tokens, UI components, CSS classes, features, and variables. Each section points to a concrete, battle-tested resource you can bookmark and use immediately.

TL;DR: Good names are short, logical, meaningful, known by everyone, and not tied to visual properties. Bad names are either too generic (container) or too specific (blueButtonLarge).

Let's dig into the practical playbook.

Designer sketching UI component naming taxonomy on whiteboard with sticky notes

Naming Design Tokens: Learn from Intuit's Taxonomy

Design tokens are where naming chaos hits hardest — because they cross the designer-developer boundary. Intuit (the company behind Mailchimp, QuickBooks, and TurboTax) built a flexible token taxonomy that scales across multiple brands and products.

The Core Principle: Separate Concerns by Layer

A robust token system typically has four layers:

Primitives  →  Semantics  →  Components  →  Pages
(raw values)   (intent)      (context)      (usage)
  • Primitives: blue-500, space-4, radius-md — raw, brand-agnostic values
  • Semantics: color-action-primary, space-inline-sm — intent-based
  • Components: button-bg-hover, card-padding — component-scoped
  • Pages: checkout-header-bg — page-specific overrides (use sparingly)

Vodafone UK's Variables Taxonomy Map

Vodafone UK's design system team published a Variables Taxonomy Map that visualizes how tokens connect across these four collections. The key insight: from a token's name alone, any developer should be able to infer where it's used and what it represents.

brand.color.primary
  └── primitives.color.blue.500
        └── semantics.color.action.primary
              └── components.button.background

If you can read that chain and immediately understand the intent, your taxonomy is working.

Tooling: Design Token Naming Guide

Romina Kavcic built a naming guide + inventory tool that walks you through configuring your own naming structure with components, categories, states, and roles. The companion spreadsheet gives you a bird's-eye view of every token, filterable by theme and mode.

Pro tip: Before inventing your own taxonomy, check Nathan Curtis's foundational work on design token naming — most modern systems build on it.

Developer writing CSS class names and design token variables in code editor Algorithm Concept Visual

Naming UI Components, Colors, and Features

UI Components: Cross-Reference Before You Decide

Struggling to name a component? Don't invent — compare. Iain Bean's Component Gallery catalogs 50+ UI components (from accordion to visually-hidden) and lists the alternative names each goes by across major design systems.

This solves the classic problem: is it a Toast, Snackbar, Notification, or Alert? The gallery tells you what Material, Carbon, Polaris, and others call it — so you can pick the most widely understood term.

For behavior-specific naming, namethatui.com is a visual dictionary of common UI patterns.

Colors: 30,000+ Named Colors at Your Fingertips

David Aerne maintains a repository of 30,355 unique color names — sourced from references and thousands of community contributions. It ships with a color picker and name search. When #FF6B6B needs a human name, this is where you look.

Features: Name from the User's Mouth, Not the Roadmap

Feature adoption fails when discoverability fails. Erin Gannon's practical guide makes one point crystal clear: good feature names tap into the user's own language, not internal jargon.

The technique:

  1. Ask 5 users to explain the feature in their own words
  2. Extract the recurring nouns and verbs
  3. Use those words as the feature name

Warning: Don't name features after internal team names, sprint codenames, or engineering abstractions. Users don't care that it's called "Project Falcon" internally.

Layers and Groups: Consistency Over Creativity

Javier Cuello's naming best practices for Figma layers and groups boil down to five rules:

RuleGoodBad
Logical structurecard/header/titleTitle copy 2 final
Shortbtn-primaryprimary-button-large-blue
Meaningfulnav-itemgroup-12
Known by everyoneavatarprofile-circle-img
Not visualalert-errorred-box

Variables: The Naming Cheatsheet

For code-level variables, the naming-cheatsheet on GitHub is the de facto reference. Its core formula:

[action][context][target]

Examples:

  • getUserProfile (action: get, context: User, target: Profile)
  • isEmailValid (boolean prefix + subject)
  • handleSubmitClick (event handler pattern)

Anti-pattern: data, info, temp, value, obj — these are not names, they're placeholders pretending to be names.

Team collaborating on feature naming strategy with user feedback sticky notes

The Bottom Line: Names Are a Team Contract

The right name is the one that's well-understood and used by the team and users. Everything else is noise.

When adoption is low, before you blame the feature, the onboarding, or the docs — check the name. A confusing name is a tax paid on every conversation, every code review, and every support ticket.

Quick Reference: Bookmark These

What to Do Next

  1. Audit your current names. Run a quick grep for data, temp, box, container in your codebase. Each hit is a future confusion point.
  2. Pick one taxonomy layer (e.g., design tokens) and standardize it this sprint. Don't boil the ocean.
  3. Add naming conflicts to your backlog — don't fix everything at once, but don't forget them either.

For a deeper dive into how naming shapes system architecture, see our analysis of building a pronunciation-aware clinical ASR flywheel with AI agent skills — where consistent naming across AI pipelines made the difference between a maintainable system and a debugging nightmare. And if you're tracking how infrastructure naming scales in AI-era data centers, our breakdown of Azure's NVIDIA Rubin platform integration shows why naming conventions matter at every layer of the stack.

Source: This guide draws on the Smashing Magazine article How To Name Things, reorganized for developer-focused practical use.

Naming is a team sport. The best time to fix it was at project start. The second best time is now.

This content was drafted using AI tools based on reliable sources, and has been reviewed by our editorial team before publication. It is not intended to replace professional advice.