Naming in code isn't a trivial detail. The words you choose for variables, CSS classes, and design tokens shape how your team thinks about the systems you build — and whether those systems remain manageable over time. A new resource roundup from Smashing Magazine breaks down best practices for naming across the development stack, and these principles affect everyone from solo developers to enterprise teams.
The Core Problem: Too Generic vs. Too Specific
Good names communicate intent without requiring explanation. Bad names fall into two camps. Names that are too vague — "data," "info," "temp" — force anyone reading the code to hunt for context. Names too tightly coupled to visual properties — "blue-button," "left-sidebar" — break the moment you redesign. Both extremes create maintenance headaches.
Javier Cuello summarized a set of naming principles that apply whether you're working in Figma layers or production code: logical structure, brevity, meaning to everyone on the team, and no ties to visual appearance.
Color Naming at Scale
If you've ever stared at a hex code and wondered what "#E8D4B8" was supposed to represent, you're not alone. A color naming repository maintained by David Aerne now holds 30,355 unique color names sourced from diverse references and thousands of user contributions. It's a genuine resource for anyone building design systems where color variables need to be meaningful to both developers and designers.
Design Tokens: The Real Challenge
Large organizations face the hardest naming problems. Intuit — parent company of Mailchimp, QuickBooks, TurboTax, and Mint — had to build a design token taxonomy that works across dozens of products. Their case study shows that the solution isn't a clever naming scheme; it's a system that separates brand-specific values from foundational patterns.
Components and Variables: Learn From Others
When you're stuck on what to call something, seeing what other design systems call it helps. The Component Gallery documents naming conventions for over 50 UI components, from accordions to visually-hidden text. It's a quick way to sanity-check your choices against industry norms.
For those wrestling with variable naming in complex systems, the Vodafone UK Design System's Variables Taxonomy Map demonstrates how to organize tokens across multiple brands and themes. It structures design tokens into four collections — brand, primitives, semantics, and pages — that show exactly where each token applies and what it represents.
Feature Naming: Ask Users, Not Developers
One often-overlooked area is naming new features. Feature adoption suffers when names are internally focused. Erin Gannon's advice: good feature names come from user language, not developer language. Ask clients to describe what they want to accomplish, then use their words. A feature called "Auto-Backup" means more to a small business owner than "Scheduled Cron Job."
Who Should Care
| Role | Why Naming Matters |
|---|---|
| Frontend developers | Consistent naming reduces onboarding time for new team members |
| Designers | Shared vocabulary between design tools and code prevents translation errors |
| Growing teams | Poor names become technical debt that compounds with every hire |
| End users | Feature names shape how customers understand and adopt your product |
Key takeaways
- Name for intent, not appearance — "primary-action" beats "green-button" every time
- Build a token layer if you're re-skinning interfaces for multiple clients
- When stuck on component names, check what established design systems use
- For client-facing features, use the language your customers use, not technical terms
- Variables and CSS classes are part of your documentation — name them like it matters
Frequently asked questions
Why do vague names like "data" cause problems?
They offer no context. Anyone reading the code has to trace backwards to understand what the variable actually contains or represents.
Should CSS class names describe visual properties?
No. Classes tied to appearance break during redesigns. Use semantic names tied to purpose or function instead.
What's a design token?
A design token is a named value — a color, spacing unit, or font size — that serves as a single source of truth across a design system.
How do I name a feature for better adoption?
Observe what your users call the problem they're trying to solve, then use that language in your feature name.
Can I just copy naming conventions from popular frameworks?
Yes, with modifications. Using familiar patterns helps new developers onboard, but adapt them to your project's specific context.
Inspired by reporting from: smashingmagazine.com