United States Web Design System

The United States Web Design System includes a library of open source UI components and a visual style guide for U.S. federal government websites.

This repository is for the design system code itself. We maintain another repository for the documentation and website. To see the design system and its documentation on the web, visit https://designsystem.digital.gov.

Contents

• Recent updates
• Getting started
• What's included in USWDS
  • Directory structure
  • Package contents
• Installing the design system
• Using USWDS CSS and JavaScript in your project
• Compiling USWDS Sass into CSS
  • Sass compilation requirements
  • Sass and theme settings
• JS customization
• Style theming and tokens
• CSS architecture
• Browser support
• Accessibility
• Long-term support of v1.x
• Long-term support of v2.x
• Need installation help?
• Contributing to the code base
• Reuse of open-source style guides
• Licenses and attribution
• Contributing

Recent updates

Information about the most recent release of the design system can always be found in the release history. We include details about significant updates and any backward-incompatible changes along with a list of all changes.

USWDS 3.0 is our most recent major release.

• Read about what's new in USWDS 3.0
• Read our USWDS 3.0 Migration Guide

Getting started

We’re glad you’d like to use the design system — here’s how you can get started:

• Designers: Check out our Getting started for designers information.
• Developers: Check out our Getting started for developers information. If your project doesn't use npm for package management, follow the instructions in this README to install the design system without npm.
• Anyone: Take a look at our new USWDS Tutorial. Follow the instructions in this GitHub repo to clone a sample project, install USWDS, customize it, and add USWDS components. It should take about an hour, and is a good introduction to USWDS concepts.

What's included in USWDS

The USWDS package includes compiled assets in a dist directory and component source files in a packages directory.

As of USWDS 3.0.0, our codebase is centered around functional packages, typically components. For more about how we organize packages, see our Packages documentation. In each of the following examples, we use [package] to represent a specific package. For example, component Sass is located in packages/[package]/src/styles for an accordion, this would be packages/usa-accordion/src/styles.

• Fonts are located in both dist/fonts and packages/uswds-core/src/assets/fonts. The fonts in dist are simply a copy of the files in uswds-core.
• Images and icons are located in: dist/img. The source for component-specific images can be found in a package's src/img directory.
• JavaScript for components is located in packages/[package]/src/index.js. General JavaScript utilities are located in the uswds-core package: packages/uswds-core/src/js
• Sass component-specific stylesheets are located in: packages/[package]/src/styles. Many components also have a component entry point at packages/[package]/_index.scss that includes references to all a component's dependencies as well. Compiled CSS is located in dist/css.
• Template markup for the components is located in: packages/[package]/src/[package.twig] in the site root. These, however, are written in the templating language Twig. It's best to get HTML source markup directly from designsystem.digital.gov/components

Directory structure

Here's what you can expect to find inside the USWDS package:

[uswds package]
├── .storybook/
├── dist/
│   ├── css/
│   │   ├── uswds.css
│   │   ├── uswds.min.css
│   │   └── uswds.min.css.map
│   ├── fonts/
│   │   ├── merriweather/
│   │   ├── public-sans/
│   │   ├── roboto-mono/
│   │   └── source-sans-pro/
│   ├── img/
│   │   ├── usa-icons/
│   │   ├── material-icons/
│   │   ├── uswds-icons/
│   │   ├── usa-icons-bg/
│   │   ├── sprite.svg
│   │   ├── [individual images]
│   │   ...
│   ├── js/
│   │   ├── uswds-init.js
│   │   ├── uswds-init.min.js
│   │   ├── uswds-init.min.js.map
│   │   ├── uswds.js
│   │   ├── uswds.min.js
│   │   └── uswds.min.js.map
│   ├── scss/
│   │   └── stylesheets/
│   │       └── uswds.scss
│   └── theme/
│       ├── _uswds-theme.scss
│       ├── _uswds-theme-custom-styles.scss
│       └── styles.scss
├── packages/
│   ├── usa-component/
│   │   ├── src/
│   │   │   ├── content/
│   │   │   ├── styles/
│   │   │   │   ├── _index.scss
│   │   │   │   └── component.scss
│   │   │   ├── test/
│   │   │   │   ├── component.spec.js
│   │   │   │   └── template.html
│   │   │   ├── index.js
│   │   │   ├── usa-component.stories.js
│   │   │   └── usa-component.twig
│   │   └── _index.scss_/
│   ├── usa-component/
│   ├── usa-component/
│   ├── uswds-bundle/
│   ├── uswds-bundle/
│   ...
├── src/
│   ├── img/
│   ├── stylesheets/
│   └── test/
└── tasks/

Package contents

Here's what you can expect to find in each of the directories and files in the USWDS package:

• /.storybook: Storybook configuration files (not used in USWDS projects)

• /dist: Compiled or collected files

• /dist/css: Precompiled CSS files with USWDS defaults

• /dist/fonts: Default fonts available to the design system

• /dist/img: All USWDS images collected into a single directory

• /dist/img/usa-icons: All icons collected into the USWDS icon sprite (sprite.svg)

• /dist/img/material-icons: All Material Icons

• /dist/img/uswds-icons: All icons created by USWDS

• /dist/img/sprite.svg: Precompiled icon sprite with default icon set

• /dist/js: Precompiled JavaScript files

• /dist/scss/stylesheets/uswds.scss: Backwards compatible USWDS Sass entry point

• /dist/scss/theme: Example theme files

• /dist/scss/theme/_uswds-theme.scss: Example theme settings file

• /dist/scss/theme/_uswds-theme-custom-styles.scss: Example custom settings file

• /dist/scss/theme/styles.scss: Example project Sass entry point

• /packages: Source files for USWDS components and other functionality.

• /packages/usa-[component]: Each package has a name like usa-[component] that matches its class name in the design system, like usa-accordion.

• /packages/usa-[component]/_index.scss: Sass entry point for the package.

• /packages/usa-[component]/src: Package source files

• /packages/usa-[component]/src/index.js: Package javascript

• /packages/usa-[component]/src/usa-component.stories.js: Storybook setup

• /packages/usa-[component]/src/usa-component.twig: Component template

• /packages/usa-[component]/src/index.js: Package javascript

• /packages/usa-[component]/src/content: Package template content

• /packages/usa-[component]/src/test: Package unit tests

• /packages/usa-[component]/src/styles: Package source Sass

• /packages/uswds: The package most projects include by default. This bundle includes all USWDS components and functionality.

• /packages/uswds-[bundle]: Other non-component functionality is included in uswds--prefixed packages. These bundles might collect common component packages (uswds-form-controls) or important internal functionality (uswds-core).

• /src: Placeholders included for backwards compatibility. Most projects should avoid using the contents of this directory.

• /tasks: Internal build process files (not used in USWDS projects)

Installing the design system

There are two ways to install the design system on a project:

• Installing it as a project dependency using Node and npm
• Installing the package directly from GitHub

We recommend using npm to make it as straightforward as possible to install the design system and update it as we release new versions.

Install using Node and npm

Use the npm package manager for Node-based projects. USWDS maintains the [@uswds/uswds package](https://www.npmjs.