Organising Design Systems

If you are a designer or engineer working on a scaling tech product, you must have found yourself blaming the other team for unclear specification, bad quality output or a general lack of understanding of how things work. If you haven’t, we would like to buy you a dystopian cup of coffee. At hand-off in critical projects, this results in last-minute chaos and leaves a bad taste in everyone’s mouth.

One significant aspect that design systems solve is serving as a single source of truth across products so that we can save ourselves from this mess at handoff. But what is this single source of truth and how do the teams working on it build and manage it?

As the design systems team involves people with a diverse skillset spanning across design, engineering, management, content, accessibility, etc., it is important that everyone in the team speak the same language to be on the same page. Once the team is aligned, it is much easier to make a system that can serve as a single source of truth.

Defining a single source of truth

A design system serves its purpose if all stakeholders share a common understanding, it’s hard to do that if people are getting their information from different sources. We maintain our design system on Figma, and for everyone in the team, it is the place where they can go for any information on the system. We chose Figma because of its robust features and the gap that it bridges between design and development. Here are a few features that we use regularly and love:

• Design Tokens
• Components & Variants (with props)
• Versioning
• Auto Layout
• Plugins (Custom & External)
• Library usage analytics
• Branching (still exploring)

PS: This post is not sponsored by Figma 🙈

Structuring Figma for Design System

Figma can be structured in several ways based on one’s particular needs, but to make it a single source of truth, we need to ensure that it covers everything from index to extensive documentation.

Our Use Case

In our scenario, we have multiple products that use different themes but similar underlying principles. So we follow the concept of composition:

• One Base File consists of foundations & principles (typography, global-color palette, borders, elevations, etc.)
• Multiple Theme Files (2 as of now) inherits foundations & principles from the base file and overwrite specific aspects in the theme files.

The file structure of DS in Figma — Blade Design System

Having multiple themes means you might have different styles(typography, colors, elevations, etc), but having multiple styles doesn’t necessarily mean that we shall have different names for each of the styles. So in order to fix this, we need a common abstraction that will have the same name across themes that can be mapped to different values from the base file.

To create this abstraction we have created a style for token mapping. Let’s see an example of how this mapping looks.

For example, we need a color for our primary CTAs in both themes, assume it is blue in one and red in the other, instead of storing the hardcoded values we alias the values with a token name i.e primary-color

• primary-color of theme A = blue
• primary-color of theme B = red

Now, there can be many values like these which can be different per theme but the purpose would remain the same. Therefore, we have set up a framework to name our tokens which can cover almost all the use-cases one can have while designing a layout or a feature. You can read this RFC to know more about our token naming convention.

Nomenclature of tokens in the Blade Design System (Read More)

Naming is not the only challenge though, it is just the first battle in a long war. The bigger challenge is how to document everything to serve the novice and advanced users of the system.

Assume that we want to build an Alert component and have to document the decisions of this component. So where do we start? We follow the following workflow for it:

1. Index
2. Introduction
3. Characteristics
4. Variants
5. Usage Guidelines
6. Platform Dependency
7. Accessibility (A11y)
8. The component (itself)

But what happens when you start scaling and have 100s of components? Do you see a problem here? Discoverability? As the design system evolves, discoverability becomes a challenge and it becomes difficult for users to find what they need.

So what do we do to address this? We group things in a way that serves the most mental models. We use Figma pages as our directory structure. The first page is the Index which shows all the things available in the system with their respective status. An index can help users get an overview of what they can expect from this system. We’ve two sections on the index page; the first section talks about the principles and the second one lists all the components & patterns. The information for a component provided on the index are:

• Thumbnail — to help users identify without reading
• Name — what is the component called in the system
• Description — one-liner about the component
• Version — to signify the version of a particular component in the system (this helps in the maintenance of a component)
• Status — tells the user the current state in the production of the component (complete/incomplete/in-progress/deprecated)

Global Index Page — Blade Design System

Don’t worry, to make it easy we’ve created a dummy Figma template on how to organise your design system towards the end.

Let’s build a component & see it in action

Let’s deep dive and see how we document a particular component inside a page in Figma. We use different artboards to separate sections so that each can be linked if we need to send links to a particular documentation section inside a component. Also, we have a different internal library to make these sections look similar (kind of a system inside the system) using headings, dividers, footers, notes, etc., which is not exposed to the consumers.

Index (specific to component)

Each component starts with its own index which has listed all the things one can read/view. There are a lot of frames on the page each depicting different types of documentation, therefore we needed some kind of index using that one can get an idea around what all is present in a particular component.

Index of an Alert Component (with hyperlinked frames)

Introduction

This section describes how the component is composed along with its place in our product ecosystem. It shows the whole blueprint of the component with labels. This helps users understand every detail of the component. This is how it looks for an alert component in our design system.

Example of an Alert component with its definition & anatomy

Characteristics (Useful for Developers)

This section gives the users information on the composition of the component and the properties of the composing elements. This is especially important to design system engineers. The characteristics section consists of two major things:

• Properties show the features (props as called in ReactJS) that a particular component offers to their consumers, it also helps in setting limitations to a particular component, for example:
  — defining a character limit to a text layer inside a component,
  — which field is required/optional
• Token/Component Usage table shows what all tokens and components (if any) are used inside a particular component. This helps developers to get an overall understanding just by looking at one frame.

Example of a props table & component usage table for an Alert component

Variants

As the name suggests this shows different variants available for a component. In case the component depicts any intent or gives some feedback to the users, it will also be listed here with their different variations & examples. For example, an alert component can depict a number of intents (positive, negative, neutral, etc.)

Intentions/Variations of an Alert component with examples. It also shows different contrast options offered by each intent

Usage Guidelines

This section guides the designers or developers on how to/not to use a particular component with some real examples from the product. This section is very crucial, it helps the user compare their use case to those in the examples and answer if this is the right component/variant for them.

Example of a Toast component showing the examples on how to & how not to use a component in different scenarios (messaging, actions, placement, etc.)

Platform Dependency

Different components might behave differently on different devices/platforms. This particular section focuses on the placement & behaviours of a component on a particular device or platform. This also guides consumers on what tokens are used on small/large devices. More than one example can exist for each section (desktop/tablet/mobile).

Example on an Alert component when rendered on a desktop, tablet & mobile device.

Accessibility (A11y)

Design systems present a unique opportunity to bake accessibility into your component libraries, both from a UI/UX design perspective and from a code perspective. There are different levels of accessibility:

• Usability is how your users experience while navigating through your product.
• Compatibility is how different assistive technologies interact with the system.

Both of these can be baked inside design systems for every component. It’s another topic to discuss in detail, let’s tackle a11y in another blog.

Accessibility (a11y) tips from one of the components

Component (with variants)

The last thing on the page is the component itself with all the applicable variants which adheres to all the guidelines documented in the component itself. These components are derived using the structure from the base file. The base file contains the skeleton of these components and the theme files just overwrite the tokens (such as colors, typography, borders, etc.)

An example of a Badge component with all the applicable variants

Challenges

It’s not a straight path, there are several challenges when we are working on making Figma a single source of truth. It is a kind of a central repository that everyone points to. Therefore we need to make sure that it is always updated. Here are a few challenges that we encountered in the journey.

Organising Style Tokens

As we discussed the structure of the files above, we saw that there is one base file that contains all the foundations/principles of the design system. And the multiple theme files inherit these properties to an extent to keep the brand consistent. Now we have two things that are being inherited from the base file into multiple files:

• Components: Base structure (skeleton) of all the components.
• Styles: Colors, Typography, Spatial System, Grids, etc.

We publish only the theme files to the consumers. We never publish the base file. While utilising these properties we get everything as an instance. Now, the component instances work as expected but there are no instances for styles. So, basically, we need to duplicate these things into multiple theme files, therefore there are high chances of human error.

Although we haven’t found an elegant solution for it, there are two ways we have attempted to solve it:

• We create a component of the base styles and use the instances of that component in the theme files. This way we have the same tokens across all files. This still needs manual intervention in case there is a change in the value of a particular token.
• Another way is using plugins, it is kind of a hack again, but we can create all the tokens at a single place(base file) and then just import the JSON of those styles into theme files and create local styles of the same in specific theme files. This also needs manual intervention for similar reasons.

Figma Feature Updates

We all love Figma because of its features and in the past two years, Figma has launched so many new things, that if you go to the two-year-old Figma you’ll feel handicapped.

Now, these quick changes are good but these come with a lot of maintenance overhead. And for a design systems team, it sometimes becomes challenging to cope up with all the changes. Also, having said that, not all features & changes would affect your tokens & components, but there are a few changes that would require you to work again. For example Introduction of auto-layout, variants, etc. These are some features that you can’t ignore as they will make your workflow more efficient over time.

Syncing Tokens

While we have tokens in place, there is no way one can transfer these token values to code other than manually writing it in code. I assume this might be a challenge for everyone working on design systems. To solve this challenge there are several plugins out there that might help you get the JSON. But that’s not only it, there might be different structures/formats in which design systems accept these token values. Therefore, we built our in-house custom plugin that does the job.

We have a frame inside Figma where we have defined tokens in a table structure that has a mapping to every theme(see the screenshot for reference). Now with just a click, this plugin scans this table and exports all the tokens in a viable JSON format that our code accepts in seconds. Not only this, but it also raises a PR on Github using the Github Actions feature so that nothing goes without approval to the codebase.

Figma Token Extractor — Custom Plugin (Read More)

There are many other minor challenges involved as well while working on design systems and everything might not be solved using the structure itself. Communication also plays a very vital role in making it successful, which will be a different topic to discuss on.

Wrap Up

It’s worth noting that design systems are not an end project, but more of an ongoing process that is always evolving over time and it might change drastically depending on the need. I hope these tips will be helpful, but it is also important to keep in mind that there’s no one-size-fits-all system and how you structure your system really depends on what works best for your team. Please leave comments with any suggestions or tips you have on creating a design system!

Here is a free Figma template on how to organise your design system.

Now that you have an understanding of how to organise a Design System on Figma, you might be curious about what goes on behind the scenes when building a component within such a system.

Fortunately, one of my talented teammates Rama Krushna Behera has written an insightful blog post on his experience of building a component in a DS — Behind the scenes of designing a design system component. It’s a great follow-up to what you’ve learned today and offers valuable insights into the intricate process of crafting design system components. Happy reading!