How to use USWDS

Phase 3: Customize

Customize the Design System with settings and custom code.

Now, equipped with building blocks that are accessible and cohesive, you can get creative. This phase is an overview of what you need to know to customize your project.

The U.S. Web Design System provides extensive support for theming via its theme settings. You’ll update the _uswds-theme.scss file in uswds.paths.dist.theme so its @use directive includes a list of all the settings you’re customizing for your project.

Note: If you use uswds-compile, as detailed in Phase 2, this tool adds this file to the directory you specify in uswds.paths.dist.theme.

Because uswds.paths.dist.theme will be updated the next time you run the init script, do this with caution! We don’t recommend using init more than once.

The USWDS Settings page describes each of the settings available in the settings files, as well as the values the settings accept. Most settings accept design tokens, visit the Design tokens section of our website for more information on the available tokens for color, spacing units, font size, and more.

You can also use uswds-compile to watch for any changes to your project Sass and recompile the CSS. Watch and recompile with the following command:

npx gulp watch

This command will run in your Terminal window. When you want to shut it down, use control-c.

Our showcase illustrates how other teams of developers and designers have taken the building blocks the Design System provides and redesigned them for their brand and message. We hope the possibilities inspire your team!

We’re looking forward to hearing about your experience and seeing how USWDS’s components look in your project!

Latest updates

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

Date Description

Replaced the outdated text: _theme-settings.scss with updated: _uswds-theme.scss. More information: uswds-site#1667


Updated theming instructions. More information: uswds-site#1538


Replaced the outdated text: uswds-gulp with updated: uswds-compile. More information: uswds-site#1424


Moved resources documentation to its own page. More information: uswds-site#1422


Added guidance for uswds-gulp. More information: uswds-site#1370


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