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 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
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!