How to use USWDS

Phase 2: Compile

Compile Design System source code into browser-readable files.

U.S. Web Design System source code is written in Sass, a powerful stylesheet language that builds automation, functions, and logic into CSS. Browsers can’t read native Sass files, so these files need to be compiled into CSS — usually a single CSS file — before we can use them. Basically, when you develop with the Design System, you do all your stylesheet work in Sass then use a compiler to convert that Sass into CSS.

Introducing uswds-compile

We recommend using uswds-compile, a USWDS tool hosted on GitHub, as a quick way to get up and running with Sass compilation for USWDS.

This tool provides simple Gulp functions that copy USWDS static assets into your project and transform USWDS Sass into browser-readable CSS. Additionally, uswds-compile applies Autoprefixer to all compiled code to make sure your CSS is browser-compatible.

Later in this guide we will walk you through setting up Sass compilation for your project with uswds-compile. To get started, jump ahead to the Using uswds-compile section below.

Loading USWDS Sass with a custom compiler

If you already have Sass compilation set up on your project, you’ll need to load USWDS Sass and your USWDS settings configuration into your Sass entry point.

About Sass entry points

A project often has many Sass files, but typically, there’s a single file that serves as the root — the “homepage” of the Sass — that links out to the others. This root file is also known as the “Sass entry point.” The Sass entry point is the most important stylesheet file in your project because it tells the compiler what source files make up your Sass codebase. Often, a project’s Sass entry point is named something like index.scss or styles.scss.

Creating a Sass entry point

If your project does not yet have a Sass entry point, create a file called index.scss or styles.scss. This file will typically live at the root of your project’s Sass directory.

Loading USWDS in your Sass entry point

Your project’s Sass entry point is a simple file that will need to:

Load your project’s USWDS settings configuration (required)
Load USWDS source code (required)
Load your project’s custom Sass (optional)

For your entry point to complete these tasks, you will need to add the following references to your entry point in this order:

/* styles.scss */

// 1. Load your project's USWDS settings configuration
@forward "uswds-theme.scss";

// 2. Load USWDS source code
@forward "./path/to/source/uswds";

// 3. Load your project's custom Sass
@forward "project-styles.scss";

Note that each @forward reference in this example is tied to one of the tasks listed above.

In plain language, this code says:

Get the instructions: Add the USWDS settings configuration that tells the Design System how to build the styles.

Your settings configuration is the first thing you’ll need to include in your entry point. Often, this configuration will live in its own file, which in this example is called uswds-theme.scss. You can find full instructions for configuring USWDS settings, along with a list of all available settings, on the Settings page.
Create the foundation: Build all USWDS styles from these settings.

Once you have set up your project’s custom settings, it is time to pull in the USWDS source code from the uswds package.

The uswds package collects all the Sass in the Design System. It contains all the styles for USWDS components as well as the design language of Sass tokens and functions used to build those components.

To load the uswds package, you must provide a path to its index.scss entry point. If you installed USWDS 3 with npm, the complete path to this file is: ./node_modules/@uswds/uswds/packages/uswds/_index.scss.
Build new work on top of that foundation: Finally, add any custom project styles built from Design System code.

After you’ve loaded the USWDS source code, you can build new styles with USWDS design tokens, functions, and mixins. For the purposes of this guide, we won’t get into custom code, but the important thing to understand is that any custom code should follow the settings configuration and USWDS source code in your Sass entry point.

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.

Using uswds-compile

Complete the following steps to install, configure, and use uswds-compile:

Step 1: Install uswds-compile

From your project’s root, run the following command to install uswds-compile:

npm install @uswds/compile --save-dev

Step 2: Create a gulpfile

If your project does not yet have a gulpfile.js file, create one at the root of your project by running this command:

touch gulpfile.js

This file will need to do the following:

Import the @uswds/compile package
Set the project’s USWDS version
Set custom project path settings
Export the Gulp functions and/or tasks you need

As an example, a simple gulpfile.js may read as follows:

/* gulpfile.js */

/**
* Import uswds-compile
*/
const uswds = require("@uswds/compile");

/**
* USWDS version
* Set the major version of USWDS you're using
* (Current options are the numbers 2 or 3)
*/
uswds.settings.version = 3;

/**
* Path settings
* Set as many as you need
*/
uswds.paths.dist.css = './assets/css';
uswds.paths.dist.theme = './sass/uswds';

/**
* Exports
* Add as many as you need
*/
exports.init = uswds.init;
exports.compile = uswds.compile;
exports.watch = uswds.watch;

Step 3: Import the uswds-compile package

Once your gulpfile.js is created, add the following line at the top of the file to pull in uswds-compile:

const uswds = require("@uswds/compile");

Step 4: Set USWDS version

Next, declare which major version of USWDS your project uses by defining settings.version. This configuration tells Gulp where to find USWDS source files in the node_modules directory. This setting currently accepts values of the numbers 2 and 3 to represent USWDS 2.X and 3.X, respectively.

For example, you would include this line if your project uses USWDS 3:

uswds.settings.version = 3;

Step 5: Customize path settings

Next, you will need to determine if there are any path settings that you’ll need to customize.

uswds-compile provides default paths that tell Gulp both where to find USWDS source files and where to distribute assets in your project. A list of all path settings, along with default values, can be found in the following table:

Setting	Default values - Version 2.x	Default values - Version 3.0	Description
`paths.src.uswds`	`"./node_modules/uswds/dist"`	`"./node_modules/@uswds"`	Source location of the `uswds` package
`paths.src.sass`	`"./node_modules/uswds/dist/scss"`	`"./node_modules/@uswds/uswds/packages"`	Source location of the USWDS Sass
`paths.src.theme`	`"./node_modules/uswds/dist/scss/theme"`	`"./node_modules/@uswds/uswds/dist/theme"`	Source location of the USWDS theme files (Sass entry point and starter settings files)
`paths.src.fonts`	`"./node_modules/uswds/dist/fonts"`	`"./node_modules/@uswds/uswds/dist/fonts"`	Source location of the USWDS fonts
`paths.src.img`	`"./node_modules/uswds/dist/img"`	`"./node_modules/@uswds/uswds/dist/img"`	Source location of the USWDS images
`paths.src.js`	`"./node_modules/uswds/dist/js"`	`"./node_modules/@uswds/uswds/dist/js"`	Source location of the USWDS compiled JavaScript files
`paths.src.projectSass`	`"./sass"`	`"./sass"`	Source location of any existing project Sass files outside of `paths.dist.theme`. The `watch` script will watch this directory for changes.
`paths.src.projectIcons`	`""`	`""`	Source location of any additional project icons to include in the icon sprite. (Use only these project icons in the sprite by setting `sprite.projectIconsOnly` to `true`.)
`paths.dist.theme`	`"./sass"`	`"./sass"`	Project destination for theme files (Sass entry point and settings)
`paths.dist.img`	`"./assets/uswds/images"`	`"./assets/uswds/images"`	Project destination for images
`paths.dist.fonts`	`"./assets/uswds/fonts"`	`"./assets/uswds/fonts"`	Project destination for fonts
`paths.dist.js`	`"./assets/uswds/js"`	`"./assets/uswds/js"`	Project destination for compiled JavaScript
`paths.dist.css`	`"./assets/uswds/css"`	`"./assets/uswds/css"`	Project destination for compiled CSS
`sprite.projectIconsOnly`	`false`	`false`	Include only the icons in `paths.src.projectIcons` in the icon sprite
`settings.compile.browserslist`	`["> 2%", "last 2 versions", "IE 11", "not dead"]`	`["> 2%", "last 2 versions", "IE 11", "not dead"]`	Define the browserslist query for CSS prefixes generated by autoprefixer.
`settings.compile.sassSourcemaps`	`true`	`true`	Include sourcemap when compiling SASS to CSS.
`settings.compile.sassDeprecationWarnings`	`false`	`false`	Show USWDS Sass deprecation warnings. When set to `true`, Sass will output deprecation warnings for USWDS code in the terminal during compilation. Deprecation warnings for non-USWDS Sass will output even when this value is set to `false`.

paths.src: The paths.src settings tell Gulp where to find USWDS source files. The default values point to directories in the uswds node module that you installed during Phase 1 of this guide.

Note that the paths.src defaults are different for USWDS 2 and USWDS 3. uswds-compile chooses which set of defaults to use based on the USWDS version defined in settings.version in step 4.

paths.dist: The paths.dist settings tell Gulp where to put assets in your project.

For example, if you wanted to tell Gulp to compile CSS into your project’s ./assets/css directory and also copy USWDS theme files into your project’s ./sass/uswds directory, you’d include these lines in your gulpfile.js:

uswds.paths.dist.css = './assets/css';
uswds.paths.dist.theme = './sass/uswds';

One helpful way to look at these path settings is that the paths.src settings are specific to the Design System; the paths.dist settings are specific to your project.

Step 6: Export compile functions

Once your paths are set, export uswds-compile functions in your project’s gulpfile.js to use them in your project. The following table summarizes the functions that are available for export:

Function	Description
`compile`	`compileSass` + `compileIcons`
`compileIcons`	Build the USWDS icon sprite into `paths.dist.img`
`compileSass`	Compile Sass into `paths.dist.css`
`default`	`watch`
`copyAll`	`copyTheme` + `copyAssets`
`copyAssets`	Copies all static assets: `copyFonts` + `copyImages` + `copyJS`
`copyFonts`	Copy USWDS fonts to `paths.dist.fonts`
`copyImages`	Copy USWDS images to `paths.dist.img`
`copyJS`	Copy USWDS compiled JavaScript to `paths.dist.js`
`copyTheme`	Copy USWDS theme files (Sass entry point and settings files) from the `uswds` package to `paths.dist.theme`
`init`	`copyAll` + `compile`
`updateUswds`	`copyAssets` + `compile`
`watch`	Compiles, then recompiles when there are changes to Sass files in `paths.dist.theme` and `paths.src.projectSass`

For any function you defined as an export in your gulpfile.js, you can run npx gulp [function].

For example, if you wanted to have the ability to tell Gulp to compile your Sass, you’d need to first export the compile task for your project by adding this line to your gulpfile.js:

exports.compile = uswds.compile;

Once exported, you can compile your code by running the following in the command line from your project root:

npx gulp compile

Step 7: Initialize your project

When your gulpfile.js is ready, initialize your project to copy all the necessary Sass, image, font, and Javascript assets from the USWDS source code.

If you defined the init export in Step 6, you can initialize your project and get started by running the following command:

npx gulp init

This command will add all the USWDS assets to the directories you set, add a project Sass entry point, and compile USWDS into CSS. Add this CSS file to the <head> of your project HTML.

Note: Use init only once. The init task is meant for initializing the design system on a project. Since it will overwrite project files (like settings files and the Sass entry point), use it sparingly and don’t use it for updating the design system on a project, or at any point after you’ve customized your settings files.

If you receive the error replaceAll is not a function when trying to run npx gulp init, please verify you are using the version of Node specified in the .nvmrc file and run the command again.

Step 8: Verify successful installation

Any time you want to recompile your CSS, run npx gulp compile from the command line in your project root.

You should see a successful compile message.

[10:10:10] Finished 'buildSass' after 5.02 s
[10:10:10] Finished 'compileSass' after 5.03 s

To verify whether you’ve successfully installed USWDS and that compilation is working, we recommend confirming the directory structure matches the paths you have updated in gulpfile.js, copying a few components, pasting them into an HTML page, and then visiting that page in the browser to see if the components appear as expected.

Next: Phase 3: Customize →

Latest updates

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

Date	Description
2024-12-18	Added documentation for `settings.compile.sassDeprecationWarnings`. More information: uswds-site#3006
2024-09-05	Added documentation for `settings.compile.browserslist` and `settings.compile.sassSourcemaps`. More information: uswds-site#2750
2024-09-05	Removed the version number from “Gulp 4” references. More information: uswds-site#2750
2024-04-26	Replaced outdated references to `paths.dist.sass` with `paths.dist.theme`. More information: uswds-site#2401
2024-04-26	Added documentation for `paths.src.projectIcons` and `sprite.projectIconsOnly`. More information: uswds-site#2401
2023-07-28	Added clarity to the instructions for custom compilers. More information: uswds-site#2123
2023-05-11	Replaced references to `copySetup` with `copyTheme`. More information: uswds-site#2071
2022-10-11	Restructured content to add clarity. More information: uswds-site#1766
2022-08-16	Fixed typo by replacing `_index.html` with `_index.scss`. More information: uswds-site#1740
2022-06-17	Added warning and success note for `gulp init`. More information: uswds-site#1667
2022-06-03	Updated the example compile settings with values that do not generate warnings. More information: uswds-site#1597
2022-04-28	Updated documentation to use Sass module syntax and updated settings table. More information: uswds-site#1538
2022-03-10	Replaced the outdated text: `paths.dist.sass` with updated: `paths.dist.theme`. More information: uswds-site#1473
2022-03-10	Replaced the outdated text: `uswds-gulp` with updated: `uswds-compile`. More information: uswds-site#1424
2021-12-14	Added clarity to guidance. More information: uswds-site#1370
2021-12-06	Added “Getting started for developers” guide. More information: uswds-site#1362