How to name components in a Figma design system without breaking your library

A new component lands in your Figma library on a Tuesday morning. By Friday, the same idea exists under three different names: Button/Primary, Btn/Default, and Primary Button 01. Designers cannot find it. Engineers cannot map it to code without a translator. The product manager asks why a single button now lives in four places. Naming sounds like a small decision, but it is the spine of any design system that has to survive contact with real work.

This guide walks through how to name components in a Figma design system so your library stays searchable, predictable, and useful months after the first commit. It focuses on the practical mechanics: structure, separators, variants, properties, and the small habits that prevent drift.

How to name components in a Figma design system

Strong component names follow a simple structure: category, item, variant, state, property. That ordering mirrors how a designer thinks when searching a library. You start broad, narrow to a specific component, then describe how it differs from its siblings. A name like Forms / Input / Default / Focus is easier to scan than Focus Default Input Form, because the left side answers “what kind of thing is this” before the right side answers “which version am I looking at.”

The exact words you use matter less than the discipline of using the same words every time. Pick a vocabulary, write it down, and treat the document like a contract. The remainder of this article turns that contract into something you can actually ship.

Why naming is the first real decision in a design system

Most design systems do not collapse under bad components. They collapse under inconsistent names. The same idea gets a different label in every file, and the library stops behaving like a library. Search becomes guesswork, and guesswork produces duplicate components.

There are three concrete problems that show up when naming is loose:

• Search noise. Designers type “button” and get forty results because half the team uses “button,” the other half uses “btn,” and a third group added “CTA.”
• Variant confusion. Two components that should be the same read as different items because one is Primary and the other is Main.
• Engineering handoff drift. Developers cannot map a fuzzy Figma name to a single React prop without a meeting, which defeats the point of having a system.

Naming is also the cheapest place to fix these problems. Changing a component’s visual treatment can break layouts and force rework. Renaming a component is a search-and-replace task, as long as you do it before the library has been cloned into fifty files.

The anatomy of a Figma component name

A useful Figma component name is built from a small number of predictable parts. You do not need all of them for every component, but you should know which part is which so you can decide what to include.

Part	Purpose	Example
Category	The collection the component belongs to. Often a feature area or element family.	Forms, Navigation, Feedback
Item	The specific component itself. Singular noun, no adjectives.	Input, Button, Modal
Variant	The role or visual weight. Used when one component has several distinct versions.	Primary, Secondary, Danger
State	The interaction state. Often a Figma property value.	Default, Hover, Focus, Disabled
Property	Size, density, or another controlled attribute exposed to consumers.	Small, Medium, Large

Read the name from left to right, and each segment answers one question. That rhythm is what makes a library scannable instead of searchable by memory.

Picking a separator: slash, dash, or dot

Figma treats slashes, dashes, and dots as part of a component name. They also create visual layers in the Assets panel. That is a feature, not a detail, because layers help designers scan. The question is which separator communicates the structure you want.

Separator	Best for	Watch out for
Slash /	Hierarchical grouping. Figma turns each segment into a folder-like view in the Assets panel.	Deep hierarchies get noisy. Avoid more than three levels.
Dash -	Inline variant or property values inside a single name.	Less clear as a hierarchy cue. Pair with slashes for structure.
Dot .	Code-style separation, often used for token naming.	Some teams find it visually busy in long names.

A common pattern is to use slashes for the category and item, and to let Figma’s own variant properties handle state, size, and role. That keeps the parent component name short and pushes the rest of the information into structured fields, which is easier to scan and easier to map to code.

Use singular nouns for items, plural for categories

Categories are collections, so plural nouns feel natural: Buttons, Inputs, Cards. Individual components inside those collections should be singular: Button, Input, Card. This small rule makes the hierarchy read the way English readers expect it to, and it prevents the awkwardness of “Buttons / Buttons” when you nest a variant.

Stick to one word per segment whenever you can. Navigation / Bar is easier to scan than Navigation / Top Bar, and it forces you to decide whether “top” is a real variant or just the current default. To place this section in context, the Figma overview offers a concise background reference.

Where variant properties take over from naming

Once a component has more than two or three meaningful differences, hardcoding them into the name becomes a liability. Figma variant properties are the right tool for any attribute that behaves like a switch, not a different component.

• Use a variant property for: size, state, color role, density, icon position, and disabled on or off.
• Keep these in the component name: the category, the item, and any true structural difference (for example, a Button versus an Icon Button are different items, not variants).

When you expose a property, name it with a question the designer actually asks. Size with values Small, Medium, Large beats a property called Type that secretly means size. Property names are part of your system’s vocabulary too.

A naming pattern that holds up at scale

Below is a starter pattern you can adapt. It is deliberately conservative, because conservative patterns survive when new people join the team and want to bend the rules.

Component	Parent name	Variant property	Values
Primary button	Button	Variant, Size, State	Primary, Secondary, Ghost / Small, Medium, Large / Default, Hover, Disabled
Text input	Input / Text	State, Size	Default, Focus, Error, Disabled / Small, Medium
Card	Card	Elevation, Media	Flat, Raised / None, Image, Video
Modal	Modal	Size	Small, Medium, Full
Tag	Tag	Tone	Neutral, Success, Warning, Danger

Notice that the parent name rarely mentions color, size, or state. Those live in properties. The parent name answers only one question: what is this thing.

Decide what counts as a new component

Half the work of naming is deciding what is a variant and what is a new component. A common trap is to treat every visual change as a reason to create a sibling. That bloats the library and makes the system harder to learn.

Use this checklist before you add a new component to the library:

1. Does it have a different name in conversation? If your team already calls it something different in design reviews, it is probably a new component, not a variant.
2. Does it have a different structure? A button with an icon is still a button. A button that contains an input is a different component.
3. Does it have a different code mapping? If engineering ships it as a distinct component in code, the Figma name should reflect that.
4. Would you ever use the two side by side? If yes, they probably deserve a shared parent and a variant property.

If the answer to most of these is no, the change belongs inside an existing component as a variant or property, not as a new top-level item.

Write a one-page naming guide and actually use it

A naming system without a written rule is a wish. Keep the rules short enough that a new designer can read them in five minutes, and specific enough that the rules resolve real disagreements.

Useful sections for a naming guide include:

• Structure: the canonical order of category, item, variant, state, and property.
• Separators: which character to use, and where.
• Vocabulary: a short list of approved words for common roles, such as Primary, Secondary, Neutral, Success, Warning, Danger.
• Property naming: rules for variant property labels, including capitalization and allowed values.
• Deprecation: how to retire a name and what to do with old instances.

Link the guide from your design system overview and from your Figma library description so the rules show up where the work happens. If you want a broader foundation before writing your own, it helps to read a working design systems overview for product teams alongside your draft. Readers can also consult the new community profiles let users view for an independent source related to this section.

Common naming mistakes and how to fix them

Most naming problems in Figma libraries fall into a small number of patterns. Recognizing them early is the difference between a system that gets used and one that gets ignored.

Mistake	Why it hurts	What to do instead
Mixed synonyms for the same idea (CTA and Button)	Search returns duplicate concepts and designers cannot tell which to use.	Pick one word and remove the other from the library.
Encoding design choices in the name (Blue Button)	The component can no longer change color without a rename.	Move color to a variant property and keep the name role-based.
Putting state in the parent name (Hover Button)	Every state needs its own component, which is exactly what properties solve.	Make a single Button with a State property.
Long descriptive names (Primary CTA Button with Icon on the Right)	Impossible to scan, and most of the description belongs in properties.	Shorten to Button and expose Variant, Icon, and Icon Position.
Inconsistent capitalization (primary button versus Primary Button)	Two names for the same thing; search treats them as different.	Pick Title Case or sentence case and apply it to every name and property value.

You will not catch every mistake in advance, which is why the next habit matters more than the rules themselves.

Make renaming a normal part of the workflow

Names decay. A component that was named correctly in version one becomes a fossil by version four as the product grows. Treat naming as ongoing maintenance, not a one-time project.

• Review names during library updates. Every time you add a component, spend five minutes checking that its name still follows the current rules.
• Track deprecated names in a short list. When a component is renamed, keep the old name as a hidden label or a description note so existing files still find it.
• Run a naming audit once a quarter. Export a list of component names, group similar items, and flag anything that breaks the pattern.
• Ask engineering to flag mismatches. Developers are usually the first to notice when a Figma name no longer matches a code component.

If your team works on more than one product surface, the same habit protects component reuse across surfaces. A library used by both marketing pages and the app should not quietly fork its naming rules.

Connect component names to the rest of the system

Component names do not live alone. They sit next to design tokens, documentation, and code components. If those neighbors drift, the names stop being useful. A few connections to keep tight:

• Tones and colors. If you use Primary, Secondary, Success, Warning, Danger as variant values, your color tokens should use the same words. Designers and developers stop arguing about whether “info” and “primary” are the same thing.
• Spacing and size scales. If you expose Small, Medium, Large on a component, your spacing tokens should map to the same names so the system tells one coherent story.
• Documentation labels. The label you give a component on your docs site should be the same as the Figma name. Anything else introduces a second vocabulary that nobody asked for.

For a broader view of how naming fits inside the larger product, an overview of what a visual identity includes and how to build one is a useful companion read, especially when the design system is also feeding marketing surfaces.

A short pre-publish checklist for new components

Before you publish a new component to the shared library, run it through this list. It is intentionally short so designers will actually do it.

1. The parent name is two to three segments, singular item, no colors or states.
2. Any visual difference is exposed as a variant property, not baked into the name.
3. Property values use approved vocabulary words, in Title Case.
4. The component has a description with a one-line usage note.
5. At least one existing file already uses the component, to prove the name is searchable.
6. The engineering counterpart either exists or has a tracking ticket.

If any answer is no, the component is not ready, and the name will probably need another pass later.

What to do when the rules have to bend

Sometimes a real component refuses to fit the pattern. A complex data table, a wizard with a custom layout, or a domain-specific element like a medical chart may need a name that breaks the simple rules. That is fine, as long as you do it on purpose.

When you bend a rule, document the reason next to the component, in plain language. “This is a domain-specific composite, not a generic table” is enough. The point is not to avoid exceptions. The point is to make exceptions visible so future designers know the rule still exists.

Closing thought

A good name is the smallest possible investment that pays back every time someone opens the library. You do not need a perfect taxonomy on day one. You need a starting pattern, a one-page guide, and the habit of revisiting the names whenever the system changes. The structure above is a workable default: category, item, and properties, with a written vocabulary and a quarterly audit. Adjust the words to your product, keep the discipline, and the library will stay scannable long after the first commit.

For related reading on how a design system connects to the wider product experience, the studio’s broader guide to how creative teams turn strong ideas into work that ships is a useful follow-up. For a more structural view of inclusive product work, the practical guide to web accessibility and inclusive design pairs well with the naming work, because a predictable library is also a more accessible one for screen reader users who rely on consistent labels.

Frequently asked questions

What is the best way to structure a Figma component name?

Use a left-to-right hierarchy of category, item, and any structural modifier, then expose state, size, and color role as variant properties. A name like Forms / Input with State and Size properties is easier to scan than a long descriptive name that bakes every attribute into the label.

Should I use slashes or dashes in Figma component names?

Use slashes for the hierarchy between category and item, because Figma turns each segment into a visible layer in the Assets panel. Reserve dashes for inline variant values when you need a single-string name. Avoid dots unless your team already uses them for token naming, since they can read as visually busy.

How many segments should a Figma component name have?

Two to three segments is usually enough. Going deeper than three levels makes the Assets panel hard to scan and increases the chance that designers will skip the structure. If you need more separation, push the extra information into a variant property.

Should colors and sizes be in the component name?

No. Colors and sizes change often and should live as variant properties, not in the parent name. Keeping the parent name role-based, such as Button with a Variant property, means the component can change visual treatment without a rename.

What is the difference between a variant and a new component?

A variant is a controlled version of the same component, with differences exposed as properties. A new component is a structurally different thing that your team already calls by a different name and that engineering ships as a separate code component. If the difference is only visual and the usage context is the same, prefer a variant.

How do I keep component names consistent as the team grows?

Write a short naming guide, link it from the library, and run a quarterly audit. Track deprecated names in a hidden list so old files still find what they need, and ask engineering to flag mismatches between Figma names and code components. Consistency comes from review, not from a single launch document.

Can Figma variant property names change without breaking files?

Changing a variant property name can break existing instances if the property key is renamed, so treat property names as part of the system’s vocabulary. If you must rename a property, plan a deprecation window, keep the old property as an alias where possible, and update documentation at the same time.

How do component names connect to design tokens?

Use the same vocabulary for variant values and tokens. If a button has a Primary variant, the color token for that role should also be called Primary. Shared vocabulary means designers and developers stop translating between two systems that should be saying the same thing.

What should I do when a component does not fit the naming pattern?

Allow exceptions, but make them visible. Add a short note to the component’s description explaining why it is a domain-specific case, and keep the pattern intact for everything else. Hidden exceptions are where libraries go to die.

How often should I audit component names?

A quarterly audit is a workable rhythm for most teams. Export the full name list, group similar items, and flag anything that breaks the current rules. Smaller reviews during regular library updates keep the audit short and stop drift from compounding.

Related reading

• Website strategy: how to plan a site that actually performs
• Web accessibility: a practical guide to inclusive design