Naming things in a design system people actually use

The hardest part of a design system isn’t drawing the button. It’s agreeing what to call it. After two years of naming debates, these are the rules that stuck.

Name by job, not by look

“Blue Button” breaks the day the brand changes colour. “Primary Button” survives a rebrand. The same goes for colours: Text Muted outlives Grey 500 in every file it touches.

Use the words your engineers use

If the code says Dialog, don’t call it Modal in the design file. Every mismatch is a translation step at handoff, and translation is where bugs sneak in.

Keep variants boring and predictable

Pick one order and stick to it: type, then size, then state. Primary / Large / Disabled is easy to find in a search. Big disabled main button isn’t.

Fewer components, more options

Before adding a new component, ask whether it’s really an existing one with one more setting. Ten button components are harder to keep in sync than one button with clear options.

Leave notes where people look

A one-line description on the component itself, like “Use for the single most important action on a screen”, does more than a forty-page guideline nobody opens.