Spoiler alert..

You can read up on the outcomes of the case study at the end, but here is a sneak preview if you like dessert before dinner.

The beginning

I joined the Humanforce team with a mandate of delivering a multi-brand design system.

Having gone through recent acquisistions, the Humanforce business was growing. Within the organisation there were at least 5 design systems in code, and at least 3 in Figma.

In order to support integration across the product suite, a new design system was proposed that would cement a set of design language standards, and a range of flexible yet opinionated components.

The challenges

Cross-platform support

There are multiple development platforms, languages and frameworks in use by Humanforce products. In order to create a versatile, effective and future-proof design system, it would ideally be platform agnostic (reusable in most current and future web technologies).

As there is currently no single solution for creating cross-platform libraries, the design system needed to choose an optimal path considerating any trade-offs.

Product adoption

As there were existing design systems already in place for Mango's target products, it would not be a “swap and adopt” integration. The project needed a planned process of production and implementation to address the most important high-level design needs first.

The existing design systems also have bespoke business-driven decisions and logic that will need to be understood, adapted and normalised.

Ideally component-level adoption would be presented to product teams as one of three levels of importance / priority:

• Prescribed: Must be the same across all products for brand or business reasons.
• Recommended: Provides optimal cross-product user or developer experience.
• Optional: Usually solution specific, but potentially useful in other cases.

Design system survey

To understand the current experience of working with the various design systems in the company, I conducted a design systems survey.

There were two key goals for the survey:

• 👉 Establish a baseline to measure the impact of the new system
• 👉 Inform early architecture decisions and next steps

Design system playbook

To guide the process of building a new system, I created a “Design System Playbook”. This became a living and breathing document to house all the relevant information about the design system. It was both a primer for anyone looking to understand the inner workings of a design system project, and a record of decisions that would inform the project outcome.

Here are some of the useful features of the playbook:

Engineer showcase

Once the research and guiding principles we done, I presented the concept to around 40 engineers. The goal here was to establish “early and often” communication, validate (or challenge) the proposed solution, and ensure Mango would start finding a place in regular conversations amongst the teams.

Tokens

A large part of the early foundation work was defining the concepts and strategy behind the design tokens. This is a bigger deal than it sounds.

Auditing

In order to improve a system, first you need to understand it. I set out to audit the current product implementations of the basics like color, accessibility and contrast, typography, layout and spacing, and other general taxonomies.

Organisation

I built the token system around a 3 tier hierarchy of inheritance. These three tiers allow us to have a strong and flexible foundation built on proven design concepts, and provide an intuitive layer of semantic options to encourage simplicity, consistency and adoption.

--hf-color-brand-blue: #3C479D; 
--hf-font-family-base: 'Roboto Flex', sans-serif';

--hf-color-foreground-brand: var(--hf-color-brand-blue);
--hf-font-family-ui: var(--hf-font-family-base);

--hf-button-primary-background: var(--hf-color-foreground-brand);
--hf-button-font-family: var(--hf-font-family-ui);

Naming

A cross-platform design system serves a wide range of audiences, so to ensure everyone can understand their intention, design token names should:

Experiment and assign

Once I had the audit and a structure, I proceeded to develop the definitions and rulesets around the various token types:

Setup

After experimenting with various organisation models, I decided the best place to start was simple but scalable.

Mango UI

This is the core design system file (library). It contains the components, recipes, utilities and variables to be used by designers across the business.

Mango WIP

This contains all component experiments and ideation. Once an idea reaches a point of maturity to enter the system, it is moved to the Mango UI file.

Features

The Figma files have been designed so they are:

• Open to anyone in the business
• Easy to digest
• Extensive where it matters
• Simple where it counts

Variables

By leveraging Figma variables, we remain streamlined without external application or plugin dependancies.

We are able to use Style Dictionary and with a custom Figma plugin we treat our codebase as source of truth.

Choosing the tech

Given the complexities of serving multiple brands across a growing company, there was a need for the design system technology to be versatile.

There was considerations early in the process of adopting one of the existing systems, and working to modify it if possible. While it would have been fantastic if this was feasible, it introduced too much risk of providing a solution that either would not scale, or was not fit for purpose.

This led to the decision to build a monorepo for Mango, which would host a standalone foundations/tokens implementation, the core components and recipes, as well as the supporting documentation and interactive playground.

Documentation

Design system documentation is integral in communicating a range of important decisions and ideas, and should be the Source Of Truth for the system.

I believe design system documentation should cater for any and all design system stakeholders. This means it needs to be detailed, but written in plain english (or translations). It should accurately describe the purpose and use case for the pieces of the design system puzzle, and offer methods of accessing more information relevant to the stakeholder if needed.

The Mango documentation site is built using Astro Starlight, written using markdown files, and at a high level contains:

• Purpose and intent
• Basic design system concepts
• Tokens, assets, components and recipes
• Status indicators for components
• Technical implementation instructions
• A change-log of versioned releases
• Integrated design files
• Integrated codebases / storybook
• Who to contact

Outcomes