Naming design tokens can sometimes be considered its own discipline. Naming is surprisingly straight forward, and if it isn’t then it solves the wrong problem.
This article is part of the Inside Design Tokens series, which splits into 10 articles:
- Definitions & Traits
- Features
- Modeling & Communication
- The Three Class Token Society
- Put your Tokens on a Scale
- Token Specification
- Naming <– this article
- Theming
- Internals
- The Hidden Knowledge
A lot has been written about naming design tokens, and Lukas Oppermann (2022) has collated this in his practical guide to name design tokens. Applying this brings people to both sides of the spectrum on one hand a chill mode and the other side a sweaty stressful mode.
How NOT to Name Design Tokens
When naming design tokens becomes a problem, then because this solves all other problems but naming design tokens. Here is a list of common mistakes:
- Find a schema or formula for all tokens
- Solve your communication
- Figure out bounded contexts (or groups or namespaces)
- Align with technical aspects (types or tiers)
- Led by tooling
This leads to hilariously complex formulae, leading to the impression you need a PhD to understand them. Samples can be found in Naming tokens in design systems (Curtis, 2020), category/type/item (CTI) (Style Dictionary), anatomy of a design token and organization (Gonzalez, 2021), naming the pyramid (Fluin, 2022), naming conventions for design tokens (Kavčič, 2022), and another set of conventions by myself (Gossmann, 2020) – to name a few.
Instead of solving all these issues with a naming schema for design tokens, address the challenges individually beforehand.
How to Name Design Tokens
Naming your design tokens is straight forward, when:
- you have established bounded contexts
- communication between contexts is clear
- a good story telling for using design tokens (optional but recommended)
- Scales are worked out and used appropriately to your system needs and and aligned with communication
- Token specifications define formulas for replicability and interoperability
With all of them ready, there is one more important fact to understand:
Design Tokens are isolated by their bounded context and so is their naming
With all the facts worked out, that most of the time already declares the tokens name – that’s the entire magic.
What Makes a Good Name?
Kavčič (2022) recommends a workshop for your team to find a good name to properly communicates, setting the base for storytelling to explain your design tokens. Along with that she lists a guideline including short
, meaningful
, easy-to understand
, modular
and consistent
. Take note that short
and meaningful
can mean mutually exclusive and easy-to understand
requires people to share the same context and is assumptive to a large extend. Here is another approach, incorporating the ideas from the list above:
- A good name is the manual for how to use the token
is the ideal case. Take note this sounds nice in theory, in practice this is not always achievable. It works for a couple of tokens, but certainly not for all – be aware of this. - A description to back up the name
the name is not always enough to convey the message, a description text can bring the ancillary information, but is not always present (or “in the eye” of a token user). - Don’t rely on common words
the industry has a magnet to use words such as primary or secondary (Gossmann, 2022), yet rarely defines them and gives room for abuse, be explicit in using such words or deny usage. - Pick unknown/uncommon words
in addition to the undefined words above and the requirement for people to share a context about common word usage (eg. t-shirt sizes and its default; I’m 162.5cm in body height and “small” is my default).
Do the opposite, pick words, that are uncommon but part of the vocabulary of the system. That will require people to look them up and learn them, instead of relying on unshared, undefined context. Works best with pattern scales.
References
- Curtis, N. (2020). Naming Tokens in Design Systems. https://medium.com/eightshapes-llc/naming-tokens-in-design-systems-9e86c7444676
- Fluin, S. (2022, August 16). The Pyramid Design Token Structure: The Best Way to Format, Organize, and Name Your Design Tokens. https://stefaniefluin.medium.com/the-pyramid-design-token-structure-the-best-way-to-format-organize-and-name-your-design-tokens-ca81b9d8836d
- Gonzalez, O. (2021, February 18). Design tokens cheatsheet. https://uxdesign.cc/design-tokens-cheatsheet-927fc1404099
- Gossmann, T. (2020, February 2). Full Featured Themes in Figma. https://gos.si/blog/full-featured-themes-in-figma
- Gossmann, T. (2022, April 21). The Primary/Secondary Controversy in Design Systems. https://gos.si/blog/the-primary-secondary-controversy
- Kavčič, R. (2022, September 14). Design Tokens 101. Design Strategy Guide. https://designstrategy.guide/design-management/design-tokens-101
- Oppermann, L. (2022, January 27). Naming Design Tokens – The Practical Guide. UX Collective. https://uxdesign.cc/naming-design-tokens-9454818ed7cb
- Style Dictionary (n.d.). Design Tokens. https://amzn.github.io/style-dictionary/#/tokens?id=category-type-item
With the strategic design, established communications, appropriately used scales, token specification and the understanding for good design token naming, let’s go and dive into themes with the next article in the series.