How to use USWDS

USWDS provides principles, guidance, and code to help you design and build accessible, mobile-friendly government websites and digital services.

Get started with USWDS

Developers

Get started with our code base by downloading the code as a zip file or installing with npm.

Designers

Create wireframes and prototypes in Sketch or Adobe XD.

USWDS project wiki

Find detailed information about our design and development processes and our collected user research.

Before getting started with USWDS

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

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

Key concepts and tools

You don’t need to understand the following concepts and tools to install the design system, but you will need to know them to build with it:

  • 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.

We’ve created these resources to help designers start prototyping and developers start building quickly and establish a shared language to promote effective collaboration through the process of customizing and updating content. The USWDS community is also a resource available to you. Please get in touch with any questions, recommendations, before, during, and/or after getting started.

Adopt USWDS incrementally

USWDS helps the federal government design and build better digital experiences. As a toolkit to design and build government websites, the design system provides:

  1. Principles: USWDS design principles support and reflect the important guidance codified in 21st Century IDEA.
  2. Guidance: USWDS user experience guidance provides best-practice advice for assuring components do what users expect them to do.
  3. Code: USWDS code provides an accessible, mobile-friendly experience across government sites. Teams can contribute new components back to USWDS.

Together, these form a design system maturity model. Adopt the design system incrementally by starting to implement our design principles in your project. Even before adding any USWDS code, you can also begin to adopt our UX guidance (like this guidance for a button). Then, start small and start to incorporate USWDS design tokens into your site design.

The design system is flexible, and we expect you to adapt it as you adopt it. Use the USWDS maturity model to build a solution that best meets your agency’s mission and user needs.

A diagram showing the concentric circles of the USWDS maturity model, progressing from Principles on the outside, through Guidance, and finally to Code in the innermost circle.

Latest updates

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

Date Description
2022-01-27

Brought in “Before getting started” content from “Getting started for developers”. More information: uswds-site#1411