Use U.S. Web Design System for components and utility classes

Status: Accepted
Deciders: Loren Yu, Rocket Lee, Sawyer Hollenshead

Context and Problem Statement

Projects should avoid reinventing the wheel where possible. A common place to do this is in the UI, by using a design system for frontend components and utility classes. This can help avoid inconsistencies in the UI, and can reduce barriers for new developers.

We want to use a design system that is:

Section 508 compliant
Open source
Well maintained and documented
Includes the typical components and design patterns needed for government websites

Considered Options

Decision Outcome

The template will provide U.S. Web Design System styling out of the box.

We will not follow their install directions, which suggests using Gulp as a task runner. Instead, to reduce the number of dependencies and configuration, we'll leverage Next.js's and Storybook's built-in Sass support. Copying the USWDS static assets into the project will be handled by a postinstall script in package.json.

Positive Consequences

USWDS is the most popular design system for U.S. government websites and is maintained by GSA employees. It is the recommended way to meet the website standards detailed in the 21st Century Integrated Digital Experience Act. More key benefits can be read about here.
Project teams can theme the USWDS if their project needs to match an existing brand.

Negative Consequences

Unlike the CMS Design System, USWDS doesn't provide React components. Project teams will need to create their own React components that output USWDS markup, or install a third-party library like react-uswds. In the future, the template could include this library by default.
CMS projects may need to swap out USWDS for the CMS Design System, although the CMS Design System is based on USWDS, so this may not be necessary right away.

Links

Previous research was done by Kalvin Wang and Shannon Alexander Navarro related to USWDS React libraries

PreviousDeployment Strategy NextFE server rendering

Last updated 10 months ago

Was this helpful?

Context and Problem Statement

We want to use a design system that is:

Section 508 compliant

Open source

Well maintained and documented

Includes the typical components and design patterns needed for government websites

Decision Outcome

The template will provide U.S. Web Design System styling out of the box.

Positive Consequences

USWDS is the most popular design system for U.S. government websites and is maintained by GSA employees. It is the recommended way to meet the website standards detailed in the 21st Century Integrated Digital Experience Act. More key benefits can be read about here.

Project teams can theme the USWDS if their project needs to match an existing brand.

Negative Consequences

Unlike the CMS Design System, USWDS doesn't provide React components. Project teams will need to create their own React components that output USWDS markup, or install a third-party library like react-uswds. In the future, the template could include this library by default.

CMS projects may need to swap out USWDS for the CMS Design System, although the CMS Design System is based on USWDS, so this may not be necessary right away.