Why your design system's naming convention will make or break adoption

Naming is where most design system documentation fails and almost nobody says so out loud.

You can have solid token architecture and strong component coverage and still ship a system that feels foreign to the people using it, because the names don't map to how they think about the interface.

Why names matter more than they appear to

A name does two things: it identifies something, and it implies something about what that something is for.

When you name a component "ContentCard," you're telling users this is a card for displaying content. When you name it "Card," you're telling them it's a container. When you name it "PrimaryCard," you're implying hierarchy, which will confuse them when they need a secondary variant and find out there isn't one.

Bad names require active recall. A developer using your system has to remember what your component does rather than understand it from the name. That overhead adds up, and the developers who run into it most are the ones using the system least frequently. Exactly the people you most need to serve.

The naming failure modes

Appearance-based names don't survive design changes. A component named "BlueButton" creates problems the first time the button isn't blue. A component named "OutlineButton" creates problems when the filled variant gets added. Name for purpose, not appearance: "ButtonPrimary," "ButtonSecondary," or just "Button" with a variant prop.

Too abstract and it communicates nothing. "Element," "Module," "Container" are so broad they describe any and all components. The name should be specific enough that someone unfamiliar with the system can make a reasonable guess about what it does.

Inconsistent casing across layers produces friction every time someone writes an import. Pick one pattern. PascalCase for components, camelCase for tokens, kebab-case for CSS custom properties. Hold it without exceptions. The exceptions are what people remember, usually wrong.

Naming in token systems

Semantic tokens get this wrong constantly. Tokens named for their value, like color-blue-500 or spacing-16, communicate the value, not the intent. That's fine for primitive tokens. For semantic tokens that map to specific uses in the interface, the name should tell you where to use it: color-text-primary, spacing-component-gap-md.

The test for a semantic token name: can someone read it and know roughly where it applies in the UI without looking up the definition? If not, the name is working against you.

Getting to agreement

Naming is where teams spend time they didn't intend to spend. Everyone has an opinion, the opinions conflict, and the conversation drags.

Get consensus on naming principles before naming individual things. If the team agrees that components are named for purpose not appearance, the name of any specific component becomes a smaller argument. Principles are more durable than specific choices, and they let you resolve future naming questions without a committee meeting every time.

The names you choose will outlast the person who chose them. Name for the team that inherits the system, not the one building it.