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
Last updated
Was this helpful?