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"); or const 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 and gulp-sass packages if you're using them. If you use the sass 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 of gulp-sass. Replace any instance of sass.sync with simply sass:
```
- sass.sync({
+ sass({
```
If you use sass and gulp-sass, you'll need to update how they work together. Update your const sass to const 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 the includePaths and gulp.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 uses USWDS instead of uswds, 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 is gulpfile.js).
Update the gulpfile.js to include a uswds.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 and src() found in your project’s gulp files. These paths tell the Sass compiler where to look for USWDS source files. The includePaths section may look like the following:
```
 .pipe(
   sass({
     includePaths: [
       PROJECT_SASS_SRC,
       `${USWDS}`,
       `${USWDS}/uswds/packages`,
     ],
   })
 )
```
Make sure includePaths includes node_modules/@uswds/uswds/packages in its array.
Update any src() references to point to the correct node_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
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 each module 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>

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.

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

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

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

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 a p 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
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 error This 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, our color() function would need to be called with uswds-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 the uswds 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 the uswds 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. All usa- 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 of usa- 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, and usa-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 include uswds-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 or 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 and sass-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 and sass-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 on uswds-core
usa-layout-grid depends on uswds-core
usa-media-block depends on usa-layout-grid and uswds-fonts
uswds-fonts depends on uswds-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 `@use "uswds-core" with ()`. More information: uswds-site#1698
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

Why migrate to USWDS 3.0?

USWDS 3.0 package overview

Migration overview

1. Check your current USWDS code and settings versions

2. Install the USWDS 3.0 package

3. Update your Sass compiler settings and recompile CSS

If you're using USWDS Gulp

If you're using USWDS Compile

If you're using a custom gulp workflow

If you're using webpack

4. Integrate any recent USWDS changes

All migrations

Settings Remove $output-all-utilities setting.

What to do

If you have code older than USWDS 2.13.0

Markup Update any instance of the small search button.

What to do

Old code

New code

Markup Update social media icons in the footer.

What to do

Old code

New code

If you have code older than USWDS 2.12.0

Settings Update three deprecated settings.

What to do

Settings Check three settings with changed defaults.

What to do

If you have code older than USWDS 2.11.2

Settings Replace the deprecated $theme-site-max-width variable.

What to do

Markup Replace the thumb_down_off_alt icon with thumb_down_alt icon.

What to do

If you have code older than USWDS 2.11.0

Settings Check five settings with changed defaults.

What to do

If you have code older than USWDS 2.10.1

Settings Check two settings with changed defaults.

What to do

Markup Update footer logo headings to use proper semantics.

What to do

5. Update to Sass module syntax

Update your @import references

Format and load your USWDS settings

Use “uswds-core” for any custom USWDS Sass

6. Optimize your installation

Using component packages

Available packages

Managing utility classes

Update to the sass-embedded compiler

Reduce utility responsive breakpoints

Using package source

Latest updates

Settings Replace the deprecated `$theme-site-max-width` variable.

Markup Replace the `thumb_down_off_alt` icon with `thumb_down_alt` icon.