Get started using the Design System by installing, compiling, and customizing our code.
Getting started for developers will lead you, step by step, through the process of installing and compiling the U.S. Web Design System and customizing your project using components and design tokens. If you prefer a hands-on demonstration of this process, please check out our interactive tutorial, which will take you through the same steps using a pre-made example website.
As always, we’re here for you if you have any questions. Please get in touch via GitHub, Slack, or email!
What you need
We recommend using the following tools when working with the Design System:
- Node (use the version specified in the .nvmrc file; if needed, download the latest version from Node.js)
These step-by-step instructions describe how to get started with the Design System using npm (recommended method).
If npm is not a viable tool for your project, however, you can download and install the Design System directly as outlined in GitHub.
The Design System supports older and newer browsers through progressive enhancement. We follow the 2% rule: We officially support any browser above 2% usage as observed by analytics.usa.gov. In other words, Design System version 3.0 supports Chrome, Firefox, Safari, and Edge. Note the Design System no longer supports Internet Explorer 11.
Get started by installing the Design System on your project, compiling your project’s Sass from the Design System source, and customizing the Design System to fit your project needs as outlined in the following phases:
Meaningful code and guidance updates are listed in the following table:
Added note that USWDS no longer supports Internet Explorer 11. More information: uswds-site#1538
Moved “Before getting started” content to “How to use USWDS” page. More information: uswds-site#1411
Added “Getting started for developers” guide. More information: uswds-site#1362