CCSPVS – Advanced Naming Convention for Efficiency and Scalability.
Author: Oliver Ustinovich
An in-depth guide to creating a scalable and efficient naming convention for design tokens, implemented and tested in several world-leading cybersecurity companies. This approach enhances collaboration between designers and developers in large-scale projects.
You can also find this article on Medium.
Why This Matters
If you’re here, you’re probably about to start working on a new design system, or you’re thinking of optimizing an existing one.
A well-crafted naming convention for your design system is like a sturdy foundation that will help it withstand the test of time and growth.
- It acts as a universal translator between designers and developers, ensuring clear communication throughout implementation.
- It’s future-proof, allowing your system to grow without becoming chaotic;
- It’s a time-saver, streamlining your workflow;
- It keeps things organized and consistent.
Existing Naming Conventions
There are several approaches to naming conventions for design tokens. The following articles offer insightful comparisons of approaches used by companies like Adobe, Salesforce, and Bloomberg:
- Exploring Design Tokens: Establishing Semantic Naming Conventions for Color Tokens
- Naming Tokens in Design Systems
These conventions share many similarities. It seems like most of them are taking their roots in BEM, a popular naming convention for classes in HTML and CSS.
These conventions may differ in their focus (component-oriented vs. semantic), the number of levels they employ, and how they structure those levels.
In this article, I’d like to propose an approach that I’ve found particularly effective and have successfully applied at several major global IT companies. This method is more comprehensive and specifically tailored for robust design systems.
Proposed CCSPVS Naming Convention
Here’s the formula:
🏷️ --collection-category-scope-property-variant--state
Let me explain:
- Collection defines the type of styles (such as Typography, Color, Stroke, Rounding, Spacing, Effect, etc).
- Category
(optional)specifies the general purpose (such as Base, Interactive, Indent, or the component name in case of extended styles). This level can be omitted for some collections. - Scope
(optional)specifies the area of properties or context where a style is applied (such as Surface, Stroke, Text, Icon, Width, etc). - Property gives you the name of the property (such as Primary, Secondary, Container, xxs, etc). It’s the only mandatory level after Collection, which means that we should have at least 2 levels.
- Variant
(optional)specifies the variation of the property (active, inactive, expanded) - State
(optional)specifies the state of the token (such as Idle, Hovered, Disabled, etc). Used mostly for color tokens, but can be also easily used for Stroke, Effect or Spacing.
These six levels should suffice for most design systems. However, this doesn’t mean all token names have to be this long—it’s the maximum length they can reach when necessary. This level of detail is typically most useful for color tokens.
Simple, right? It’s easy to define and easy to find what you’re looking for. Here’s a few more things that are worth mentioning:
- In Figma, as shown on the picture above, this convention would have to be interpreted a bit differently to become more consumable for designers, while maintaining its integrity (as shown on the picture above). Read below for more details.
- As you can see, we’re missing light modes and themes here. The reason is that they don’t have to be a part of the token in both UX and FE. In Figma, different light mode values are usually stored separately in additional columns on the Primitive Colors level (depends on your architecture). On FE, they are also stored separately.
- Also, to make it consistent and translatable from Figma to Front-end I suggest using camelCase for multi-word levels.
Examples
Here are some examples to make it clearer:
--color-base-surface-container-active--hover--spacing-indent-level1--typography-base-fontFamily-header-primary--rounding-base-sm
Find the whole working structure example below.
Limitation & Workarounds
This naming convention does not include a System level defining a library. There are a few ways to deal with it:
- You can add this level to your naming convention, right at the beginning (it can be just added on the FE within the translation process), e.g.,
--dataViz-color-base-curve-default--idle - Or you can utilize the Category level for separate subsets of your libraries like Data Visualization, which usually utilize absolutely different styles, e.g.,
--color-dataViz-curve-default--idle.
Application in Figma
In Figma we can support this naming convention a bit differently. We should keep in mind that the real estate in the right Figma panel where we select Styles is limited. It means that we should keep the end token names limited if we want to be able to use them effectively.
Let’s take a look what we can get in Figma:
collection in Figma Variables / category group / scope group / property–variant––state
And to make it 100% clear—here’s the visualization:
To create a group in Figma Variables, simply add a forward slash (/) to your variable name. For example, Base / Surface / primary would create a token named primary inside a folder called Surface, which is itself placed within a folder called Base.
It’s important to note that not all styles can be stored in Figma Variables. Some will need to be kept as Styles, or even as both Variables and Styles.
Here’s my preferred approach: I keep everything as a Figma Variable, with Typography and Effects stored as Styles that are infused with Figma Variables.
Translation to Front-End
As you can see, Figma Variables and Styles use a simplified naming structure, showing only the last three levels instead of the full name. Don’t worry—this isn’t a problem. Your engineers can easily create a small script to automatically convert the Figma naming to the complete format.
My colleague Tony Ward has written an excellent guide on this topic: Syncing Figma Variables to CSS Variables.
Extended Styles
As I was mentioning at the beginning – the main idea behind this convention is that general semantic styles should be enough in most of cases. If every stroke for every component has a different color – then it’s not very consistent is it!? However, component-specific exceptions also have their place in this architecture. So if you plan on having component exclusions – don’t worry, it’ll work too. Although I appreciate to keep these exclusions as close to nada as possible.
In this naming convention, I call these component-related exceptions “Extended Styles.” Here’s how it works:
- If we define the general border color as
--color-base-stroke-primary-contrast--idle, then - An exception for a Tag component would look like this:
--extColor-tag-stroke-primary-contrast--idle, where “extColor” stands for Extended Color collection in Figma Variables.
This approach eliminates the need for an additional level in our naming convention to specify semantic or component-specific styles (as seen in many other conventions). Instead, we keep them in separate Collections. For example, alongside the Typography collection, we’ll have extTypography (if needed). Similarly, for Spacing, we’ll have extSpacing, and so on.
Working Structure Example
| Collection | Category | Scope | Property | Variant | State |
| color | base interactive info success warning error | surface stroke text icon | primary secondary onSolid | active onSolid | idle hovered focused selected disabled read-only |
| spacing | base indent | – | xs sm md lg xl level1 level2 | – | – |
| typography | base | fontFamily fontSize lineHeight fontWeight letterSpacing paragraphSpacing | 400 800 16 32 heading | primary secondary | – |
| stroke | base | width | xs sm md lg xl | – | – |
| rounding | base | – | sm md lg round | outer inner | – |
| effect | base | elevation glow blur | positionX positionY blur spread color | – | – |
This is it! Thank you for reading to the end! I hope this information proves helpful. Please feel free to share your feedback and ideas for improvement in the comments on Medium. Ciao!
