U.S. Web Design System in React
PreviousUse NPM over Yarn Architectural Decision RecordsNextCommunications Tooling: Video Conferencing
Last updated
Was this helpful?
Last updated
Was this helpful?
Status: Accepted
Deciders: @sawyerh, @aligg, @lorenyu, @rocketnova
Date: 2022-12-05
Technical Story: #19
The U.S. Web Design System (USWDS) only provides HTML and CSS for its components. It includes a small bit of vanilla JS to add interactivity to some components like the date picker.
It's common for projects to write their own React components to output the USWDS HTML, to reduce the amount of boilerplate needed to use the USWDS components.
discovered that Nava engineers and designers universally agreed that being able to use a React USWDS component library when starting new projects would be valuable.
Use the existing open source
Create our own React USWDS component library
Leave the responsibility to each project team
Add as a template dependency, making it available to all teams who use the template. The primary reasons are to avoid reinventing the wheel and because it's overall a well-built and maintained library.
Includes React components for all USWDS components and patterns.
Fairly well maintained.
Intentionally does not include any non-USWDS components.
Supports USWDS v3 (latest version)
Not necessarily a con, but just to call it out: We've only done a lightweight review of their technical implementation and hygiene — there's testing and linting, no reported a11y issues are open in GitHub or reported in Storybook, but we haven't done a comprehensive review of their code or a full accessibility audit. We're operating on trust in Truss's technical expertise, and an assumption that the outputted HTML markup is close to identical to what USWDS provides, so any a11y issues would likely be on USWDS's end.
Nava could create our own React USWDS component library, similar to react-uswds.
We'd have full control over the technical approach and wouldn't have a dependency on another vendor to incorporate changes or release new versions.
Requires more time and effort than using an existing library. We'd have to build and maintain the library.
Reinventing the wheel. We can always fork react-uswds if it no longer meets our needs.
This is the current approach. Each project team is responsible for creating their own React components for the USWDS components they need.
No additional work required from the Platform team.
Each project team has to spend time and effort building the components or making technical decisions related to how they'll integrate USWDS. Teams then have to write their own tests and fix their own bugs for these components. Overall a potential poor use of time and effort.
react-uswds is maintained by Truss, another vendor in this space. . Truss also maintains a for designers.
This was the recommended approach coming out of .
They to a specific version, which means that a project cannot use a newer version of USWDS until react-uswds updates it on their end. In practice, this could mean that a project may have delayed access to new component styles or CSS bug fixes that USWDS releases.