USWDS Design Tokens Guide

Overview

The purpose of this project is to provide lessons learned and guidance on how designers can progressively understand and apply the use of design tokens in their work — ultimately increasing adoption of the U.S. Web Design System (USWDS) among digital services teams working on government websites.

To inform the content in the guide, we interviewed multiple waves of UX/UI Designers to gauge their understanding and experience with USWDS design tokens, as well as ran usability tests of the finished guide. We discovered that all the designers are aware of tokens, but not all of them understand how to incorporate tokens into their work. Our guide aimed to address all designers that fall along the spectrum of design token newbie to token master.

They allow for both useful constraints and creative flexibility when either building a new system or working within an existing one.

While designers seem generally familiar with design tokens and know that they are a part of the U.S. Web Design System (USWDS), they usually are not incorporating the use of them in their workflows and collaboration with developers.

Mostly all of the guidance currently available on design tokens is geared to developers, not designers, making it more difficult to understand and use.

This is a missed opportunity to realize the full potential of USWDS and its role as a common language between design and implementation.

Many designers can become increasingly frustrated when their designs are misinterpreted by developers. Similarly, developers can become frustrated when designers misunderstand how the web works and how to build responsive, accessible sites.

Designers can have more control and contribute more to the development process by understanding tokens. When looking at the work of two UI designers with varying knowledge of tokens at my company, the designer who better understands and implements tokens when explaining their designs to developers consistently has better end products that are far more closely aligned with their designs.

So I decided to create a guide for my team.

My team and I created a microsite to document guidance on how designers can progressively understand and apply the use of design tokens in their work.

The guide includes two main components:

• “Maturity model“-style content meant to progressively increase the use of design tokens.

• Learning resources. Many designers mentioned during our prior interviews that they learn best while doing, so the resources are interactive to best serve the designers and also business development.

The Design Tokens Guide

The guide is split up into three main sections. The idea is to learn one section at a time to progressively adopt an understanding and ultimately use design tokens.

I presented the new guide to my design team during one of our bi-weekly team meetings. We used a template created in CodePen as the interactive part of our presentation so designers were able to interact with the tokens and ask questions in real-time. Overall, the guide was well-received and the implementation has proved to be especially useful for our UI Designers.

The site was created using Github, Jekyll, HTML, markdown, and the United States Web Design System.

I used Figma to ideate and Github and Microsoft Teams to collaborate.

More about Jekyll and the approach: Jekyll is a tool used for building static webpages. I can add content using Markdown (a simple, readable language) and then Jekyll can help to build the basic HTML structure. It makes building reusable templates and adding content very simple for designers. For this project, I created my own HTML structure when necessary and used USWDS to further customize and make it responsive.