Thomas Gossmann

Unicyclist. Artist. Developer.

Inside Design Tokens: Naming

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:

  1. Definitions & Traits
  2. Features
  3. Modeling & Communication
  4. The Three Class Token Society
  5. Put your Tokens on a Scale
  6. Token Specification
  7. Naming <– this article
  8. Theming
  9. Internals
  10. 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

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.