Getting started for developers

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:

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.

Step-by-step

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:

Phase 1: Install →

Phase 2: Compile →

Phase 3: Customize →

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date Description
2022-04-28

Added note that USWDS no longer supports Internet Explorer 11. More information: uswds-site#1538

2022-01-27

Moved “Before getting started” content to “How to use USWDS” page. More information: uswds-site#1411

2021-12-06

Added “Getting started for developers” guide. More information: uswds-site#1362