If you want to integrate design tokens into your design system but don’t quite know where to begin, you’re not alone. Adding design tokens to an existing system calls for good organization and consistent use. This already challenging task is not made any easier by the lack of standard naming conventions.

In this article, we’ll delve into how our team integrated design tokens into our design system, Ictinus. We’ll discuss the challenges we encountered, the solutions we came up with, and the impact design tokens had on our workflow. Finally, we’ll share insights gained from our experience.

What are design tokens?

A design token is a piece of data that encapsulates a single design decision.

The term ‘design token’ was first coined by Jina Anne at Salesforce in 2014. They can represent a wide range of properties and link (‘alias’) to other tokens, making them scalable by nature.

Sound familiar? It’s similar to how programming variables work: you declare a specific value which is then propagated to many different instances. These values and relationships can be represented in JSON format.

What are the benefits of design tokens?

In our preliminary research, we analyzed the approach of other Design Systems (e.g. Polaris, Carbon, etc.) and read up on token literature and best practices. Our early findings were enough to convince our team: tokens were worth the time, cost and effort of integration. Our biggest challenges at the time were gaps in communication and insufficient change tracking. Tokens promised to help with these issues as well as do the following:

1. Resolve gaps in communication

Design decisions often got ‘lost in translation’ due to inadequate documentation and time pressure. Discrepancies between design and implementation were not just common but expected. This translated to much more time and effort spent in QA – and still, mistakes could slip through.

2. Fix issues with change tracking

This gap in communication had a ripple effect. Changes in design documentation were not always reflected in current implementation. That made it hard to confirm whether a specific section of documentation was updated or not. When should we implement QA?

As a result, we had to freeze our design system to a specific version (V4); a last resort solution that opened a whole new can of worms. Last but not least, our current workflow all but ensured that the team ran at different speeds.

The more we learned about tokens, the more they seemed like a winning bet. They would help us resolve some of our biggest issues, become more efficient and enrich our design language.

3. Improve efficiency

Before Figma (our tool of choice) introduced variables, there was no way to natively link styles. Design tokens would allow us to mass-update multiple styles by editing a single aliased token. This would simplify maintenance and reduce cognitive load, allowing the team to focus on the bigger picture instead.

4. Extensive customization support

Design tokens can represent a wide range of properties beyond the usual color, typography, and layer effect styles. Tokens also support the following:

• Spacing
• Sizing
• Border radius
• Border width
• Animation styles

The challenges of implementing design tokens

It was not all sunshine and rainbows though. As mentioned before, a standardized framework for creating and using design tokens doesn’t exist just yet. In this article, Brian Heston addresses the most common design token implementation concerns.

Of special note is the mention that there is no common standard for naming and applying tokens. This lack of consistency poses challenges when combining components from different libraries. It also makes it hard to outline and follow a common set of best practices.

What token tiers are, and how we used them (aka layers, groups or sets…)

Before diving into token creation, we first needed to lay down the basics. What would we call different token levels, for example? And how many levels would we need?

Tokens can be organized into different levels of abstraction. Common names for different levels include ‘levels’, ‘types’, ‘tiers’, ‘layers’, ‘groups’, and ‘sets’. These levels help organize tokens based on their purpose, scope, or usage. We ended up going with ‘tiers’, as it was both the most unique-sounding and descriptive.

Naming settled, we shifted our focus to tier structure. How many tiers should we have? What should each tier contain? How would it relate to other tiers?

In the many faces of themeable design systems, Brad Frost suggests a three-tiered model that uses a vertical hierarchy. 

Tier-1, the lowest tier, contains tokens that encapsulate raw visual design materials. 

Tier-2 tokens are contextual, and link Tier-1 tokens to high-level usage. 

Finally, Tier-3 tokens are specific to components and link to Tier-2 tokens.

How we named our tiers

We settled on the name ‘global’ for Tier-1. It would contain every single tokenized value in our design system. ‘blue.3’, a token containing a single color value with no context, is an example of a ‘global’ tier.

Tier-2 would draw from ‘global’ to create contextual tokens. For example, ‘blue.3’, a global token, may link to the ‘sem.textColor.active’ semantic token to create a token describing text color for an ‘active’ state. We named this tier ‘semantic’ (‘sem’ for short).

You can think of Tier-2, the ‘semantic’ layer, as one of your theme layers. If you want to be able to switch to dark mode down the line, all you need is identical ‘semantic’ layers that point to different aliases.

Finally, Tier-3 became ‘component’ (abbreviated to ‘comp’). This final tier would link to Tier-2, drawing contextual tokens in component-specific combinations. 

Token name conventions and semantic attributes

With the tiers in place, it was finally time to think about token name structure. What should we include in a design token name, and in what order? This well-known, oft-referenced talk by the Asana team on Schema 2021 served as a great starting point. The whole video is worth a watch, but of special interest is the hierarchical naming convention the Asana team uses to name design tokens.

Inspired by Asana and mindful of HTML/CSS standards, we created our own set of naming rules as follows:

1. A token name is composed of the following semantic attributes: tier.category.property.state
   1. Tier: Indicates the tier the token can be found in.
      1. The ‘Global’ tier is omitted from the token name for the sake of simplicity.
      2. Tokens found in the ‘semantic’ tier start with ‘sem.’
      3. Tokens found in the ‘component’ layer begin with ‘comp.’
   2. Category: Chooses a general token category (e.g. ‘spacing’). When used in a ‘comp’ token, ‘category’ displays the component name.
   3. Group: provides context on a given category (e.g. ‘background’ as a subcategory to ‘color’).
   4. Property: Contextual value of token. May also be state or variant. May also reference alternative visual variants for non-interactive components.
2. Semantic attributes are separated by period (.)
3. Token names that include more than one word are formatted in camelCase.

How we use Tokens Studio for Figma (our not so secret weapon)

When we were implementing design tokens, Figma didn’t offer support for token creation as variables had not been released yet. Even now, variables do not support properties like border width (and, as of the writing of this article, cannot be exported in JSON without a plugin). This meant we would need to use a third-party tool. We chose Tokens Studio, a popular choice that we could easily integrate into our Figma workflow.

Tokens Studio for Figma represents tokens in JSON as a list of objects. You can create and edit tokens either via the user interface provided by the plugin or by directly editing the JSON code. 

The ability to store the generated tokens as JSON in GitHub branches was a game-changer for our team. It allowed development to review design work as it was being done. Upon approval, typescript code would be auto-generated from said JSON. Finally, small issues were addressed and corrected in a fraction of the usual time. This was a big step towards bridging the aforementioned communication gap.

Importing global tier tokens

Tokens Studio allows you to import existing Figma styles and convert them into tokens; this saved us a lot of time. After we imported our preexisting color, typography, and layer effect styles into Tokens Studio, it was time for the good stuff. We created extra categories such as spacing, sizing, and border radius.

Semantic tier tokens

It was then time to begin work on the ‘semantic’ tier tokens. These are tokens with contextual meaning that link to context-less ‘global’ tokens. Semantic style examples include text color, typography styles, icon sizes, and interaction palettes. These styles are then combined in many different ways to make the final tier, ‘comp’.

Component design tier tokens

The component tier is the final layer (Tier-3). Each token created in this tier links to a ‘sem’ token. This allows for easy tracking of individual component tokens while still maintaining scalability.

The ‘category’ semantic attribute for ‘Component’ tier tokens is always the component name. This level of granularity allows for better control when working with large design systems.

Here’s an example of a ‘comp’ token:

comp.button.compact.iconSize

• ‘comp’: indicates ‘component’ token tier
• ‘button’: the component’s name
• ‘compact’: applies to compact button
• ‘iconSize’: sets icon size property

Results and Impact

The adoption and utilization of design tokens significantly enhanced our team’s workflow. Design tokens helped our team create a common language spoken by all and allowed for a unified mindset. This fostered a better understanding between designers and developers regarding each other’s constraints. It also led to significant delivery time and quality improvements.

Internal design-to-development average time was reduced by roughly 30%. This has a lot to do with the fact that token structure is similar for both designers and front-end developers. As a result, understanding them and applying them correctly became a more intuitive process for both disciplines. This was also a big help towards streamlining communication and reducing excess noise.

It reduced visual discrepancies between design and implementation. As a result, time normally spent on QA was instead used to better develop the components and pad the documentation. This affected onboarding of users and products to the design system, speeding up the process by approximately 65%. This allowed us to create better, more thorough documentation for component behavior and patterns. This led to a sharp decline in bug fix tickets (to the tune of approximately 55%).

The team’s upcoming steps involve introducing the highly-anticipated theming to ORFIUM products. Our previous framework made this a pipe dream, but with tokens, sky’s the limit!

Takeaways

Here are some practical tips to help your team adopt and use design tokens:

1. Define a clear tier structure that your team can understand at a glance and use with ease. Each tier should have a distinct name, abbreviation, and purpose. 
2. Create naming conventions for your design tokens as a team. Make sure the naming conventions are easy to remember and use. 
3. Document everything token related. Documentation should be accessible and understandable by both design and development team members.
4. Simplify token creation and export with third party tools like Tokens Studio for Figma.

That’s all for now, folks! We encourage you to share with us your own findings and concerns at @LifeatOrfium.

_{To learn more about design tokens, check out Jina Anne’s 2021 YouTube video or read the video summary by Amy Lee.}

References

https://uxdesign.cc/naming-design-tokens-9454818ed7cb

https://medium.com/@amster/wtf-are-design-tokens-9706d5c99379

WTF are Design Tokens?

https://medium.com/fast-design/evolution-of-design-tokens-and-component-styling-part-1-f1491ad1120e

The Many Faces of Themeable Design Systems

https://medium.muz.li/unlocking-the-power-of-design-tokens-to-create-dark-mode-ui-18c0802b094e

Our Design System with React Components, Figma, and Storybook.

Reasoning

When we started building our Design System at ORFIUM, I was hard-pressed to gather information from other companies that had gone through the process or colleagues with this kind of experience. I hope that you will find answers in our story to some of the questions you’ll face when you go about creating a design system of your own.

Start of everything and the big Q

Big Bang — The start of everything

Over the past couple of years, we’ve seen more and more companies adopt the idea of a Design System into their core business. Creating and using a  design system can help to solve a number of problems for design and frontend teams collaborating. As the design system handbook defines, it helps  teams to:

• iterate quickly
• manage debt 
• prototype faster
• design consistency
• improve usability
• focus on accessibility

But what happens when you want to sync those two departments together and have that system stand as middleware? This is the point in our research where we had a hard time finding information. Turns out, it’s pretty challenging to find a one-solution-fits-all kind of answer.

At ORFIUM, the need for a DS came up as our products grew and we had to work on different projects that focused on different user flows. Furthermore, the nice problem of rapidly growing two departments (front-end and design) led us to the need for centralized information about our user journey and a more rapid and solid solution for building components. This is where the Design System comes in. 

To do that we decided to implement two different tools. 

• The first one would be a collection of design components, processes, style guides, and rules placed by the design team. These would be the one source of truth for any product design. So if we had one search page on a product every component used in that page would come for the design system’s components.
• The second tool is for the frontend team, which has to be in total sync with the design team. The components, dev standards, and rules that will be applied here will come mainly for the first tool and ensure that everything is in place. All components served by the design team to products will be available from the frontend team. 

Our Design System 

How we did it — Front-End 

Initial analysis

The first step was to identify what we were about to build. One of our primary considerations was to not waste resources, to ensure that no extra work would be put in for unnecessary outcomes. So the first question on the team’s mind was  “ do we really need to make everything from scratch”?

There are many well-known, well-structured, and open-source design systems out there, such as Material Design or Ant Design. So, why don’t we use that kind of a tool? We spent a decent amount of time considering our v1 designs of all the products. This exercise led us to the conclusion that we couldn’t use any other system. Here’s why:

• As our products grew we weren’t sure if we wanted certain rules for each system. Having a system and constantly trying to avoid fundamentals wouldn’t be a great fit.
• We didn’t want to kill the design team’s creativity.
• We wanted to keep our system lean. And carrying a package from a library that contained mostly elements we’d never use didn’t make any sense for Orfium.

Furthermore, it was time to establish how it was going to be used within the team. As we don’t currently use any sort of monorepos, we wanted to make sure that this library would have its own roadmap. We chose the use of npm and made it a public package. This way the team would have to use it as a public package contribution and we have to stick with many good processes. This move allowed us to pull Request labeling and procedures, automate our changelog and release system, and, importantly, to show our work to the world and be proud of what we deliver. 

First Baby Steps

Our implementation was broken up into 3 steps. 

1. We started by defining all style guides and what we’ll need for the future with our design team. Margins, paddings, typography, colors, and grid definitions, all of these are crucial inner parts of the system that are going to be used in many places and have to be constant.
2. We focused on the atomic design system for building all of our components, based on the style guides defined earlier. These parts, which we call components, were buttons, text fields, icons, chips, avatars, list items, etc. As we finished with the atom parts we moved to the molecules, which is what we call combinations of the previous atoms. Examples of those components are icon buttons, select, lists, etc.
   Pro Tip: I suggest that you do that early and define it with the team.
3. We moved into mostly visual testing. We started by using snapshots. With that, we knew every time we changed something, that visual part had changed. It was crucial, as the library will grow and everything is linked under the hood, that a small change doesn’t affect components negatively.
   Pro Tip: A visual comparison of any external tool doesn’t hurt.

Team Arrangement

We defined several ways of communication between the Product, Design, and Frontend teams to provide a solution that will be built once and will help all products in the way.

It is important to note here that we see the design system team as a non-product team and our two teams (design and frontend) maintain it.

Use of a Federated team

Each product has its team. This team consists of people from all departments: Frontend, Backend, Design, Product, and QA. The need usually comes from the Product team and grows there. 

The flow of requests, from request to implementation and release.

So if there is a new feature, let’s just say a select input that does only filtering, it is the responsibility of the frontend engineers and designers to raise that need of a new component to the DS moderators to discuss.

You can learn more about team structures and dynamics in a great article here.

Federated team flow based on Nathan Curtis article.

Furthermore, because there is no specific team for the design system, the request will be created as a task and can be handled by either the first developer available or the first product team member that needs to serve this in their roadmap.

This way we built it once and use it when there is a need. We always have a “Design System First” rule.

Roles

We have two roles defined to smooth out our communication.

Moderators make document decisions, provide guidelines, do the technical review, and communicate updates. They also create space for doers to get the job done.

As our DS consists of two departments, Frontend and Design, there are two moderators: a technical mod and a designer.

Moderators communication between teams

Doers are the system contributors  and builders. They execute on proposals or requests, and set priorities based on the design’s needs.

Planning

Yeah, it’s not what you think it is. Or maybe it is. The DS is not a product, so we don’t have scheduled events, velocity, or retros. But we an agreed meeting every two weeks. This is  mainly driven by the moderators to discuss new requests. They are the main members who need to attend, but both teams can join optionally as their input is important. This meeting is also where we vote on story points. Remember when we said that Product Managers who serve requests first are going to have them built? Well, story points help here for the team to know what it can create for the Design System. 

Problems we encounter

Of course, all the above didn’t work out of the box from day one! The first version was in beta mode. All the communication between us was unshaped. Let’s take a look at the issues we faced while setting up our Design System and its processes. 

Versioning

As we have many products and different roadmaps, we need to keep different versions for breaking changes. Having different versions allowed us to run at different speeds. So if we had 3 products that had 3 different roadmaps, we didn’t need to force anyone to always be up to date with the latest design system changes.

Representation of versioning

At first, we were manually fixing versions and keeping track of everyone. This took a lot of time and energy and, as we try to keep our DevOps mentality, we had to automate it. If we have a version for our library, the design team has to do the same. 

Now the system has automated releases (semantic) that we track. We introduce branches for the next release (major — breaking change release) that we have in the roadmap and we also have different versions in Figma, which match what we have and what is in the next version. Design and Frontend teams must be fully aligned with these versions, otherwise QA will fail.

Wrong tools for the job

We also needed to find the perfect tool for the job. We tried a couple until we found Figma . 

We started out with Zeplin, where we had all of our design screens. But it didn’t help our design team to keep track of their changes as their team grew. So we moved to Abstract. That tool solved the problem of version tracking, kinda. But that was right when our design system took off, and the point where we needed to split all of our product designs into smaller components. So the key that changed everything was this word, “components”. That’s when Figma comes in. With Figma, we now had the power for different versions and component-based designs. Our teams need to understand each other. Figma gave us this in a simple way.

Pro Tip: we went through 3 tools to end up at Figma because we only discovered the growing needs as we used the Design System. Learn from our experience and use Figma for Design/Frontend collaboration. 

Lack of communication 

Oh boy, two different worlds under the same roof, you can imagine. We had (and we still have) miscommunication. It’s one of the main ingredients of teams with different worldviews working together, we know it. The first and main problem was the main responsibility at the two ends. As the teams were working on the Design System, we were all questions like:

• what should we work on next?
• why is that there? 
• who will say this is approved to continue to develop?

We discovered that we were tripping over our shoelaces! Thus, we assigned what we call “the Gatekeeper” a.k.a the Moderator on each team. The Moderator is the go-to person for all of these questions. That person is not responsible to run all the tickets, is a member of the team but has to align with both teams to solve any problems and communicate with the other moderators for issues and features.

These two people now held the single source of truth, but we also have to make our decision-making more transparent. The solution was pretty simple: we started a Slack group where we shared our decision-making while we wrote it down on documentation.

As these things started to work well and we gained a good speed, we had to plan ahead. Our tasks, according to our federated system, must be visible to everyone to handle. We came to a place also when we wanted to have a rough calculation of how this affects all the other products. We know that we do well and all, but wouldn’t  it be awesome if we could say that we spent 10 hours building one thing that we used in 5 places? That’s 40 hours saved! 

For this, we agreed that we had to create a “planning” event where the moderators will attend and all other members optionally can join. At this event, we are voting for each task and creating rough planning for the upcoming weeks. On the completion of each task, we also count the hours that it took to complete. This way we know what we planned and how long it took. Sounds familiar, agile people?

Lastly, as our process of doing things was

planning -> coding -> code review -> QA -> completion

We decided that we need to change things a bit to avoid doing code reviews on the wrong things. So for this case and only we switched to

planning -> coding -> Design QA -> code review -> QA -> completion

This way we give developers the sanity to review a finished solution.

So, the solutions that are in place:

• Moderators for each team
• Specific chat to let both teams in on the decision-making 
• Planning and time tracking
• Design QA before code QA

What’s next

Enough with the past. What does the Orfium Design System, Ictinus, have in its future?

Every decision we make is based on a need. Also, any change in previous decisions we make is for the same reason, a new need. Right now there are 2 of them that we need to solve.

Documentations link

Lately, we see that our two documentations (technical + design) need to be compared or be visually linked. This will help us develop, as we could visually compare in real-time with the design itself. Also, it can help any QA or viewer compare the actual outcome which adds extra value. 

The planned solution for this is to link the storybook with Figma in two-way communication. 

Enhanced QA

We have much room to expand here as we only scratched the surface. The plan is to add more QA to UX and UI. Also, as per our DevOps nature, we can add a solution to automate in any release to check if something changed as per documentation from any side and show exactly what changed.

Conclusion

Building a design system is challenging, literally. It will challenge the way the teams work and communicate, collaborate with each other and how the org as a whole thinks about more abstract solutions. It’s a long road that requires constant fixes in both tech and processes. But it will pay off all the hard work when you see it in action. When one small UI or UX change suddenly affects 5 products and their users. 

Of course, your design system doesn’t have to match our story, because every company’s DS may be bigger. Even a standalone product.

If you wanna have a glance at our project check it at npm or Github.

*Credit for all of this hard work must go to both of the teams, Frontend and Design. Plus, thanks for all the assets for this article!

References

Team Models for Scaling a Design System

Evolving Past Overlords to Centralize or Federate Design Decision-Making Across Platformsmedium.com

Defining Design System Contributions

Time to Separate the Small-and-Quick from Larger Thingsmedium.com

Panagiotis Vourtsis

Head of Front End Engineering @ ORFIUM

https://www.linkedin.com/in/panvourtsis

https://github.com/panvourtsis

Katerina MIliaraki

Product Design Lead @ ORFIUM

https://www.linkedin.com/in/katerinamiliaraki/

https://twitter.com/katmiliaraki