UI Crux: Reasonable and scalable taxonomy for tokens

This article covers creation of a design token structure that respects developers pursuit of simplicity, uniformity and scalability. Say hello to RSTT, RSCSS new partner in crime.

Visual representation of a Reasonable System for Token Taxonomy

Why Reasonable and Scalable?

Before diving into the main event — the actual recipe for a scalable taxonomy, let me explain what I mean by a Reasonable System for Token Taxonomy (RSTT).

If you take a closer look into taxonomies out there, you’ll notice that, they are usually well-structured, but sometimes missing, in my opinion, key characteristics, manifested through:

1. Lack of logic or rationale in terms of real use cases for a token,
2. Final compound names are way too long to be scalable and reasonably operational.

In other words, if designer or developer would like to extend the design system on to a new scenario, he/she is sometimes unable to create a short coherent token while still keeping the same established taxonomy.

Most design systems fall into pit of too long tokens, that are either:

• unreadable or
• get truncated in narrow spaces

Components taxonomy is facing nearly identical set of issues. That’s why I figured I’ll strike two birds with one stone, sharing my point of view.

Tokenization and componentization of UI development solves huge amount of issues, yet I’d argue that lack of reasonable scalability in both process contributes to new series of problems, that could be have been avoided or minimized with better planning, and striving for said logic.

In the end, how many times you have noticed that all this complexity is starting to live (1) a life on its own, while (2) loosing all its flexibility and (3) detaching from reality of coding and designing?

What are Design Tokens?

First, let’s refresh our knowledge what design tokens are.

[A] What design tokens are:

1. Tokens are a way of storing and managing design decisions
   Like typography, color, spacing, etc.
2. Tokens are a technology-agnostic format
   They can be used across different UI frameworks and technologies.
3. Tokens are a self-explanatory entities
   They replacing meaningless static values with meaningful expressions.

[B] What design tokens are not:

1. Tokens are not CSS classes
   Tokens are technology-agnostic.
2. Tokens are not variables
   Tokens are a methodology of conveying design patterns.
3. Tokens cannot support themselves
   Tokens coexist in symbiotic relation with code, design and documentation. They need them in order to make sense.

Yet, they have many touch-points with both CSS classes and variables.

[C] What types of tokens are out there:

[Tier 1] Primitive tokens (aka Reference, Option tokens)
Reference raw value.
Examples:

  --d-type-display-sm : 1rem;
  --d-color-magic-500: #6050ff;

[Tier 2] System tokens (aka Alias, Common, Decision, Global, Meta, Semantic tokens)
Calls another token, instead of an actual value. Ultimately used to set up a matrix of common values within codebase an/or design system.
Examples:

  --d-type-size-body: var(--d-type-display-sm);
  --d-color-bg-magic: var(--d-color-magic-500);

[Tier 3] Component tokens (aka Override, Scoped tokens)
Description.
Examples:

--d-color-text-button-primary-default: var(--d-color-text-primary);
--d-type-size-button-primary-md: var(--type-size-button-label-md);

What is the design tokens glossary?

Second big thing, that we need to touch base, is the glossary — the controlled vocabulary — a metadata of words, phrases, and notations — subset of natural language—a set of semantic denotations describing certain concepts.

Let’s take a look at the list of properties once tokenized can bring value to the development-design process. Consider it also an example of a controlled vocabulary:

Please note, that the listed CSS attributes are not equal to property labels i created.

More specifically all property labels used within the tokens’ compound names, should make the token:

• Self-explanatory and consistent,
• Universally understandable and crystal clear,
• Searchable and short as possible.

Here is extract list of typical categories subject to tokenization:

Here is the rest of the glossary:

Here you’ll find combined scales for commonly tokenized CSS properties:

There is no point in listing absolutely everything. Thus if necessary, above glossary may be supplemented by:

1. Shared vocabulary, nicely listed in UI Crux/Shared Vocabulary →
2. UI Elements list in UI Crux/UI Elements →

Creating compound names

Ok, let’s get to the meat. I ordered the category and property labels within the taxonomy, from the most general to the most specific. As a result, the eyes of developers and designers can easily scan them.

Yet, token name should be as short as possible, so I do not see any point in repetitions, or using two property-labels, that have exactly the same meaning or using just one of them is enough to understand what each token does. The simpler the better.

Consider the following table as a guide for compound token names:

It can be also visualized as a following sequence:

RSTT build sequence

Key takeaways

Firstly, throughout planning phase, it became evident to me that, the real key for flexible and scalable taxonomy, is to base it on the System Tokens.

System tokens can be used in a wide variety of contexts and places. Thus, they have a broad range of use cases coverage.

In other words, system tokens have bigger:

1. Contextual precision
2. Coverage

— than primitive and component tokens, making them champions for flexibility, uniformity and scalability.

Secondly, during ‘assembly’ phase it became crystal clear, that it takes much more of planning and skill to develop a reasonable token taxonomy, then I initially though.

The complexity increases logarithmically with granularity, depth, size and requirements of an application, a library or a design systems.

Since, token taxonomy has to be integrated into the system — and at the same time — be on top of it, this case study required a blend of logic, experience, and skill together with meticulous strategizing. So if you are planning to tackle similar problem, take my advice into consideration.

Thirdly — and above all else — a developer-centric focus, proved to be the key in putting everything into a undestandable form.

Share it

If you find this story valuable, please share it with your design community.

If you’d like to talk about it, discuss something more in-depth or just want to say ‘Hi’, book a session with me through ADPList.

References:

Introduction to design tokens

Reimagining Design Systems at Spotify

Tokens in Design Systems

Driving Your Design System with Tokens

Design Tokens beyond colors, typography, and spacing.

Component-level Design Tokens: are they worth it?

Naming Tokens in Design Systems

Naming design tokens

Controlled vocabulary - Wikipedia