USWDS Packages

You can follow along in the demo repository.

In this exercise we’ll see the importance of using USWDS component packages.

The Default Approach

If you’re new to USWDS you’ve probably seen the styles being loaded like in the example below:

// Your custom theme.
@forward "uswds-theme";

// USWDS styles.
@forward "uswds";

// Your custom project styles.
@forward "your-project-styles";

You can see this in the demo repo:
./storybook/packages/index.scss
```
@forward "uswds-theme";

@forward "uswds";
```
In your terminal, make sure the component library is running.
Terminal window
```
# drupal-govcon-2025-demo ➜
npm run lib
```
Visit the sample USWDS page template.
Terminal window
```
http://localhost:6060/?path=/story/pages-landing--default
```
You should see the standard USWDS landing page template all styled and looking mostly good.
Next, go back to your terminal and stop the task or open a new terminal tab and compile the styles.
Terminal window
```
# drupal-govcon-2025-demo ➜
npm run build:vite -w storybook
```
After around 4 seconds you’ll get a compiled CSS file you can see in ./storybook/dist
- Directorystorybook/
  - Directorydist/
    Directoryassets/
    index-[a_random_hash].css # 565KB
If you open up finder and you’ll see that the file weighs about 565KB. Using the entire USWDS stylesheet without thinking about the components you’ll use, like in the previous exercise, can be heavy.

Let’s take a leaner approach by using USWDS component packages.

Replacing with Packages

Make sure your local component library environment is running.
Terminal window
```
# drupal-govcon-2025-demo ➜
npm run lib
```
Open up the index.scss file.
./storybook/index.scss
```
@forward "uswds-theme";

@forward "uswds";
```
Remove the @forward "uswds";.
./storybook/index.scss
```
@forward "uswds-theme";

 @forward "uswds";
```
Next, open the documentation page in your browser. You should see an unstyled page.
Terminal window
```
http://localhost:6060/?path=/story/pages-landing--default
```
First, let’s identify the components we have on the page. We have banner, hero, footer among others.
Next we’ll use the table in the USWDS Packages docs and import what we need. Let’s fix the Government Banner first.
./storybook/index.scss
```
@forward "uswds-theme";

 @forward "usa-banner";
```
You should see a much quicker compile in your terminal. The page should auto refresh and you should see a banner with some styles.

Can you add the remaining packages?
Solution
The following components should be included:
./storybook/index.scss
```
 @forward "usa-accordion";
 @forward "usa-banner";
 @forward "usa-button";
 @forward "usa-skipnav";
 @forward "usa-header";
 @forward "usa-hero";
 @forward "usa-section";
 @forward "usa-footer";
 @forward "usa-identifier";
```
You might have noticed that some packages already include other components. For example, usa-button styles appear with usa-header styles. If you also forward buttons you’ll only load it once thanks to SASS modules.

We’re just missing a few bundled packages to make this work, the global styles that includes the CSS normalize and the typography. In the packages table they’re called uswds-global uswds-typography.

@forward "uswds-global";
@forward "uswds-typography";

Solution

Your index file should look like this:

@forward "uswds-theme";

@forward "usa-accordion";
@forward "usa-banner";
@forward "usa-button";
@forward "usa-skipnav";
@forward "usa-header";
@forward "usa-hero";
@forward "usa-section";
@forward "usa-footer";
@forward "usa-identifier";

@forward "uswds-global";
@forward "uswds-typography";

If you take a look at the page again, you should see the page is styled again.
Run the build command again and see that your styles are much leaner too.
Terminal window
```
npm run build:vite -w storybook
```
The index.css file should be 149KB now, saving 416KB from our original.

Not only do you get faster builds and leaner styles, but now you’re setup to be able to extend USWDS!