esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

Naming: Give Every Design System Part a Clear, Lasting Name

Learn how clear, consistent names help designers and developers find, use, and maintain the parts of a design system.

In short

Naming in a design system means giving every part a clear, consistent name, so designers and developers can find, use and maintain it.

10 min readFree

What you will learn

A design system is a shared set of parts, such as buttons, colors, and text styles. Every part has a name. A name can look like a small detail, but it decides whether a teammate finds the right part in seconds or spends a long time hunting for it. This lesson explains naming as it is used in design systems: how to give components, styles, tokens, layers, and variants names that both designers and developers understand.

By the end, you will be able to explain why names matter, build a simple naming pattern, name things by their purpose rather than their look, and keep names working as the system grows.

Key words

Naming convention
A written set of rules for how every name in the system is built.
Component
A reusable piece of an interface, such as a button or a text box.
Variant
One version of a component, such as a large button or a disabled button.
Style
A saved look, such as a text style or a color style, given a name in the design file.
Token
A named design decision, such as a color or a spacing amount, stored under a name so many places can reuse it.
Primitive token
A raw value with a name that says what it is, such as a blue shade in a palette.
Semantic token
A token named for its job or role, such as the color for an action button.
Component token
A token tied to one specific component, such as the background of a button.
Casing
How letters are capitalized and joined in a name, such as button-primary or ButtonPrimary.
Handoff
The moment a designer passes finished design work to the developer who will build it.

Why do names matter?

A name is the first thing a person reads about a part. When names are clear, a designer can search the file and find the right part. A developer can look at the same name in the design file and know where the matching part lives in code. Good names act as a shared vocabulary.

  • Less confusion

    When designers and developers use the same words for the same part, meetings are shorter and fewer questions go back and forth.

  • Less repeated work

    People often build a new part when they cannot find the old one.

  • Fewer handoff mistakes

    If a Figma property is named Size and the code prop is also Size, with the same values, the developer does not have to guess what the designer meant.

Tip

Ask a teammate who did not build the system to find one part using only the search box. If they struggle, the names need work.

How do you build a naming convention?

A naming convention is the set of rules that decides how every name is built. You do not need a perfect convention on day one. You do need one pattern, used the same way everywhere, and written down.

Choose a consistent structure

A structure is the order of the parts in a name. Start from broad to narrow, so a reader can see the big group first and the detail last.

  • Slash paths for components

    Figma's pages describe slash-separated names as a way to organize components, such as Button/Primary. Figma's guidance says the Assets panel, which is the list where teams pick library parts, mirrors the file's structure.

  • Category, role, then modifier for tokens

    Some teams use a pattern like category, then role, then modifier. The UAL design system follows a simple pattern: primitive names use category and scale, and semantic names use category and role, such as surface-primary.

  • Prefix for your own system

    Nord Design System adds a short prefix to every token name so its names do not clash with names from other systems. Its examples start with n-, which stands for Nord.

Many guides describe a similar idea: a token name has a few parts. One guide lists an optional prefix, a core meaning made of category and property, optional modifiers for intent or variant, and an optional suffix for state or mode. You do not need every part in every name.

Pick casing and separators

Casing decides how capital letters and word joins look. Common styles are kebab case, such as primary-button; camel case, such as primaryButton; Pascal case, such as PrimaryButton; and snake case, such as primary_button. Each has pros and cons. The right one is the one your team reads easily and uses without error.

Choose one style early and apply it to the whole system.

Tip

Pick the casing your developers already use in their own work. Then stop debating it. A consistent style matters more than which style you chose.

Name the purpose, not the look

The most important rule is to name a part for what it does or means, not for how it looks. Compare red-dark with color-text-danger. The first name describes a shade. If the brand changes its red to purple, the name becomes wrong, and it still tells nobody why the color exists. The second name says the text is for danger messages, so it stays true even when the shade changes.

The same idea appears across the guides. One explains that a token name should tell you what the token is for, not what it looks like.

  • Primitives may describe the value

    A raw palette entry can keep a look-based name such as blue-500, because that is exactly what it is.

  • Semantics describe the role

    A semantic name such as action-primary-background says the color's job, so the value behind it can change without a rename.

  • Components describe the place

    A component name such as button-background-default says where the value is used.

A common mistake is a hue name leaking into a role name, such as color-blue-cta. The fix is to split it into a primitive named for the shade, such as blue-60, and a semantic name for the job, such as action-cta.

Worked example: a primary button on a checkout screen

Imagine a checkout screen with a main Place order button. The button is the primary action, it can appear in a large size, and it turns into a disabled state when the form is incomplete. Here is how a team can name it so a developer can map each name straight to code.

  1. 1

    List the parts of the button

    Write down what varies. Here the parts are the type (primary), the size (large), and the state (disabled). Nord also keeps size names short, such as s, m, l, and xl, and treats m as the default.

  2. 2

    Name the component in the design file

    Use the name Button as the layer's name, with the variation kept in properties. Each slash creates one level in the Assets panel, so a designer sees Button, then Primary, then Large, then Disabled.

  3. 3

    Keep variation in properties

    Be careful here. If the team combines these layers into one component set in Figma, Figma reads the text before the first slash as the set's name and the later parts as values with generic names. Guidance from Pegasus and Figma suggests keeping Button as the set, then using properties such as Type, Size, and State, with values that match the code's props.

  4. 4

    Name the matching token

    Give the button background a semantic token named color-background-action-primary. Read it from left to right: color is the category, background is the property, action is the role, and primary is the variant. It says the job, not the shade.

  5. 5

    Name the states with the same pattern

    A disabled version can be added to the end of the same name, such as color-background-action-primary-disabled.

  6. 6

    Run the change test

    Ask whether the name still makes sense if the brand changes from blue to purple. Because the name describes the role, the answer is yes. Only the value behind the name needs to change.

Tip

A developer should be able to search for color-background-action-primary in the code and land on the same decision the designer named in the file. If the two names differ, the handoff will cause mistakes.

Check your understanding

Quick check

Your team has a color style called 'Light Blue 2'. It is used for links and for error text. The brand is changing its blue to purple. What is the problem with this name, and what would you rename it to?

How do you keep names working over time?

A good name on day one can go bad after a year. New products, new brands, and new team members all put pressure on names. The goal is to keep names stable, clear, and easy to follow as the system grows.

Why avoid vague and temporary names?

Some names say nothing about their job. A name like color-1 or color-2 forces every reader to look up what it means.

  • Avoid numbers that hide meaning

    Names such as color-1 or box-2 hide their purpose. Replace them with a role, such as color-text-link.

  • Avoid temporary words

    Words such as new, final, temp, or v2 feel useful today but mislead people later. Name the part for what it is, and let the version live in the file history.

  • Name things, not actions

    Nord advises nouns over verbs for components, because a component is a thing. Button is a good name. Clicking is not.

  • Plan for states before naming

    Decide the full list of states, such as hover, disabled, and dark mode, before you name the first token. Otherwise you will rename tokens in the middle of a project.

Why write the naming rules down?

A naming convention that lives only in one designer's head will drift. Write the rules in one short page, with examples of right and wrong names. Include the casing, the order of the parts, the allowed words for roles, and the rule for states.

Rules also need owners.

Tip

Before you add a new name, search the system for an existing one. Most new requests are a repeat of an old name under a different label.

Rename with care

Sometimes a name must change. A color name may be wrong, or a component may have a vague label. A rename can break files and code that still use the old name, so plan it instead of doing it in a hurry. Figma's variant tools are a good example of why. Figma's variants page says component names must follow a structure to be converted accurately into variants, so a rename can affect that conversion.

  1. 1

    Find every use

    Search the design file and the code for the old name. Note every page, component, and screen that depends on it.

  2. 2

    Decide if the rename is worth it

    Rename when a name is misleading, vague, or temporary. Do not rename only because you prefer a different style when the current name works.

  3. 3

    Change the name in one planned pass

    Update the design file and the code together, in the same release, so the two never disagree for long.

  4. 4

    Tell the team and record the change

    Post the old name, the new name, and the reason in the team's shared rules, so later readers understand the history.

Semantic names make future renames rarer. When a semantic token points to a primitive, a brand change can update only that link.

Summary

Naming gives every part of a design system a clear name that designers and developers can share. Build one consistent structure, pick one casing style, and name for purpose rather than look. Keep names free of vague and temporary words, write the rules down, and rename only with a plan. A system whose names are easy to read is a system people will actually use.

Sources

How is this lesson?

Last updated on 17 November 2026

Learn with me

Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.