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 |
|---|---|
| 2022-06-17 |
Replaced the outdated text: |
| 2022-04-28 |
Updated theming instructions. More information: uswds-site#1538 |
| 2022-03-10 |
Replaced the outdated text: |
| 2022-02-17 |
Moved resources documentation to its own page. More information: uswds-site#1422 |
| 2021-12-14 |
Added guidance for |
| 2021-12-06 |
Added “Getting started for developers” guide. More information: uswds-site#1362 |
