Naming things in your design system, as we all know, is hard. It’s so hard, in fact, that Christianity lists it as the oldest profession on record. It’s true!

I thought it might be nice to share a few quick tips that have helped me over the years.

Semantic First, Industry-Standard Second, Custom Third

My current organization had (and still has) legacy naming, as it’s a very old and very stable tech company. Too many changes can rock the boat, too little and it’s impossible to course correct. Many of our clients want us to ensure that the decisions we make are bulletproof and backed up.

Semantics

The absolute easiest way for us to do this was to use semantic HTML naming instead of any other term out there in the market. We use borrowed authority from the standards bodies of the world and provide accessibility lingo to boot. We looked to HTML tags first, ARIA roles second, and finally CSS classes & psuedo-classes third.

For example, we have headings (H tags) and not headers, Comboboxes (role=’combobox’) and not Autocomplete (because that’s an attribute), and Backdrops (::backdrop) behind our Modal dialogs and not scrims, covers, or masks. All these components have semantic equivalents, so they get semantic names.

Industry-Standard

The next level down are things that are common industry patterns. This would cover something like a floating balloon of information that appears above a button for more context. There are quite a few names for this type of component, but when comparing multiple design systems and JS helper libraries, the name Popover seemed to be predominant. We chose this because we want any common component to be as easily recognizable to newcomers as we can.

Custom Names

Finally, if there is no standard, we rely on custom names. Sometimes my company already had a legacy name for these items, and we kept them. But generally, we try to have the custom name succinctly describe the component itself. For example, there’s a common repeating design pattern with an image, heading, a small bit of descriptive data, and sometimes an action. Some systems call this a list, but semantically a list is very different. Neither made sense. We decided to call it a ‘Summary list’, because it had a small summary within the repeating item itself and a way to take action.

T-Shirt Sizes & Hundreds Places

When dealing with tokens themselves, the T-Shirt naming method mainly has worked best in my opinion. It’s easiest to track, scale, etc. But I think this pattern needs tweaking. Using “font.size.2xl” makes sense when dealing with size, but not with color. This is where most seem to fall back to using a hundreds place like “color.blue.100” or “color.red.900”.

It works, but if it’s paired with the T-Shirt size method it feels disjointed. Devs and designers need to learn two or more types of methods to go up or down the scale.

If I could do our tokens over, I think I may try an approach like “color.blue.2up” or “font.size.2down”. I think this could work for size, weight, speed, color, and so on and create a single system of scale, making a much more learnable system.

Finally, I don’t think it’s valuable to define 10 steps of every color, even if it does look good on design files. I’d suggest setting a max brightness, min brightness, and baseline of a color, and programmatically defining the steps the system requires. Changing colors in all states is as easy as defining the bounds.

Atomic Design & Other Principles

And while a lot of people swear by the naming conventions of this structure or that one, I’ve found the cuter a naming convention gets, the less understandable it gets. We tried playing with this early on using space analogies, and molecules, etc. but it just made everything murky. Everything is a component, some are lower level, and even within those lower level ones, there’s a level lower than that. For us, it doesn’t make sense to keep track of that level of depth.

We do however keep track of patterns (common collections of components with certain configurations, such as common forms), but they themselves aren’t components.

Conclusion

In the end, do what works for your audience. Accessibility and learnability drove many of our decisions, and generally we are pretty happy with the result. Good luck!