How to use USWDS
Migrating to USWDS 3.0
Migrate to USWDS 3.0 for Sass module support and an unbundled design system with minimal upgrade effort
Note: This guide provides instructions for upgrading from USWDS 2 to USWDS 3. If your project uses USWDS 1, you will need to update according to the USWDS 2.0 migration guide before proceeding with these steps. Not sure which version you’re on? Here’s how to check.
Why migrate to USWDS 3.0?
Use modern Sass syntax before the old syntax loses official support. USWDS stylesheets are written in a language called Sass. This language updated its syntax in 2020 and the old syntax is now deprecated. Sass will no longer support the old syntax starting in October 2022. We want teams to use source code with reliable support throughout the life of their project.
Improve performance and reduce the size of your project CSS. Using USWDS 3.0 with the new Sass syntax — called Sass module syntax — allows teams to unbundle their implementations of USWDS and use only the components and code that they need on their project. Depending on your project, this could mean a significant reduction to both the amount of CSS you ship and the time it takes to compile. This means faster load times, better scores in performance evaluation tools, and a better developer experience.
Stay up-to-date with minimal hassle. We want teams to benefit from the most current version of USWDS. Many projects should be able to migrate from USWDS 2 to USWDS 3.0 in about an hour. This new version makes no markup or style changes from USWDS 2.13.3. If you already use USWDS 2.13.0 or later, you should be able to update to USWDS 3.0 in a matter of minutes. Additionally, the under-the-hood changes we’re introducing in USWDS 3.0 will make it easier to stay up-to-date with USWDS over time. An incremental update now will make subsequent updates simpler.
Learn more about what’s new in USWDS 3.0 →
USWDS 3.0 package overview
USWDS 3.0 has a component-centered architecture. The source code is grouped into directories (or “packages”) which include the styles (Sass), JavaScript, tests, and templates (Twig) specific to a component. As we go through the migration process, many of the changes we’ll apply point your project at these new component-centered locations.
Here’s an overview of the new @uswds/uswds
package:
├── @uswds/
│ └── uswds/
│ ├── dist/
│ │ ├── css/
│ │ ├── fonts/
│ │ ├── img/
│ │ ├── js/
│ │ ├── scss/
│ │ └── theme/
│ └── packages/
│ ├── usa-component/
│ ├── usa-component/
│ ├── usa-component/
│ ├── uswds-bundle/
│ ├── uswds-bundle/
│ ...
Most of the source code now lives in /@uswds/uswds/packages
but some compiled assets and some backward-compatible helper files still live in /dist
.
An individual package looks like this:
│ ...
│ ├── usa-accordion/
│ │ ├── src/
│ │ │ ├── content/
│ │ │ │ ├── index.js
│ │ │ │ ├── usa-accordion.json
│ │ │ │ ├── usa-accordion~bordered.json
│ │ │ │ ├── usa-accordion~multiselectable.json
│ │ │ ├── styles/
│ │ │ │ ├── _index.scss
│ │ │ │ └── accordion.scss
│ │ │ ├── test/
│ │ │ │ ├── accordion.spec.js
│ │ │ │ └── template.html
│ │ │ ├── index.js
│ │ │ ├── usa-accordion.stories.js
│ │ │ └── usa-accordion.twig
│ │ └── _index.scss
Most teams won’t ever need to know what’s happening inside the USWDS source code, but the more you know about what’s going on under the hood, the better you can understand what’s happening and why as you migrate to USWDS 3.0.
Learn more about USWDS packages →
Migration overview
There are four necessary steps migrating to USWDS 3.0. In addition to the required steps, we also recommend updating your codebase to the Sass module system (Step 5) and optimizing your installation to improve CSS size and compile time (Step 6).
- Check your current USWDS code and settings versions
- Install the USWDS 3.0 package
- Update your Sass compiler settings and recompile CSS
- Integrate any recent USWDS changes
- Recommended Update to Sass module syntax
- Optional Optimize your installation
1. Check your current USWDS code and settings versions
USWDS 3.0 uses the same styles and markup as USWDS 2.13.3 — and, with one exception, the same settings. This means that if you’re currently using USWDS 2.13.3, there are no styles or markup to update. But if you’re using a version older than 2.13.3, migrating to USWDS 3.0 may mean updating some of your markup and settings.
So, before migrating, check the versions of both your existing USWDS code and its settings (since code and settings may be different).
Check your project’s current package.json
file and your project’s _uswds-theme
files.
Your package.json
file will display the version of USWDS in a line like "uswds": "^2.12.2"
.
Your theme files will have a version number at the top, under the image of the American flag. Note these versions so we can make the proper updates in Step 4: Integrate any recent USWDS changes, below.
/* package.json */
"devDependencies": {
"uswds": "^2.12.2"
}
/* _uswds-theme-spacing.scss */
/*
* * * * * ==============================
* * * * * ==============================
* * * * * ==============================
* * * * * ==============================
========================================
========================================
========================================
----------------------------------------
USWDS 2.12.2
----------------------------------------
SPACING SETTINGS
----------------------------------------
Read more about settings and
USWDS spacing units tokens in the
documentation:
https://designsystem.digital.gov/design-tokens/spacing-units
----------------------------------------
*/
2. Install the USWDS 3.0 package
Once you’ve noted the version of USWDS you’re currently using, you can update to the new USWDS package (@uswds/uswds
) and remove the old one (uswds
).
- In a terminal window, navigate to your project root.
- Install USWDS 3.0 with
npm install @uswds/uswds --save-exact
- Uninstall the old USWDS package with
npm uninstall uswds
3. Update your Sass compiler settings and recompile CSS
USWDS 3.0 requires the use of Sass Load Paths to compile properly.
USWDS 3.0 load paths must include a path to the @uswds/uswds/packages
directory, typically by updating an IncludePaths
setting to include node_modules/@uswds/uswds/packages
.
Add this load path to your compiler settings, or update any old paths if your compiler already includes them. We have guidance for a few common compiler setups.
Note: USWDS relies on Autoprefixer to make its compiled CSS browser-compatible. If your compiler does not already use Autoprefixer, we strongly encourage that you add it to your project.
- How do you know you're using USWDS Gulp? Search for a line like
const uswds = require("./node_modules/uswds-gulp/config/uswds");
oderconst uswds = "node_modules/uswds/dist"
in your gulp setup. This indicates that you're using the gulp setup we distributed as USWDS Gulp. Update your versions of the
sass
andgulp-sass
packages if you're using them. If you use thesass
package, run the following command in the terminal:npm install sass@latest
If you use the
gulp-sass
package, run the following command in the terminal:npm install gulp-sass@latest
- The
sass.sync
function is no longer supported in the latest versions ofgulp-sass
. Replace any instance ofsass.sync
with simplysass
:- sass.sync({ + sass({
If you use
sass
andgulp-sass
, you'll need to update how they work together. Update yourconst sass
toconst sass = require("gulp-sass")(require("sass"));
:- const sass = require("gulp-sass"); + const sass = require("gulp-sass")(require("sass"));
- Update the USWDS
const
elements to the updated USWDS package location:- const pkg = require("./node_modules/uswds/package.json"); + const pkg = require("./node_modules/@uswds/uswds/package.json"); ... - const uswds = require("./node_modules/uswds-gulp/config/uswds"); + const uswds = "./node_modules/@uswds/uswds"; or - const USWDS = "node_modules/uswds/dist"; + const USWDS = "./node_modules/@uswds/uswds";
Search for references to
${uswds}
in theincludePaths
andgulp.src()
found in your project’s gulp files. These paths tell the Sass compiler where to look for USWDS source files.Some of our file directories have moved in USWDS 3.0, and it is necessary to point gulp to the correct location inside the
@uswds/uswds
package. Below are snippets from the standard USWDS Gulp references and their necessary updates. If your code usesUSWDS
instead ofuswds
, just keep the case you have.// location of theme files: - gulp.src(`${uswds}/scss/theme/**/**`) + gulp.src(`${uswds}/dist/theme/**/**`) ... // location of font files: - gulp.src(`${uswds}/fonts/**/**`) + gulp.src(`${uswds}/dist/fonts/**/**`) ... // location of img files: - gulp.src(`${uswds}/img/**/**`) + gulp.src(`${uswds}/dist/img/**/**`) ... // location of compiled js files: - gulp.src(`${uswds}/js/**/**`) + gulp.src(`${uswds}/dist/js/**/**`) ... // Sass's load paths: includePaths: [ PROJECT_SASS_SRC, - `${uswds}/scss`, + `${uswds}`, - `${uswds}/scss/packages`, + `${uswds}/packages`, ],
- Recompile your Sass as usual. When it compiles, it's using USWDS 3.0!
- How do you know you're using USWDS Compile? Search for
const uswds = require("@uswds/compile");
in your gulp setup. This indicates that you're using the@uswds/compile
package in that JavaScript file (typically that file isgulpfile.js
). - Update the
gulpfile.js
to include auswds.settings.version = 3;
line. This setting tells USWDS Compile which version of USWDS you're using. USWDS Compile handles the load paths and package locations automatically./* gulpfile.js */ const uswds = require("@uswds/compile"); + uswds.settings.version = 3;
- Recompile your Sass as usual and check that your files compiled as expected. When it compiles successfully, it is now using USWDS 3.0!
-
Search for references to USWDS in the
includePaths
andsrc()
found in your project’s gulp files. These paths tell the Sass compiler where to look for USWDS source files. TheincludePaths
section may look like the following:.pipe( sass({ includePaths: [ PROJECT_SASS_SRC, `${USWDS}`, `${USWDS}/uswds/packages`, ], }) )
- Make sure
includePaths
includesnode_modules/@uswds/uswds/packages
in its array. - Update any
src()
references to point to the correctnode_modules/@uswds/uswds
location. Some of the file directories have moved in USWDS 3.0, so confirm that you are accounting for these new locations in your paths.- Fonts:
@uswds/uswds/dist/fonts
- Images:
@uswds/uswds/dist/img
- Theme files:
@uswds/uswds/dist/theme
- Compiled JavaScript:
@uswds/uswds/dist/js
- Packages:
@uswds/uswds/packages
- Fonts:
- Recompile your Sass as usual and check that your files compiled as expected. When it compiles successfully, it’s using USWDS 3.0!
In webpack, include includePaths
within the sassOptions
of your Sass loader:
loader: "sass-loader",
options: {
sourceMap: true,
sassOptions: {
includePaths: [
"./node_modules/@uswds",
"./node_modules/@uswds/uswds/packages",
],
},
},
This array needs to include "./node_modules/@uswds/uswds/packages"
.
4. Integrate any recent USWDS changes
Since USWDS 3.0 is based on USWDS 2.13.3, any markup or settings migration comes from migrating from your current version to 2.13.3. If you’re already up-to-date, this won’t take any time at all, but there have been some changes that might be breaking changes for your project over the course of the USWDS 2 branch.
Follow the instructions in each section that applies to either your USWDS version or your settings version. Changes specific to markup have a Markup tag. Changes specific to settings have a Settings tag.
Settings Remove $output-all-utilities setting.
We’ve removed the $output-all-utilities
settings and replaced it with $output-these-utilities
which is a list of the utilities you want to output.
What to do
- Check to see if you have
$output-all-utilities: false
in your utilities settings. - If so, replace it with
$output-these-utilities: ("module", "module", "module");
where eachmodule
is a utility you wish to include in your project. For a complete list of utility modules, see the utility module list in Managing Utility Classes, below. - If your settings include
$output-all-utilities: true
, remove the setting entirely.
Markup Update any instance of the small search button.
You’ll need to update any instances of the small search button on your site. We’re now using explicit images to better support legibility in instances where icons do not load.
What to do
- Check your codebase for instances of
<span class="usa-sr-only">Search</span>
. - Update the markup from the old version to the new version if you use it.
Old code
<button type="button" class="usa-button" type="submit">
<span class="usa-sr-only">Search</span>
<button>
New code
<button type="button" class="usa-button" type="submit">
<img
src="{{ uswds image path }}/usa-icons-bg/search--white.svg"
class="usa-search__submit-icon"
alt="Search" />
</button>
Markup Update social media icons in the footer.
You’ll need to update social media icons in the USWDS footer. We’re now using explicit images to better support legibility in instances where icons do not load.
What to do
- Check your codebase for instances of
usa-social-link.
- If you use it, update the markup from the old version to the new version.
Old code
<a class="usa-social-link usa-social-link--facebook"
href="{{ link }}">
<span>Facebook</span>
</a>
<a class="usa-social-link usa-social-link--twitter"
href="{{ link }}">
<span>Twitter</span>
</a>
<a class="usa-social-link usa-social-link--youtube"
href="{{ link }}">
<span>YouTube</span>
</a>
<a class="usa-social-link usa-social-link--instagram"
href="{{ link }}">
<span>Instagram</span>
</a>
<a class="usa-social-link usa-social-link--rss"
href="{{ link }}">
<span>RSS</span>
</a>
New code
<a class="usa-social-link" href="{{ link }}">
<img
class="usa-social-link__icon"
src="/usa-icons/facebook.svg"
alt="Facebook" />
</a>
<a class="usa-social-link" href="{{ link }}">
<img
class="usa-social-link__icon"
src="/usa-icons/twitter.svg"
alt="Twitter" />
</a>
<a class="usa-social-link" href="{{ link }}">
<img
class="usa-social-link__icon"
src="/usa-icons/youtube.svg"
alt="YouTube" />
</a>
<a class="usa-social-link" href="{{ link }}">
<img
class="usa-social-link__icon"
src="/usa-icons/instagram.svg"
alt="Instagram" />
</a>
<a class="usa-social-link" href="{{ link }}">
<img
class="usa-social-link__icon"
src="/usa-icons/rss_feed.svg"
alt="RSS" />
</a>
Settings Update three deprecated settings.
Each of the following settings is no longer set-able. If you use any of these settings, they may no longer reflect your intention. These are the deprecated settings and their defaults:
$theme-input-tile-background-color-selected: "primary-lighter"
$theme-input-tile-border-color: "base-lighter"
$theme-input-tile-border-color-selected: "primary-lighter"
What to do
- Check this list to see if you changed the default value.
- If you did change the default value, this change will no longer affect the input tile.
- Assure that the input tile still displays well: check your codebase for instances of
input--tile
and check the affected part of your site if you get a match.
Settings Check three settings with changed defaults.
If you use any of these settings in your code, the output may change:
Setting | Old default | New default |
---|---|---|
$theme-color-success-dark |
"green-cool-50" |
"green-cool-50v" |
$theme-color-success-darker |
"green-cool-60" |
"green-cool-60v" |
What to do
- Check your settings to see if they are set to either the old or the new default.
- If they use either the old or the new default, delete the setting from your settings file so it uses the system default.
Einstellungen Replace the deprecated $theme-site-max-width
variable.
We deprecated the $theme-site-max-width
variable. We’re using $theme-grid-container-max-width
instead.
What to do
- Replace instances of
$theme-site-max-width
with$theme-grid-container-max-width
. If your layout is affected by this change, remove this setting from your settings file.
Markup Replace the thumb_down_off_alt
icon with thumb_down_alt
icon.
We replaced the thumb_down_off_alt
icon with thumb_down_alt
in our default icon sprite.
What to do
- Search for any instances of
thumb_down_off_alt
- Replace it with
thumb_down_alt
Settings Check five settings with changed defaults.
If you use any of these settings in your code, the output may change:
Setting | Old default | New default |
---|---|---|
$theme-alert-icon-size |
5 |
4 |
$theme-table-border-color |
"ink" |
default |
$theme-table-header-text-color |
"ink" |
default |
$theme-table-stripe-text-color |
"ink" |
default |
$theme-table-text-color |
"ink" |
default |
What to do
- Check your settings to see if they are set to either the old or the new default.
- If they use either the old or the new default, delete the setting from your settings file so it uses the system default.
Settings Check two settings with changed defaults.
If you use any of these settings in your code, the output may change:
Setting | Old default | New default |
---|---|---|
$theme-breadcrumb-background-color |
"white" |
default |
$theme-alert-icon-size |
4 |
5 |
What to do
- Check your settings to see if they are set to either the old or the new default.
- If they use either the old or the new default, delete the setting from your settings file so it uses the system default.
Markup Update footer logo headings to use proper semantics.
We improved the accessibility of the footer by converting a non-semantic heading into paragraph text.
What to do
- Look for
<h3 class="usa-footer__logo-heading">
in your footer markup. - Replace the
h3
in this markup with ap
for both the opening and closing tags.
5. Update to Sass module syntax
While USWDS 3.0 supports the deprecated @import
Sass syntax, we recommend upgrading to the new Sass module syntax when updating to USWDS 3.0.
These instructions will help you update your @import
references to the new syntax, format and load your USWDS settings, and use the new uswds-core
package to access USWDS functions, mixins, tokens, and variables in your custom Sass.
Update your @import references
- Replace all instances of @import with @forward in your Sass entry point.
- @import "uswds-theme-color";
+ @forward "uswds-theme-color";
- @import "uswds-theme-general";
+ @forward "uswds-theme-general";
- @import "uswds-theme-spacing";
+ @forward "uswds-theme-spacing";
- @import "uswds-theme-typography";
+ @forward "uswds-theme-typography";
- @import "uswds-theme-utilities";
+ @forward "uswds-theme-utilities";
- @import "uswds-theme-components";
+ @forward "uswds-theme-components";
- @import "uswds";
+ @forward "uswds";
- @import "uswds-custom-styles";
+ @forward "uswds-custom-styles";
Format and load your USWDS settings
- Locate your existing project theme files. These are the
_uswds-theme
files that you found in Step 1: Check your current USWDS code and settings versions, above. - Create a new project-specific theme settings file. If your project already has a single project-specific theme settings file, you’re all set. If not, create a new file in your project theme file directory called
_uswds-theme.scss
. -
Find which theme settings you’ve customized. Comparing your theme files to the default theme should reveal which of these settings you’ve modified. We recommend accomplishing this with a series of diffs against the default theme files.
The bad thing about this process is that it can be tedious. The good thing is that you only have to do it once, and then you’ll have a small, manageable project theme file that can be your baseline moving forward. And you’ll never again have to worry about overwriting your settings files when you update to a new version of the design system.
We recommend an online diff service like quickdiff.net, diffchecker.com, or text-compare.com.
Each of the files below is from version 2.13.3 of the USWDS default settings. For each of these files, use the diff tool to find the differences between your settings file and the current (USWDS Version 3.x) defaults.
USWDS Version 2.13.3 Defaults
- Color settings
- Component settings
- General settings
- Spacing settings
- Typography settings
- Utilities settings
When you compare earlier versions of the Design System to USWDS Version 3.x, look for instances where your project has a different value than the default. Ignore cases where a setting exists in the current version but not in your version. This indicates a new setting that probably does not apply to your project. Instances where a setting exists in your version but not in the current version can likely be ignored. This usually indicates a deprecated setting that should not affect your project, but it can be worth checking to see if that variable appears anywhere else in your codebase.
When you see a setting that appears different from the current default, this is probably one of your project’s custom settings. Copy this setting and add it to your new
_uswds-theme.scss
file.At the end of this process, your new
_uswds-theme.scss
file will look something like the following:$theme-image-path: "../uswds/img"; $theme-font-path: "../uswds/fonts"; $theme-show-compile-warnings: false; $theme-show-notifications: false; $theme-focus-color: "blue-50v"; $theme-global-paragraph-styles: true; $theme-global-link-styles: true; $theme-global-content-styles: true; $theme-utility-breakpoints: ( "card": false, "card-lg": true, "mobile": true, "mobile-lg": true, "tablet": true, "tablet-lg": true, "desktop": true, "desktop-lg": true, "widescreen": true );
-
Load these customizations into USWDS core. Once you have all your project-specific settings in a single file, we’ll load these customizations into the special
uswds-core
package that powers the design system. We do this with a special@use ... with
statement:@use "uswds-core" with ( {{ your settings }} );
In the previous example,
{{ your settings }}
would be a list of all the USWDS settings variables in your settings file.So with an existing settings file like the following:
$theme-image-path: "../uswds/img"; $theme-font-path: "../uswds/fonts"; $theme-show-compile-warnings: false; $theme-show-notifications: false; $theme-focus-color: "blue-50v"; $theme-global-paragraph-styles: true; $theme-global-link-styles: true; $theme-global-content-styles: true; $theme-utility-breakpoints: ( "card": false, "card-lg": true, "mobile": true, "mobile-lg": true, "tablet": true, "tablet-lg": true, "desktop": true, "desktop-lg": true, "widescreen": true );
We’d update it to use
@use
with the following:@use "uswds-core" with ( $theme-image-path: "../uswds/img", $theme-font-path: "../uswds/fonts", $theme-show-compile-warnings: false, $theme-show-notifications: false, $theme-focus-color: "blue-50v", $theme-global-paragraph-styles: true, $theme-global-link-styles: true, $theme-global-content-styles: true, $theme-utility-breakpoints: ( "card": false, "card-lg": true, "mobile": true, "mobile-lg": true, "tablet": true, "tablet-lg": true, "desktop": true, "desktop-lg": true, "widescreen": true ), );
Note that the new
@use
statement is a list of variables, so each line ends in a comma,
instead of a semicolon;
.Note: the
@use "uswds-core" with ()
configuration accepts only current USWDS settings variables. If you receive the errorThis module was already loaded, so it can't be configured using "with"
, confirm that all your declared variables exist in the in the list of USWDS settings and try compiling again. -
Use the new theme file in your project If your project already was using a project-specific theme settings file, you’re all set. If not, you’ll need to open your project’s Sass entry point, typically
styles.scss
. It usually looks something like this:/* * * * * * ============================== * * * * * ============================== * * * * * ============================== * * * * * ============================== ======================================== ======================================== ======================================== */ // ------------------------------------- // Import individual theme settings @forward "uswds-theme-general"; @forward "uswds-theme-typography"; @forward "uswds-theme-spacing"; @forward "uswds-theme-color"; @forward "uswds-theme-utilities"; // components import needs to be last @forward "uswds-theme-components"; @forward "uswds"; @forward "uswds-custom-styles";
We can remove all the individual theme settings from our Sass entry point and replace them with a single
@forward
statement, using the project-specific settings file that we just created, like so:
- // Import individual theme settings
- @forward "uswds-theme-general";
- @forward "uswds-theme-typography";
- @forward "uswds-theme-spacing";
- @forward "uswds-theme-color";
- @forward "uswds-theme-utilities";
- // components import needs to be last
- @forward "uswds-theme-components";
+ @forward "uswds-theme";
@forward "uswds";
@forward "uswds-custom-styles";
Now your project is using its theme settings in the proper USWDS 3.0 format! You can safely remove the old theme files from your project.
Use “uswds-core” for any custom USWDS Sass
Unlike @import
, which makes Sass members (tokens, variables, mixins, functions, or placeholders) available globally, @use
only reveals Sass members to the stylesheet that loads them.
Accommodating this is relatively straightforward for USWDS 3.0: For any project stylesheet that uses USWDS members (that’s probably most, if not all, of them!), you’ll need to load uswds-core
at the top of your stylesheet. You will also need to check if you have non-USWDS modules in your stylesheet and load those as well. Here is how to do it:
- Load “uswds-core” at the top of any stylesheet that uses USWDS members.
/* custom stylesheet */ @use "uswds-core" as *;
In USWDS 3.0,
uswds-core
is the name of the package (or “module” in Sass terminology) that contains all the members used in USWDS Sass. Loading this package makes all of these members available to your stylesheet.In this step, we add
as *
to our@use
statement to indicate that we don’t want any namespacing attached to USWDS members. By default, Sass members brought in via@use
are namespaced using the basename of the file url. For example, if we were to use the the default load pattern@use "uswds-color
, ourcolor()
function would need to be called withuswds-core.color()
. Removing namespacing enables us to use the same member references that we used with the older@import
syntax.For more information on controlling namespacing, read the Sass documentation on namespacing.
-
Check if your project uses members defined outside of USWDS. This includes searching for references to Sass’ built-in modules. If it does, you’ll need to include these as well via
@use
at the top of the document.As an example, your stylesheet might contain the following lines at the top:
/* custom stylesheet */ @use "sass:math"; @use "sass:list"; @use "sass:color"; @use "uswds-core" as *;
Once each of your custom Sass files loads the required modules, you should be done!
- Recompile your Sass and check for errors.
6. Optimize your installation
Upgrading to USWDS 3.0 introduces many opportunities to improve the performance of your project. While none of the steps listed below are necessary to make USWDS 3.0 work, completing these items will likely show significant improvements in both file size and compilation times for your project.
Using component packages
By default, a USWDS installation includes every component available to the design system. But most projects don’t use all these components. USWDS 3.0 allows you to use only the components you need for your project, via component packages.
A component package is a self-contained module that includes only code related to a specific component. In addition to an omnibus uswds
package, USWDS 3.0 includes packages for every component available in the design system, and for some features (like fonts) that are common to many components. (A full list of the packages available in USWDS 3.0 is included in the table below.)
Using individual component packages instead of the uswds
bundle package can result in a significant reduction in the size of your project CSS and noticeable improvements to compile time. Complete the following steps to load component packages in your project:
-
Determine if your project is using the
uswds
package bundle. By default, USWDS projects load theuswds
package to include all the styles available to the design system. You will see a line like the following in your Sass entry point when you’re using theuswds
package:@forward "uswds";
If you are using the
uswds
package and want to use component packages instead, proceed to the next step. -
Determine which packages your project needs. The process of determining which packages your project needs is not automatic. Most projects will need to do a little work to identify the components their project uses.
A brute-force method to determine which packages your project uses is to search your codebase for use of a key class name associated with that component, like
usa-accordion
for accordions. Allusa-
prefixed packages use the same name as their CSS class. For reference, all the available packages in USWDS 3.0 are listed in the table below. Search package-by-package for instances of the package or search your codebase for instances ofusa-
and make a running list of all the packages you use. -
Load the your project’s necessary component packages in your Sass entry point. If you find a hit for the class name in your codebase, include the relevant package in your Sass entry point.
For instance, if you found
usa-banner
,usa-identifier
,usa-button
, andusa-accordion
, you might attach the following packages in your Sass entry point:@forward "usa-accordion"; @forward "usa-banner"; @forward "usa-button"; @forward "usa-identifier";
Each package is smart enough to include any dependent package it needs to display properly.
-
Many projects will need to use the utilities package (
uswds-utilities
) and the global package (uswds-global
). If your site uses utilities, be sure to include the utilites package. The global package includes normalize. If you compile your styles and see improper spacing around many elements (like around the perimeter of the page), be sure to includeuswds-global
. -
Remove your reference to the uswds bundle package. Once all of your project’s component packages are loaded, you can safely remove the
uswds
package reference from your entry point.- @forward "uswds"; + @forward "usa-accordion"; + @forward "usa-banner"; + @forward "usa-button"; + @forward "usa-identifier";
Available packages
The following packages are available to any USWDS project. Each package includes component styles related to the package name, and additional styles related to any component dependencies.
For any package listed below, add a @forward "[package]"
line to your Sass entry point. For instance, if you wanted to add the usa-accordion
package, add the following line:
@forward "usa-accordion";
Package name | Gzip size | Full size | Source size | Dependencies |
---|---|---|---|---|
usa-accordion | 1.85 KB | 10 KB | 3 KB | usa-icon, uswds-fonts |
usa-alert | 2.405 KB | 13 KB | 7 KB | usa-icon, uswds-fonts |
usa-banner | 5.92 KB | 32 KB | 7 KB | usa-media-block, uswds-fonts |
usa-breadcrumb | 2.22 KB | 12 KB | 6 KB | usa-icon, uswds-fonts |
usa-button | 2.96 KB | 16 KB | 9 KB | uswds-fonts |
usa-button-group | 3.33 KB | 18 KB | 3 KB | usa-button |
usa-card | 2.035 KB | 11 KB | 5 KB | uswds-fonts |
usa-character-count | 0.185 KB | 1 KB | 0.2 KB | uswds-core |
usa-checkbox | 1.85 KB | 10 KB | 3 KB | usa-fieldset, usa-input-list, usa-legend, uswds-fonts |
usa-checklist | 1.295 KB | 7 KB | 0.7 KB | usa-icon, uswds-fonts |
usa-collection | 1.665 KB | 9 KB | 3 KB | uswds-fonts |
usa-combo-box | 1.85 KB | 10 KB | 3 KB | usa-icon, usa-select |
usa-content | 0.037 KB | 0.2 KB | 0.2 KB | uswds-core |
usa-dark-background | 0.074 KB | 0.4 KB | 0.4 KB | uswds-core |
usa-date-picker | 3.145 KB | 17 KB | 10 KB | usa-icon, usa-input, uswds-fonts |
usa-date-range-picker | 3.145 KB | 17 KB | 0 KB | usa-date-picker |
usa-display | 1.295 KB | 7 KB | 0.8 KB | uswds-fonts |
usa-embed-container | 0.0555 KB | 0.3 KB | 0.3 KB | uswds-core |
usa-error-message | 1.11 KB | 6 KB | 0.1 KB | uswds-fonts |
usa-fieldset | 1.295 KB | 7 KB | 0.2 KB | usa-input, uswds-fonts |
usa-file-input | 1.85 KB | 10 KB | 4 KB | uswds-fonts |
usa-footer | 7.955 KB | 43 KB | 7 KB | usa-button, usa-form, usa-icon, usa-input, usa-label, usa-layout-grid, usa-list, uswds-fonts |
usa-form | 1.48 KB | 8 KB | 1 KB | uswds-fonts |
usa-form-group | 1.11 KB | 6 KB | 1 KB | uswds-fonts |
usa-graphic-list | 4.625 KB | 25 KB | 0.9 KB | usa-layout-grid, uswds-fonts |
usa-header | 6.845 KB | 37 KB | 6 KB | usa-accordion, usa-button, usa-nav, usa-search, usa-skipnav, uswds-fonts, uswds-helpers |
usa-hero | 4.625 KB | 25 KB | 0.7 KB | usa-layout-grid, uswds-fonts |
usa-hint | 1.295 KB | 7 KB | 0.2 KB | usa-input, uswds-fonts |
usa-icon | 0.074 KB | 0.4 KB | 0.4 KB | uswds-core |
usa-icon-list | 4.07 KB | 22 KB | 16 KB | usa-input, uswds-fonts |
usa-identifier | 1.665 KB | 9 KB | 3 KB | uswds-core, uswds-fonts |
usa-input | 1.295 KB | 7 KB | 0.5 KB | uswds-fonts |
usa-input-prefix-suffix | 1.48 KB | 8 KB | 1 KB | usa-icon, usa-input |
usa-intro | 1.11 KB | 6 KB | 0.2 KB | uswds-fonts |
usa-label | 1.11 KB | 6 KB | 0.3 KB | uswds-fonts |
usa-layout-docs | 0.037 KB | 0.2 KB | 0.2 KB | uswds-core |
usa-layout-grid | 3.33 KB | 18 KB | 18 KB | uswds-core |
usa-legend | 1.11 KB | 6 KB | 0.3 KB | uswds-fonts |
usa-link | 1.48 KB | 8 KB | 1 KB | usa-icon, uswds-fonts |
usa-list | 0.0925 KB | 0.5 KB | 0.5 KB | — |
usa-media-block | 0.0185 KB | 0.1 KB | 0.1 KB | — |
usa-memorable-date | 1.295 KB | 7 KB | 0.6 KB | usa-form-group, usa-input, uswds-fonts |
usa-modal | 3.33 KB | 18 KB | 3 KB | usa-button, uswds-fonts |
usa-nav | 5.55 KB | 30 KB | 9 KB | usa-accordion, usa-icon, usa-search, uswds-fonts |
usa-pagination | 1.48 KB | 8 KB | 2 KB | uswds-fonts |
usa-paragraph | 0.037 KB | 0.2 KB | 0.2 KB | uswds-core |
usa-process-list | 1.48 KB | 8 KB | 2 KB | uswds-fonts |
usa-prose | 4.44 KB | 24 KB | 18 KB | uswds-fonts |
usa-radio | 1.48 KB | 8 KB | 1 KB | usa-fieldset, usa-input-list, usa-legend, uswds-fonts |
usa-range | 1.48 KB | 8 KB | 2 KB | usa-label, uswds-fonts |
usa-search | 3.33 KB | 18 KB | 1 KB | usa-button, usa-icon, usa-input, uswds-fonts, uswds-helpers |
usa-section | 0.111 KB | 0.6 KB | 0.6 KB | uswds-core |
usa-select | 1.48 KB | 8 KB | 1 KB | usa-icon, usa-input, uswds-fonts |
usa-sidenav | 1.48 KB | 8 KB | 2 KB | uswds-fonts |
usa-site-alert | 3.145 KB | 17 KB | 4 KB | usa-alert |
usa-site-title | 0.0 KB | 0 KB | 0 KB | — |
usa-skipnav | 1.295 KB | 7 KB | 0.6 KB | uswds-fonts |
usa-step-indicator | 2.22 KB | 12 KB | 6 KB | uswds-fonts, uswds-helpers |
usa-summary-box | 1.295 KB | 7 KB | 0.9 KB | usa-list, uswds-fonts |
usa-table | 3.885 KB | 21 KB | 15 KB | uswds-fonts |
usa-tag | 1.295 KB | 7 KB | 1 KB | uswds-fonts |
usa-textarea | 1.295 KB | 7 KB | 0.5 KB | uswds-fonts |
usa-time-picker | 1.295 KB | 7 KB | 0.1 KB | usa-hint, usa-input, usa-label, uswds-fonts |
usa-tooltip | 1.295 KB | 7 KB | 1 KB | uswds-fonts |
usa-validation | 4.81 KB | 26 KB | 0 KB | usa-alert, usa-button, usa-checklist, usa-fieldset, usa-form, usa-input, usa-label, usa-legend |
uswds | 72.89 KB | 394 KB | 0 KB | — |
uswds-core | 0.0 KB | 0 KB | 0 KB | — |
uswds-elements | 0.1295 KB | 0.7 KB | 0.7 KB | — |
uswds-fonts | 1.11 KB | 6 KB | 6 KB | — |
uswds-form-controls | 6.105 KB | 33 KB | 0 KB | usa-character-count, usa-checkbox, usa-combo-box, usa-date-picker, usa-error-message, usa-fieldset, usa-file-input, usa-form, usa-form-group, usa-hint, usa-input, usa-input-prefix-suffix, usa-label, usa-legend, usa-memorable-date, usa-radio, usa-range, usa-select, usa-textarea, usa-time-picker |
uswds-global | 1.665 KB | 9 KB | 0 KB | normalize, uswds-core, uswds-elements, uswds-fonts, uswds-helpers |
uswds-helpers | 0.037 KB | 0.2 KB | 0.2 KB | sr-only, usa-focus |
uswds-typography | 4.995 KB | 27 KB | 0 KB | usa-content, usa-dark-background, usa-display, usa-intro, usa-link, usa-list, usa-paragraph, usa-prose |
uswds-utilities | 36.63 KB | 198 KB | 198 KB | — |
Managing utility classes
Utility classes have their own naming conventions that are a bit less straightforward to identify. Look at the table below. If your codebase includes classes that start with one of the class bases, include its utility module name in the $output-these-utilities setting
.
Look for classes in your codebase for searching for a regular expression string like [" ]flex-
.
For instance, if you found add-list-reset
, font-
, order-
, and display-
, you might use the following setting:
$output-these-utilities: (
"add-list-reset",
"display",
"font",
"order"
),
Utility module name | Class base | Gzip size | Default full size |
---|---|---|---|
add-aspect | add-aspect- | 0.08 KB | 0.44 KB |
add-list-reset | add-list-reset | 0.02 KB | 0.12 KB |
align-items | flex- | 0.04 KB | 0.24 KB |
align-self | flex- | 0.06 KB | 0.31 KB |
background-color | bg- | 1.0 KB | 5.4 KB |
border | border- | 4.35 KB | 23.5 KB |
border-color | border- | 4.35 KB | 23.5 KB |
border-radius | border- | 1.61 KB | 8.7 KB |
border-style | border- | 0.03 KB | 0.14 KB |
border-width | border- | 0.56 KB | 3 KB |
bottom | bottom- | 0.18 KB | 0.96 KB |
box-shadow | shadow- | 0.06 KB | 0.33 KB |
circle | circle- | 0.19 KB | 1 KB |
clearfix | clearfix | 0.02 KB | 0.09 KB |
color | text- | 0.37 KB | 2 KB |
cursor | cursor- | 0.07 KB | 0.39 KB |
display | display- | 0.28 KB | 1.5 KB |
flex | flex- | 0.06 KB | 0.33 KB |
flex-direction | flex- | 0.02 KB | 0.1 KB |
flex-wrap | flex- | 0.02 KB | 0.1 KB |
float | float- | 0.02 KB | 0.1 KB |
font | font- | 2.41 KB | 13 KB |
font-family | font-family- | 0.37 KB | 2 KB |
font-feature | text- | 0.03 KB | 0.14 KB |
font-style | text- | 0.02 KB | 0.11 KB |
font-weight | text- | 0.1 KB | 0.54 KB |
height | height- | 0.11 KB | 0.6 KB |
justify-content | flex- | 0.18 KB | 0.95 KB |
left | left- | 0.08 KB | 0.44 KB |
letter-spacing | text-ls- | 0.05 KB | 0.28 KB |
line-height | line-height- | 1.61 KB | 8.7 KB |
margin | margin- | 0.8 KB | 4.35 KB |
margin-horizontal | margin- | 4.02 KB | 21.75 KB |
margin-vertical | margin- | 4.02 KB | 21.75 KB |
max-height | maxh- | 0.12 KB | 0.65 KB |
max-width | maxw- | 0.13 KB | 0.72 KB |
measure | measure- | 0.18 KB | 0.98 KB |
min-height | minh- | 0.13 KB | 0.72 KB |
min-width | minw- | 0.07 KB | 0.4 KB |
opacity | opacity- | 0.24 KB | 1.3 KB |
order | order- | 0.26 KB | 1.4 KB |
outline | outline- | 0.03 KB | 0.18 KB |
outline-color | outline- | 0.56 KB | 3 KB |
overflow | overflow- | 0.09 KB | 0.46 KB |
padding | padding- | 4.02 KB | 21.75 KB |
pin | pin- | 0.06 KB | 0.35 KB |
position | position- | 0.04 KB | 0.21 KB |
right | right- | 0.09 KB | 0.47 KB |
square | square- | 0.14 KB | 0.73 KB |
text-align | text- | 0.03 KB | 0.16 KB |
text-decoration | underline- | 0.06 KB | 0.32 KB |
text-decoration-color | text- | 2.33 KB | 12.6 KB |
text-indent | text-indent- | 0.19 KB | 1 KB |
text-transform | text- | 0.04 KB | 0.2 KB |
top | top- | 0.07 KB | 0.4 KB |
vertical-align | text- | 0.06 KB | 0.32 KB |
whitespace | text- | 0.04 KB | 0.2 KB |
width | width- | 0.56 KB | 3 KB |
z-index | z- | 0.04 KB | 0.22 KB |
Update to the sass-embedded compiler
The sass-embedded
package compiles Sass faster than the gulp-sass
oder gulp-dart-sass
compiler.
In a gulp workflow, we recommend using gulp-sass
and sass-embedded
together for the simplest and fastest compiling.
- Install
gulp-sass
andsass-embedded
in your project:npm install gulp-sass sass-embedded –s
-
Uninstall any other sass compiling packages, if they exist:
npm uninstall sass npm uninstall gulp-dart-sass
- In your Sass gulp tasks file, replace your existing sass compiler package import with
gulp-sass
andsass-embedded
:- const sass = require("gulp-dart-scss"); + const sass = require("gulp-sass")(require("sass-embedded"));
- In your Sass gulp tasks file, remove any line that sets the sass.compiler:
- sass.compiler = require("sass");
- Recompile.
Reduce utility responsive breakpoints
There are nine responsive breakpoints available to utilities and the layout grid. These are defined in the $theme-utility-breakpoints setting
. If a utility breakpoint is set to true
, any layout grid class and any utility with its responsive key set to true will output responsive classes.
This can result in bulky CSS, and if your project doesn’t use these breakpoints you can save a lot of space by setting these breakpoints to false. By default, mobile-lg
, tablet
, and desktop
are set to true:
$theme-utility-breakpoints: (
"card": false,
"card-lg": false,
"mobile": false,
"mobile-lg": true,
"tablet": true,
"tablet-lg": false,
"desktop": true,
"desktop-lg": false,
"widescreen": false
),
For each breakpoint set to true in your project, search for its usage in your codebase by searching for the breakpoint name + a colon (:
). So, to search for the tablet-lg
breakpoint, search for tablet-lg:
. If that breakpoint does not appear, you can set the value to false
.
Using package source
Once you’ve optimized your project to use only the component packages you need, you can further optimize those packages. Each component package includes, by reference, code for any additional packages it depends on. You can improve performance by manually forwarding all your project component’s dependencies, then pointing your Sass entry point directly at each package source, bypassing each package’s dependency import.
For example, according to the table in Available packages, above, the usa-banner
component includes the following packages as dependencies: usa-icon
, usa-layout-grid
, usa-media-block
, and uswds-fonts
. Then we’ll look at these dependencies’ dependencies:
usa-icon
depends onuswds-core
usa-layout-grid
depends onuswds-core
usa-media-block
depends onusa-layout-grid
anduswds-fonts
uswds-fonts
depends onuswds-core
Instead of simply forwarding the usa-banner
component, you can import the component and all related dependencies directly. Note: We’ve used uswds-core
already when we forwarded our settings, so we won’t forward it again:
// Instead of...
@forward "usa-banner";
// Import the component and all related dependencies
@forward "usa-banner";
@forward "usa-layout-grid";
@forward "usa-media-block";
@forward "uswds-fonts";
Now, instead of pointing at the component packages, we can point directly at the component package source. For each usa-
prefixed component package, append /src/styles
to its name:
@forward "usa-banner/src/styles";
@forward "usa-layout-grid/src/styles";
@forward "usa-media-block/src/styles";
@forward "uswds-fonts";
When you recompile, you should see an improvement in compile time.
Note: This performance technique may cause issues when you update USWDS versions. Check the release notes for any new version to see if we’ve changed any package’s dependencies, which we will indicate as a potential breaking change.
Latest updates
Meaningful code and guidance updates are listed in the following table:
Date | Description |
---|---|
2024-06-07 |
Added note about Autoprefixer to Sass compilation section. More information: uswds-site#2319 |
2022-07-17 |
Added note about error handling for |
2022-08-29 |
Added instructions for users migrating from USWDS 1.x. More information: uswds-site#1739 |
2022-05-04 |
Added clarity to migration page. More information: uswds-site#1583 |
2022-04-28 |
Added “Migrating to USWDS 3.0” guide. More information: uswds-site#1538 |