Six Styles for Naming Design Tokens
A comprehensive exploration of widespread and well-known naming conventions and their respective pros and cons.
The TL;DR
The style we use to name design tokens is heavily influenced by the technology we use.
The usage of certain tools and platforms comes with specific requirements for naming. Take for instance, prominent tools like Figma and Style Dictionary - these platforms often have their unique naming conventions that users must strictly adhere to.
On a similar note, programming languages such as CSS also have their specific naming requirements.
When a developer or designer is working across different platforms, it becomes an absolute necessity to comprehend these requirements thoroughly and adjust the token case naming in a manner that aligns with them.
This isn't just about following rules or working with the platform. It's really about keeping our code easy to read and consistent.
1. Kebab Case
It is the most widespread style also known as dash case or hyphen-case, which separates words with hyphens, like this kebab-case
.
Examples
color-text-default
color-text-primary
button-default
button-primary
space-xs
space-smbutton-primary
👍 Pro
Widely adopted and recognized as a standard.
Front-end best friend, like CSS and HTML.
Readable and easy to understand.
Logical separation of naming levels (components, category, property, modifier, etc.)
👎 Cons
Lead to confusion in the programming language, as the hyphen often serves as a subtraction operator.
It doesn't fit well with multiple terms — e.g.,
line-height
orfont-size
— where the single word also has hyphens.Difficult to read in the case of long names, as the hyphen uses the space of a single character.
2. Camel Case
Camel Case is a type of token case naming where the first letter of each word or abbreviation in a compound term is capitalized.
Examples
colorTextDefault
colorTextPrimary
buttonDefault
buttonPrimary
fontSizeXsmall
FontSizeSmall
👍 Pro
Camel case is often used in most of programming languages like Java and JavaScript, hence it aligns well with the common practices of these languages.
Provides a clear visual cue for the start of each new word within the token name, which can aid in understanding the structure and purpose of the token.
👎 Cons
Difficult to read when the name is made up of multiple words without any spaces or separators between them.
It could lead to confusion in those languages where the initial capital letter denotes classes or types.
Does not work well with certain modifiers, such as sizing scales and acronyms.
Does not function properly in case-insensitive systems.
3. Pascal Case
Pascal Case, similar to Camel Case, capitalizes the first character of each word. The main difference is that Pascal Case also capitalizes the first character of the name. For example, PascalCase
.
Examples
ColorTextDefault
ButtonDefault
FontSizeSmall
👍 Pros
Like Camel Case, it provides a clear visual cue for the start of each new word within the token name.
Often used in programming languages like C#, hence it aligns well with the common practices of these languages.
👎 Cons
May be difficult to read when the name is composed of multiple words without any spaces or separators between them.
It could lead to confusion in languages where the initial capital letter denotes classes or types.
Does not function correctly in case-insensitive systems.
4. Snake Case
Snake Case is another style of token case naming. In this case, words are typically all lowercase and separated by an underscore, such as snake_case
.
color_text_default
color_text_primary
button_default
button_primary
fontSizeSmall
FontSizeSmall
👍 Pros
Readability is high due to the underscore separating words, making them easier to comprehend at a glance.
It aligns well with languages like Python and Ruby, hence it suits these languages' practices.
👎 Cons
It could lead to confusion in languages where the underscore symbol is used for other purposes.
Not suitable for platforms that do not allow underscores in naming conventions.
Can be cumbersome to write out if there are many words in the name.
5. BEM
BEM (Block, Element, Modifier) is another naming convention that's widely used in CSS.
It's a methodology that provides a clear and strict framework for organizing CSS classes into independent modules. The name itself stands for the three parts of the naming convention:
Block: The standalone entity that is meaningful on its own.
Element: A part of a block that has no standalone meaning and is semantically tied to its block.
Modifier: A flag on a block or an element, used to change appearance or behavior.
Examples
block__element--modifier
header__logo--dark
button__icon--large
👍 Pros
BEM naming conventions create a rigid structure that can be used to identify the relationship between different pieces of code.
It makes the structure of the HTML/BEM classes more transparent and understandable, both for the developers who write it and the browsers that interpret it.
The naming convention helps to avoid collisions in naming due to the unique naming scheme.
It's very useful in teams and large projects where it's crucial to keep CSS scalable and maintainable.
👎 Cons
The naming convention can lead to long class names in a developed HTML file.
It requires a learning curve to understand and apply correctly.
It can be considered overkill for small projects.
6. Dotted Case
Dotted Case is another style of token case naming that is becoming increasingly popular, particularly in the context of Figma plugins such as Token Studio. In this naming style, periods or dots are used to separate words in a token name, for example dotted.case
.
Examples
color.text.default
color.text.primary
button.default
button.primary
fontSize.xsmall
fontSize.small
👍 Pros
Highly readable due to the clear separation of words by dots, making it easy to understand at a glance.
Shorter than
kebab-case
, clearer than anything else.Using dots to split words in the token name can make its structure and purpose easier to understand.
👎 Cons
Dotted Case might lead to confusion in programming languages where the dot symbol has a specific use, such as object property access in JavaScript.
It might not be suitable for platforms that do not allow dots in naming conventions.
Similar to Snake Case, it can be cumbersome to write out if there are many words in the name.
Which style should I use?
Each token case naming style comes with its own set of advantages and disadvantages. What matters most is not which style is objectively 'best', but rather, which one works best for your team and product.
Each team's preferences, product requirements, and the technologies used all play a critical role in this decision.
Running a naming workshop with your team could help set expectations and rules that everyone knows and approves of.
If you're interested in learning more about how to build a scalable naming convention, consider checking out my course “Design Tokens Pro - Mastering Design Tokens for Product Design”