How I Created a Scalable Design Token Framework.

Built to Power Any Design System.

Project Overview

Team

Engineering team
DSM teams
A design supervisor
Lead Designer — Design System (Me)
Product designer
A guest designer

Domain

A financial services client aimed to standardize the design across internally developed and newly acquired products using design tokens

Tool

Figma
Miro

Duration

Phase 1: 2025 Q1
Phase 2 2025 Q2

I use the design thinking process to guide the project.

First Challenge

Although I was new to Design Tokens, I was trusted to take on this project because of my skills and judgment.

Start with ambiguity

We were told that the client needed help with design tokens. However, after talking to the DSM team, it was clear they didn’t even know what those were.

Workshop

I self-ramped on design tokens through deep research to lead a workshop that aligned stakeholders on scope and goals.

Workshop Challenge

“How might I guide the audiences who have no knowledge about design tokens toward making these decisions comfortably within 45 minutes?

In the workshop I covered the topic of:

• What is a design token

• Different levels of design token

• Design token benefits on white labeling or theming

• Get alignment on what to be tokenized

These topics are crucial for clients to make a decision.

Following the workshop, we reached full alignment on the project's objective.

project's objective.

“Developed a scalable design token structure to support future roadmap needs, including multiple brands and dark mode.”

Research

DSM audit

Define

Audit Analysis

I used the informed data from the audit to:

Streamline the color usage of those categories
Adjuste the colors for consistency
Remove any one-off color
Remove any color that breaks DSM rules.

Create

Looking at the current color style palette informed me that the current Design System was intended to have 2 brands color – Primary and secondary.

However, how they use the color in the components could led to shifting color when white labeling. As you can see here using chip as an example.

In Enable state the background color is s shade of Primary, while when hover is a shade of secondary. It looks harmonize in the current brand color.

But if we have a white-label brand that has clashing primary and secondary color. It could led to this scenario where user hovers on a component and it changed color totally.

The other approach is to group the current primary and secondary color sets into a single scale, resulting in a more cohesive white-label product.

For the semantic-level token, I use a quick mock exercise to see how many tokens would play out in dark mode.
As you can see here, if all the white backgrounds are linked to the same color token, it doesn’t work as well in dark mode as the color looks too blended together.

I did more research to see how others tackle this issue. I found a material design’s concept of ‘surface,’ ‘container,’ and ‘on’ would help solve this issue.

Using the idea, I separate the background into 3 levels: page background, surface, and container to give more flexibility to the token structure.

Token Structures

Primitive Level tokens

For the Primitive Level tokens, I split them into 2 collections.

First is the global collection for all the values, like neutral colors or system colors, that would not be affected by a change of brand.

Second is the brand collection, which is all the values that depend on brand color.

That also includes the border radius of the button group, the fields group, and the cards group that I identified from the audit exercise.

Semantic-level tokens.

The semantic-level tokens. I split them into 2 collections.

First is System Collection, which contains all the values that are independent of light or dark mode.

Second is the Mode collection, where light and dark mode colors are established.

From the quick mock exercise, I made a document explaining different levels of background and other details of the Mode Collection structure.

Here is the documentation I created explaining more detail on container structure and status structure.

Component-level token

Here’s the component-level token documentation I created, including a naming structure based on best practices I identified during research.

Hand-off

Putting users first is second nature. Alongside the token docs, I put together a practical Do’s and Don’ts guide to help designers navigate the DSM with ease during hand-off.

Quality Assurance

I work closely with the development team, giving feedback to make sure the component is pixel-perfect and all tokens are applied correctly.

Outcome & impact

For the Client

Reduced UI inconsistencies. As use can see form the audit analysis that I color and streamline the DSM.
Speed up theme customization. With the token structure that is implemented, changing between white label brand and the dark mode will be just 1 click away

For the Agency

Empowering Designers for Design System Work. At a senior level, I focus on both project delivery and team growth. I created a template and training to equip designers with the skills to confidently tackle DSM projects.

If I were to do it again

Even the Design System Project needs feature requirement gathering and technical QA. For future DSM projects, I recommend assigning a dedicated person to capture feature requirements early. In this project, many detailed features and business needs surfaced during the QA phase, too late in the timeline for effective implementation.