Published in


Reimagining a Token Taxonomy

Notes from design token projects, from audits to implementation

1 Plan

1.1 Recognize problems to solve and goals to reach

Most design systems have an established visual language applied across a catalog of UI components. There’s well-defined color choices, groups, and relationships; typography, space and size have some semblance of tokenization too.

  • Tokens are too shallow and simple, inhibiting the pursuit of dark mode, themes, and more.
  • Tokens are too general, applied broadly for distinct purposes.
  • Tokens are applied incorrectly: …brand-red for errors, …text-muted for dimmed borders, …forms-success for a positive trend, and so on.
  • “Tokens” aren’t really tokens, but disparate sets of poorly organized and conflicting variable lists.

1.2 Plan an approach

Grounded in problems to solve and goals to reach, it’s time to plan an approach. This small-to-medium size project need not plan all steps robustly. Yet, a discussion should resolve:

  1. What token types will you impact: generic and semantic colors only? Component-specific colors too? Or also typography, space, size, shape, elevation and more? Most projects are ≥80% color, and address other tokens as needed.
  2. Will component design remain unchanged, or will you also “enhance as you go” (e.g., add focus ring states) and/or “fix as you go” (e.g., correct for inconsistent divider line colors)? Most projects enhance and fix design as they go.
  3. When is your project done: when you have sufficient, token-infused specification or when integration is complete across Figma libraries, component code and documentation site?
  4. What UI components are in scope (usually, all of them), and which will you audit to inform early decisions (usually, many of them)?

2 Audit as-is “tokens”

Equipped with a plan, dig into design and code resources, find the tokens (and more masquerading as such), see how they are applied to UI components to identify concepts and form ideas of what to do.

2.1 Map token path(s)

Consider mapping token flow across design assets, documentation and especially into the depths of code repositories. A big picture can expose the breadth of impact, weaving from where tokens live into the files where partners import, integrate, transform and apply tokens with their work.

Zoomed out board of code file screenshots tracing a token’s flow from Style Dictionary through transformations and utilities to component files per platform

2.2 Collect existing, as-is “tokens”

Once you begun to inspect where “tokens” live, excavate tokens from:

  • Token code implementation(s) in tools like Style Dictionary
  • Variables, mixins and other utilities in component code repositories across web, iOS and Android implementations
  • Token and foundations pages in documentation websites
  • “Token” locations, such that different values and concepts may show up in one or more places (Figma, code files, etc).
  • “Token” descriptions (“Use for…”) across tools to identify what’s described where and what to reconcile across outputs.

2.3 Inspect how styles are applied in Figma

With tokens well understood, I’ll inspect how tokens are applied across components with a focus on frequency, intent and (lack of) precision. Figma’s Selection colors feature is a great help. Select all variants, and then trace through to each application one color style at a time, discovering how each is applied.

Inspecting Figma’s “Selection colors” to trace applied color styles
Same / similar tokens applied to different properties, components and semantic intents
Varying tokens often erroneously applied to other intents

2.4 Inspect “tokens” applications in code, too

Depending on your comfort level, you or a teammate could inspect and log lines of code that apply tokenizable decisions in today’s libraries and products. Focusing on even a small set of components can lead you to styling constructs and utilities across web’s CSS, iOS and Android to observe how tokens, variables and hard-coded values are applied.

Code applying existing tokens with rigor and precision
Code with poorly named variables and hardcoded values

2.5 Identify concepts as you explore

Once equipped, you can slice, pivot, sort and filter to analyze the data. As you synthesize what you’ve found, record the important ideas and concepts you’ll need to work through with your team. At its most formal, you could track those ideas in a table with columns for:

  • Alternative terms already in use or discussion
  • Token level the term applies to, such as property, variant, or state
  • Related as-is tokens used today that could be impacted
  • Rationale and other notes to inform decision making
Table to capture ideas and concepts to inform a first draft and workshop(s)

3 Decide to-be tokens

Equipped with as-is token data and emerging themes, it’s time to draft an improved taxonomy, get feedback, and iterate towards decisions.

3.1 Propose a taxonomy

Having paintakingly audited and analyzed the landscape, get to work! Establish a separate sheet of proposed “to be” tokens, that includes:

  • Token type (Generic, Semantic, Component) for sorting and filtering
  • Token value
  • Token aliases, via dynamic references to other rows

3.2 Workshop important choices

As proposed tokens take shape, convene a workshop. Always include essential design system teammates — designers and developers — and add other relevant stakeholders as needed. Workshops can serve two purposes: update the group on progress and make decisions together.

Figjam format, balancing presentation materials (above) with a series of workshop sections (below)
  • An example token indicating levels to discuss
  • Repetitive token structures ($esds-color-{concept}-{the gray one}-background, $esds-color-{concept}-{the red one}-background) to see how decisions play out
Set the stage with visual examples and sample token structures
  1. Individually, dot vote on an alternative for each choice.
  2. As a group, discuss each choice, eliminating options (as red) as you go
  3. As a group, agree on an alternative (such as alert for {concept}, error for {the red one}, and so on) by marking it green.
Choices with options and voting for alert tokens

3.3 Iterate choices to completion

After a few workshop(s), don’t be surprised if energy and interest in discussing token taxonomy wanes as decisions become increasingly niche. At this point, shift to direct messages, async updates, and the occasional Slack poll to iterate towards completion.

4 Implement the new taxonomy

With decisions made, it’s time to record tokens in a specification and transform code libraries, Figma assets and documentation.

4.1 Record as a specification

Most teams I work with record token taxonomies in a design specification rather than spreadsheet (too hard to find for most) or just Style Dictionary (a repository invisible to most token consumers).

Color token specification, including swatches, values, names, aliases, Figma styles and descriptions

4.2 Handoff and review(s)

As opposed to collaborative workshops, handoff sessions will typically be short: I’ll introduce the specs, we’ll discuss how to review and comment, we’ll resolve any high priority open threads.

4.3 Implement across Figma, code and docs

With a new token taxonomy in hand, it’s time to implement across outputs:

  • For Style Dictionary, implement the new tokens in 1+ JSON files and publish the update.
  • For the documentation site, update tokens page(s) and other impacted docs (such as Color, Typography, and Space).
  • For component code per platform, refactor how tokens flow in, variables and utilities refactored, and components updated one-by-one.
  • For your community, announce the change across communications channels like Slack and email.
Migration sample, indicating as-is value and to-be token proposed per relevant CSS rule



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Nathan Curtis

Founded UX firm @eightshapes, contributing to the design systems field through consulting and workshops. VT & @uchicago grad.