Naming things: the quiet half of a design system

Building the components is the part that feels like the work. It's visible, it's satisfying, and you can show it in a review. Naming them feels like admin: the thing you do at the end, quickly, so you can ship.

A component nobody can find gets rebuilt. That's a duplication problem with a naming cause.

Then a year passes, a second designer joins, and they build a new button. Not out of carelessness. They searched the library for “button,” found Btn/Primary, Action/Default, CTA/Large and Button/Main, couldn't tell which one was current, and made the decision any reasonable person would make: they built one they understood.

That's the whole failure mode. A design system doesn't die from missing components. It dies from components nobody can find, which produces duplicates, which produces ambiguity about which one is canonical, which produces more duplicates. Naming is the retrieval layer, and retrieval is the entire point of a library.

A few principles I've landed on, mostly by getting them wrong first.

Name by function, never by appearance. Button/Danger survives a rebrand. Button/Red becomes a lie the moment danger states go orange, and worse, a lie that still works, so it stays, quietly wrong, until someone builds a red button that isn't dangerous and the whole category loses meaning. Same for Text/Small versus Text/Caption, or Card/Grey versus Card/Inactive. If the name describes what it looks like, it will eventually describe what it used to look like.

Match the developers' names. If engineering calls it a Chip and design calls it a Tag, every handoff conversation carries a translation step, and translation steps are where things get lost. The specific names matter far less than the fact that both sides use the same ones. This is worth an actual meeting: an hour spent agreeing on a shared vocabulary saves more downstream time than almost any other hour in a system project.

Put the noun first. Button/Primary/Large sorts and filters sensibly. Large/Primary/Button scatters your buttons across the alphabet. Figma's search is prefix-weighted and so is human memory: people recall the thing before they recall its qualifier. Nobody thinks “I need a large one, of a button.”

Be boring on purpose. Clever internal names (a spacing scale named after planets, a type ramp named after musical intervals) feel like culture when the team is three people who were all in the room. They feel like a private joke to the person who joins in month fourteen and has to learn a mapping before they can use a token. Every clever name is a small tax on every future person.

Version by deprecation, not deletion. When a component is genuinely replaced, renaming the old one to Deprecated/Button and leaving it in place for a cycle does two things: it stops existing files breaking, and it tells anyone who finds it what happened. Deleting it means someone eventually rebuilds it, having never learned it existed.

The test I use is the newcomer test. Give someone who has never seen the library a task (build a confirmation dialog) and watch what they search for. The words they type first are what the components should be called. Not the words that are technically precise, not the words that match the internal architecture. The words a competent person reaches for when they haven't been trained.

Most naming debates are taxonomy debates in disguise. If two people can't agree whether something is a Card or a Panel, the useful question usually isn't which word wins. It's whether these are one component or two. The naming argument is doing you a favour by surfacing a structural question early, while it's still cheap.

Components are how a design system does its job. Names are how anyone finds out it has one.