< back to all blog posts

Naming conventions for your design system

After covering off how to structure your Figma files, we thought we’d get on to naming… Naming conventions can be very hard and messy if you don’t do it correctly. It is one of the foundations that will help you better collaborate, and it makes your designs both easier to implement and understand.

So, how do you name your design files? What are the best practices for design system naming conventions? Are there some rules to follow for naming and structuring a design system?

You need to find the right balance between clarity, searchability, and consistency. We would highly recommend setting naming conventions with your dev team so you both use the same naming as much as possible.

Here are a few tips to start.

States

It’s been quite a surprise to find out that defining states is not so obvious for everyone. The same state can have different naming, and states’ behaviors are not defined the same way for different people. So let’s get started properly and have a clear and well-defined state naming convention. Here is a list of states whose behaviors I think are the most used ones.

Different states

Enabled
The “Enabled” state indicates an interactive component or element that the user can usually click on or interact with. This state distinguishes the “Disabled” state, suggesting that the component or element is not active.

Hover
The “Hover” state shows a visual return to users to indicate that they are hovering over the component concerned.

Focused
The “Focused” state is triggered when a user has highlighted an item, using an input method such as a keyboard or voice.

Pressed
The “Pressed” state is a visual indicator for the user to confirm that the component has just been clicked.

Activated
The “Activated” state provides a visual distinction between a component that has been pressed and remains visible, usually indicating an open state or an active input such as an accordion, tab, or navigation element. Above all, it is a highlight, whether initiated by the user or by default.

Visited
The “visited” state is mainly used on links to indicate which links the user already clicked on.

Selected
A ‘Selected’ state indicates that the user has made a selection of options using one of the following input methods: key, cursor, keyboard, or voice. Selected states should be moderately emphasized to be easily identifiable but not distracting. “Selected” carries a notion of choice and/or subscription instead of “Activated”, which is more of an indicator for users to find their way around.

Validated
A “validated” state indicates to the user that what they filled is correct and complete. It is a feedback on an action he/she just completed.

Dragged
A “dragged” state communicates feedback to indicate when a user presses and moves an element.

Error
The “Error” status concerns mainly form components to indicate input errors to the user visually.

Disabled
The “Disabled” state is the opposite of the “Enabled” state. It, therefore, indicates that the component is inactive and therefore not clickable.

Read-only
The “Read-only” state is between an “activated” or “enabled” and “disabled” state. It is not possible to interact with the component, but still, it is essential to display the component to indicate it has been well activated.

Perceptual patterns (styles)

When it’s about your styles, focus on function rather than description.
For example, with colors, it may be tempting to describe what the color looks like (e.g. primary-blue or main-blue), but this would be a mistake. Consider instead explaining what this color’s purpose is and keep it simple. For example, if blue is your main color, you should probably name it Primary. Moreover, if you’re rebranding and your primary color turns pink, you’ll be happy not to have to change the color name in your files. I also like to set main categories for my colors. In my experience, these categories fulfill a lot of common needs for design systems:

Brand colors

  • Primary
  • Secondary
  • Accent

Functional colors

  • Information
  • Success
  • Warning
  • Danger

Greyscale

  • Grey-000
  • Grey-100
  • Grey-900
Naming conventions for colors

If you need more granular information, feel free to add numbers for your shades, or use t-shirt size. This way, you could have a Primary-100, Success-200, Accent-300 etc for your color shades and Spacing-M, Spacing-L, Spacing-XL etc for your spacings, grids and layouts for example.

You can use the same logic with other styles such as fonts, shadows, icons etc.
For example, having Primary and Secondary fonts would make sense. You can also specify your shadows by function (shadow-hover, shadow-action, shadow-highlight…) or range it by intensity (shadow-100, shadow-200, shadow-300…).

Functional patterns (components)

With functional patterns, I like having a six-category level to organize my components, improve readability and improve usability. The way Zeelo organized it, starting from the category and ending at the theme level, is quite interesting. Here is what it could look like:

[Category] / [Component List] / [Type] / [Variant] / [State] / [Theme]

Category (the main category of your components, this gathers a whole family of your components)

  • Actions
  • Forms
  • Navigation

Component list (all the components belonging to the category)

  • Buttons, Floating button, Links…
  • Checkbox, Radio, Inputs…
  • Header, Footer, Pagination…

Type (if your component has different types of use)

  • Primary, Secondary…
  • Inputs-text, Input-dropdown, Input-date…
  • Header-desktop, Burger-menu…

Variant (specify all the variations of the component here)

  • Icon + text, Text only, Icon only…
  • 2 items, 3 items, no item…
  • Connected, Public…

States (the different states of your components – these are most used for web as it covers a lot more than mobile)

  • Enabled
  • Hover
  • Focused
  • Pressed
  • Disabled
  • Visited
  • Error
  • Validated
  • Read-only

Theme (if you have multiple brands or just a dark/light mode)

  • Light mode, Dark mode…
  • Pro, Public, Enterprise…
  • Product A branding, Product B branding…
Naming conventions for components

The naming convention for your design files

There are several ways to name your design files depending on your needs. Here are some best practices to give you some inspiration:

  • Use three-letter acronyms to display your project’s name
    For example, if you have a project named “Official Landing Page” you can name your file “OLP.” If your project is one word only, feel free to choose the 3 letters you think are the most relevant. For example, if it is “Pricing” it could be “PRC” or “PCG.”
  • Use acronyms to display the file’s owner
    If you need to know who created this file or to whom it belongs, I like to display the name as an acronym, too, with the first letter of the name and the two first letters of the last name—for example, Jules Mahé: JMA.
  • Use the JIRA ticket
    If it’s important to sync your design with engineering, feel free to add the JIRA ticket number in your file. It can be attached with a “#” at the beginning, for example: “#8832”
  • Use dates to keep track
    Even if it might not be relevant to Figma’s autosave, some people like to display dates when the file has last been edited. I suggest using the structure “year-month-day” to show this clearly when sorted alphabetically.
  • Use versioning
    It might be essential for you to display which version this document is. If your file doesn’t have much complexity, you can keep it simple and use V1, V2, V3. But you can also use SemVer if you need more details: 1.0.8. If possible, syncing with the versioning of your coded or documented components is always a good idea.

An explicit name for your file will always be the best way to display the correct information to your users. Keep it simple as long as you can, but feel free to add these tips above to help you organize your workflow better. Here are some examples of what this could look like:

  • #3490-Landing Page-JMA
  • OLP-Pricing-V2-JMA
  • Pricing 2.0.4
  • 20210924-Landing Page-JMA

Going further

Resources

Naming implies more than just best practices. Sometimes, you also need tools and methods to help you implement this naming strategy. Here are some resources to help you.

  • Rename it, a plugin to help you rename your layers, frames, and more in a much easier way. Available for Figma, Adobe XD and Sketch
  • UI Guidelines, to get an overview of most used names for components by other design systems
  • The component gallery, a ​​repository of interface components based on examples from the world of design systems

Naming workshop

Naming is also about federating your teams around your design system. That’s why organizing a workshop to decide naming conventions for your patterns is always a good idea. We made a Figjam to help you start this workshop. Feel free to duplicate and edit it, this is just one way to do it.

Name Casing Conventions

Another variable to consider when naming is how to be consistent with the name casing convention. In the end, no matter which one you choose, just pick one and stick with it so you can be consistent throughout your whole system. Here is a quick comparison to help you make your decision.

camelCase
The rule is to have the first letter of the first word in lower case and to get rid of spaces by capitalizing each word, except the first one. It is commonly used for variables and functions in JavaScript.

PascalCase
All the words are capitalized including the first one and all spaces are removed. It is commonly used for C# and Java.

kebab-case
Here we replace the spaces with a hyphen “-” between each word and all of them are lowercase. It is commonly used for CSS and HTML5.

snake_case
Very similar to the kebab-case, the difference with snake_case is the use of underscores “_” to separate each word. It is commonly used for databases programs such as SQL databases, but also with PHP or Python.

In my opinion, the kebab-case is the best suited for design needs.

  1. First, it’s more consistent if you use numbers or t-shirt sizes (grey-100 or spacing-xl, for example).
  2. Secondly, it’s easier in tools such as Figma to select only one word between each hyphen if you need to edit your naming. This is something you can’t really do with snake_case, PascalCase or camelCase since it selects the entire naming and doesn’t understand the different words between underscores or capital letters.
  3. Thirdly, it’s more suitable for design systems needs since it is mainly used for web languages (CSS and HTML5). Moreover, getting rid of capitalizing letters makes it easier for everyone (designers and developers) since you are not wondering if you are name casing your letters the right way.

Closing thoughts

Naming is hard, and don’t be surprised if you fail the first time. What is essential is to be sure everyone using your design system is aligned with the way you name your patterns. In the end, that’s all that matters when you build a design system: federate people so that they can work better together.
We also wrote an article about how to organize your Figma files for your Design System, and it can be a great addition to this topic if you are structuring your design system right now.

I hope that these insights, tips and best practices provide you with a little more realistic and helpful guidance on naming in design systems.