Adopt Diez design token framework

[connor-baer]

Context

The original design token RFC sketched out a cross-platform workflow for design tokens:

1. A single source of truth

Design tokens are typically in a platform-agnostic format such as JSON or YAML. They can therefore be the source of truth across platforms.

2. Updated by designers

Design tokens shouldn’t be updated by developers. These primitive values should be owned by designers. Ultimately, to make the process of updating design tokens easier, they could even be sourced from a design tool such as Figma.

3. Automatically transformed

Theming variables need to have a different format depending on the platform. For example, colors on the web could be RGB or HEX, but they need to be formatted as 6- or 8-digit HEX in Android. Design tokens can be automatically transformed to be consumed by any platform, based on their requirements.

So far, this repository only contains the static theme for Circuit UI, SumUp's component library for the web.

Proposal

I propose to adopt the Diez design token framework. It provides excellent tooling to implement the workflow that is outlined above:

• Extract tokens and icons from Figma and other design tools
• Transform design tokens for iOS (Swift, Objective-C), Android (Kotlin, Java), and the web (TypeScript, JavaScript, CSS/SASS)
• Automatically generate a documentation website
• Additional abstraction layer: map tokens to a platform-specific schema (e.g. the Circuit UI theme)

Have a look at Diez's website for a detailed overview.

Workflow

• The design team maintains a single Figma file with (only!) the design tokens.
• When changes are ready to be published, the design team runs a CLI command to automatically extract the design tokens using Diez. This step can be automated as much as it needs to be (e.g. trigger a GitHub Actions workflow through a custom Figma plugin).
• The platform teams map the design tokens to the schema for their respective platform. Diez takes care of transforming the raw values to the platform-specific formats.
• The platform schemas (aka themes) are consumed by the platform-specific component libraries and applications through versioned packages. Product teams are responsible for keeping their applications up to date.

Alternatives

While researching tooling for design tokens, I also reviewed Theo and style-dictionary. They are focused on transforming design tokens for different platforms (something that Diez can also do) but don't support extracting design tokens from Figma or other design tools. They also don't seem to be actively maintained anymore.

There was a project at a SumUp hackathon last year to build an internal tool to extract the design tokens from Figma. Unfortunately, the project didn't make it beyond a proof-of-concept. At this point, I'd prefer to use and support an off-the-shelf OSS tool.

[herberthenrique]

I really like this, is there any chance of we have a Proof of Concept with the Design team?

I would just add that we need to first, review all the design tokens. I remember that some colors in the designer's figma were totally not considering Circuit colors. Like, they had colors name we never had it, but the HEX exists. I don't know if I could explain the problem properly

[connor-baer]

I've gotten an initial confirmation from Giao Chung from the design team that this would fit well into their workflow and setup in Figma. I wanted to wait for feedback on this RFC before creating a proof of concept :)

There's a lot happening in the design system space in the design team. Two designers are working on this almost full-time. Giao Chung worked on (re)building the mobile design system first since that's where the most inconsistencies are. He's shifting focus to the web now and is doing an excellent job documenting the principles and constraints in detail.

Daniel (Bartel) has been working on the brand refresh which includes updated colors and a heavily reduced color palette.

TL;DR: We're working to bring Figma and Circuit UI back in line, with Figma being the source of truth with detailed usage guidelines.

[robinmetral]

Only (small) concern on my end, diez/diez hasn't had a contribution in about two months, and it looks like there are some stale issues and PRs in the repo.

GitHub insights show that diez is used in 19 open-source repositories, in contrast to 300+ for both Theo and styled-dictionary.

The tool looks good and is also backed by a company, Haiku, but do we know that it's being used by teams in production yet? If we start relying on this for our design tokens solution it would be nice to know it's mature enough.

Thoughts?

[connor-baer]

We're looking at this topic again as part of #871. @robinmetral was right to be concerned in his last comment, Diez hasn't had any new commits since August 2020 and can be considered unmaintained.

We'll look into alternative tools instead, such as https://github.com/salesforce-ux/theo and https://github.com/amzn/style-dictionary.