The Hidden Cost of Not Naming Things

Let me be blunt: poor naming in CSS is like organizing a library with blank spines. Sure, the books are all there — but when it’s time to find something, good luck. And when someone else inherits the mess? Now it's their problem. Until it’s yours again.

I’ve worked on solo builds, massive design systems, and legacy codebases with 10 authors. One thing is always true: bad names compound. They add friction. They kill momentum. They make smart people feel lost.

What’s Really Making Your CSS Feel Messy

You think it’s the specificity wars. The cascade. The random overrides. But often, the real root of chaos is inconsistent class names.

Let’s take a typical example:

/* spaghetti.css */
.btn-blue { ... }
.primary-button { ... }
.cta { ... }
.button-important { ... }

Technically, they all do the same thing. But semantically? It’s a guessing game. What’s the “real” button class? Which one should you extend or override?

This is how styling turns into detective work — and why updates get risky fast.

Better Naming, Better Flow

Here’s the shift that changed my workflow: I stopped thinking of class names as shortcuts, and started treating them like contracts. They describe behavior, context, or purpose — not just appearance.

/* predictable.css */
.btn { ... }
.btn--primary { ... }
.btn--danger { ... }
.card { ... }
.card--highlight { ... }

This style is inspired by BEM (Block Element Modifier), but I’m not dogmatic about it. The real win is consistency. When I name classes clearly and deliberately, I don’t need to memorize them. I can read them. Guess them. Trust them.

Common Naming Pitfalls (and How to Fix Them)

  • Problem: Mixing roles and styles — .btn-blue vs. .primary-button
  • Fix: Use one consistent pattern — either functional (.btn--primary) or stylistic (.is-blue), but not both
  • Problem: Class names that lie — like .red-alert on a green success message
  • Fix: Separate meaning from styling. Use .alert--success and define colors in CSS, not names
  • Problem: Overloading names — .block, .title, .content (all too vague)
  • Fix: Prefix based on context — .profile__title, .post__content, etc.

Names should answer questions — not create them.

My Personal Rules for Naming CSS Classes

  • Be descriptive, not decorative. Use names like .error-message, not .red-text.
  • Be consistent across the project. Even if your pattern isn’t perfect, sticking to it is better than random mixing.
  • Use modifiers, not new classes, for variations. .card--dark is clearer than .card-darkmode-v2.
  • Don’t abbreviate too much. .btn is fine. .bx-lt-sm is not — unless you’re writing YAML for robots.

In short: name things like you’ll revisit them in six months — on three hours of sleep — with a client on the phone.

What Recruiters and PMs Should Know

If you’re hiring or evaluating a front-end dev, don’t just look at the visuals. Peek into the class names. Well-named CSS is a sign of thoughtful structure. Sloppy naming? That usually means sloppy thinking — and expensive rework later.

Great naming is invisible UX. It’s what helps teammates move faster, clients feel confident, and projects stay clean as they grow.

Want a second set of eyes on a stylesheet or design system? Or thinking about standardizing your class naming across a team? Contact me here and I’ll help you make it stick.