How to Better Name and Manage Variables in Figma

Establishing a set of Design Tokens is crucial work that helps you better manage your design system while making your designs more consistent and maintainable. In Figma, we can use Local variables to build Design Tokens, but how to better name and manage these variables is key.

Use English Naming

Please use only English or numbers to name your variables. Don't mix multiple languages, as this not only makes variables look messy but also confuses developers in Dev mode who can't easily copy useful code.

colors/background/默认  ❌  
colors/background/default  ✅

For example, if you use naming like colors/background/默认, in Figma's Dev mode, the generated CSS variable will be var(--colors-background-) - the Chinese "默认" disappears because Figma can't recognize Chinese characters and ignores them. Chinese characters are also not allowed in CSS.

Use / for Grouping

Grouping Rules

Please use / to reasonably group your variables as much as possible. This better organizes your variables, making them clearer and more readable, while also helping other designers and developers find and use them. Just like files, you wouldn't put all files in your computer's root directory but would organize them into different folders by category. Generally, you can use the following rules for grouping:

Variable grouping rules diagram
Variable grouping rules diagram
  1. Foundation: Represents basic design property types like colors, spacing, screen, etc.
  2. Target: Indicates where the variable is applied
    • Can refer to specific properties like border, background, box-shadow, etc., with complete naming like colors/border, colors/background, colors/box-shadow.
    • Can also refer to application scenarios like foreground (for text colors), danger (for emphasizing dangerous states), with complete naming like colors/foreground, colors/danger.
    • Can refer to specific components like Button, Input, Card, Icon, etc. For components, you may need further grouping since one component contains multiple styles, such as Button component can be divided into colors/button/background, colors/button/border, etc.
  3. Modifier: This part provides additional detail supplements for the variable, such as hover, active, focus, disabled, etc. It can also refer to specific states like danger, success, error, warning, and color levels like primary, secondary, etc. Not all variables need this part - for example, global variables like colors/border, colors/background, etc. Only add this when you need to subdivide the variable.

Manage Your Variables Like Files

With the above grouping rules, it seems we can manage variables well, but there's an issue. Suppose you have the following directory structure on your computer:

File directory structure example
File directory structure example

Imagine you're creating a variable named colors/background/hovered, meaning the background color in hover state. What about the default state background color?

You might think to use colors/background directly, which seems concise and reasonable. Let's see what problems this naming approach brings when restored in file management:

File management structure showing the problem
File management structure showing the problem

The actual structure in Figma:

Actual structure in Figma showing the issue
Actual structure in Figma showing the issue

Where is the colors/background variable? You'll find you can't manage default state and hover state variables in the same place because they belong to different folders/groups - this is the problem.

Just like managing numerous files on your computer, you naturally put files of the same type in the same folder rather than separating them, so you can better manage and find files.

Therefore, when managing variables, if a variable has multiple states, please name the default state separately, such as colors/background/default. Don't omit the Modifier part - this ensures all variables under the colors/background group are in the same place.

Correct variable organization structure
Correct variable organization structure

Methods for Separating Multiple Words

When encountering properties, states, or components composed of multiple words, you need separation. In Figma, you cannot use characters like ., {}, $ for separation. When needing to separate multiple words, please use the following formats:

  • camelCase -> twoWords
  • constantCase -> TWO_WORDS
  • kebabCase -> two-words
  • pascalCase -> TwoWords
  • pascalSnakeCase -> Two_Words
  • snakeCase -> two_words
  • trainCase -> Two-Words
  • capitalCase -> Two Words
  • sentenceCase -> Two words

Which naming format to use specifically should be fully communicated with your team, including developers and other designers. This is very important, and try not to include multiple formats unless you know what you're doing.

Separation vs. Grouping?

Only separate when you really need to, such as when properties, states, or components are composed of multiple words: border-radius, max-width, dropdown-menu

border-radius/sm  ✅
maxWidth/2xl  ✅

In the following cases, you should use grouping instead of separation:

colors/background-card ❌
colors/border-dropdown-menu ❌

colors/background/card ✅
colors/border/dropdown-menu ✅

In the error case above, colors/border-dropdown-menu illustrates the timing issue of separation vs. grouping well. "border-dropdown-menu" is not a single meaningful term - "dropdown-menu" is. Forcing them together causes confusion, while colors/border/dropdown-menu clearly expresses the relationship between border and dropdown-menu.

Always remember, you're creating Design Tokens that need to be used by multiple people and continuously iterated. Clear, understandable structure and naming are crucial. Don't fear grouping - unreasonable separation is more terrifying than grouping as it will make your variables increasingly chaotic and ultimately unmaintainable.

Reference Your Development Tech Stack

No rules are set in stone. You can adjust according to your team situation, but unified team standards are important. Our team uses Tailwind CSS in development, and Tailwind CSS configuration files typically use DEFAULT to represent default state. To maintain consistency, we also use DEFAULT to represent default state in Figma, such as colors/background/DEFAULT. This makes exporting Figma variables to Tailwind CSS configuration more convenient and unified.

If your development team uses CSS Variables, then when separating words, you should always use kebab-case format, as this is the common naming convention for CSS variables.

In summary, communication with the development team is necessary to ensure your variables can actually be implemented.