Getting started for developers

Get started using the design system by installing, compiling, and customizing USWDS code

Before getting started

USWDS includes over 40 accessible, mobile-friendly components out of the box, ensuring consistency and saving developers the need to build everything from scratch for their web-design and -redesign projects.

Components are built from (and further customizable based on) tokens. Akin to atoms in an atomic-design methodology, tokens are the design system’s predefined units of color, spacing, typography, and opacity that form the building blocks of design.

USWDS also provides tools and solutions that make it simpler to comply with legal requirements, such as the 21st Century Integrated Digital Experience Act and Section 508 of the Rehabilitation Act, like a simple way to pick accessible colors or a component that displays required links.

Key concepts

The following are concepts fundamental to the design system:

  • Design tokens: Design tokens are predefined units of color, spacing, typography, opacity, and more that form the building blocks of the design system.
  • Components: Components are simple and consistent solutions to common user interface needs, like form fields, buttons, and icons. If tokens are the building blocks of the design system, components are the building blocks of a site or service.
  • Utilities: Utilities are single-purpose classes mapped to USWDS tokens. Utilities allow developers to prototype with design system utilities without writing Sass or CSS.
  • Implementations: Implementations are how teams use USWDS in their projects, like in Drupal, as well as other platforms and frameworks. We’ll link to projects and community supported implementations.

You don’t need to understand these concepts to install the design system, but you will need to know them to build with it.

What you need

We recommend using the following tools when working with USWDS:

These instructions describe how to get started with USWDS using npm. If npm does not work for your project, you can download and install the system directly as outlined under “Download and install” in GitHub.

We’ve designed USWDS to support older and newer browsers through progressive enhancement. The design system follows the 2% rule: we officially support any browser above 2% usage as observed by analytics.usa.gov. In other words, USWDS version 2.0 supports Chrome, Firefox, Safari, Edge, and Internet Explorer 11 and up. The next major version of USWDS (3.0) will drop support of Internet Explorer 11.

Step-by-step

Get started with USWDS by installing the design system on your project, compiling your project’s Sass from the USWDS source, and customizing the design system to fit your project needs.

Phase 1: Install →

Phase 2: Compile →

Phase 3: Customize →