Home

Awesome

United States Web Design System

CircleCI Build Status Snyk vulnerabilities npm Version npm Downloads GitHub issues code style: prettier

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

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.

Getting started

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

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.

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:

Installing the design system

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

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 that includes both the pre-compiled and compiled files. We rely on npm packages to easily update and install the design system from the command line.

  1. Install Node/npm. Below is a link to find the install method that coincides with your operating system:

    Note for Windows users: If you are using Windows and are unfamiliar with Node or npm, we recommend following Team Treehouse's tutorial for more information.

  2. Make sure you have installed it correctly:

    npm -v
6.13.0 # This line may vary depending on what version of Node you've installed.

  3. Create a package.json file. You can do this manually, but an easier method is to use the npm init command. This command will prompt you with a few questions to create your package.json file.

  4. Add @uswds/uswds to your project’s package.json:

    npm install --save @uswds/uswds@latest

The @uswds/uswds module is now installed as a dependency. You can use the compiled files found in the node_modules/@uswds/uswds/dist/ directory or the source files in the node_modules/@uswds/uswds/packages/ directory.

Note: We do not recommend directly editing the design system files in node_modules. One of the benefits of using a package manager is its ease of upgrade and installation. If you make customizations to the files in the package, any upgrade or re-installation will wipe them out.

Install the package directly from GitHub

If you’re using a framework or package manager that doesn’t support npm, you can find the source files in this repository and use them in your project. Otherwise, we recommend that you follow the steps outlined in this section.

  1. Download the USWDS package directly from the latest USWDS release and uncompress that file.

  2. Copy these files and folders into a relevant place in your project's code base. Here is an example structure for how this might look:

    example-project/
├── assets/
│   ├── uswds/
│   │   ├── dist/
│   │   ├── packages/
│   │   └── src/
│   ├── stylesheets/
│   ├── images/
│   └── javascript/
└── index.html

    You'll notice in our example above that we also outline a stylesheets, images and javascript folder in your assets folder. These folders are to help organize any assets that are unique to your project and separate from the design system assets.

    <!-- This note also exists on the USWDS Site download page, which is maintained in the USWDS-Site repo. If any changes are made, make sure to update there as well. -->

    Note: Files in the downloadable USWDS package will show a "last modified" date of October 26, 1985. This is intentional. This default date is set by npm on all its packages to ensure builds will be identical.

Using USWDS CSS and JavaScript in your project

The three files critical to any USWDS project are the stylesheet, the JavaScript, and the initializer. Most projects require all of these to function properly.

Reference the stylesheet, library, and initializer in each HTML page or dynamic template in your project.

Here is an example of how to reference these assets in your index.html file:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Example Project</title>
    <script src="assets/uswds/dist/js/uswds-init.min.js"></script>
    <link rel="stylesheet" href="assets/uswds/dist/css/uswds.min.css" />
  </head>
  <body>
    <script src="assets/uswds/dist/js/uswds.min.js"></script>
  </body>
</html>

And that’s it — you should now be able to copy our code samples into your index.html and start using the design system.

Compiling USWDS Sass into CSS

If you want to take full advantage of USWDS custom settings and add build new styles and components with the USWDS toolset, you'll need a way to access the assets in the USWDS package and compile custom CSS from the USWDS source files.

USWDS uses the task manager Gulp as a way to add USWDS assets to a project and compile our CSS from the package source. Gulp is a useful and powerful tool, but it can be difficult to set up if you are new to it.

The USWDS Compile package is made for developers new to Gulp or those who just want a simple setup to compile USWDS Sass. The repo contains files and instructions for setting up the compiler, initializing USWDS, and compiling CSS from the source files.

Sass compilation requirements

USWDS Sass needs three things to compile properly:

Note: Using a compiler package like USWDS Compile is a good way to fulfill these requirements automatically.

Autoprefixing

The design system requires autoprefixing to work properly. Don't add vendor prefixes to your custom styles manually — it is more reliable to use autoprefixing. Autoprefixing services like gulp-autoprefixer automatically add vendor prefixes to CSS rules. We use the following autoprefixer settings via .browserslistrc config:

> 2%
last 2 versions
not dead

Sass Load Paths

USWDS 3.0 and newer require the use of Sass Load Paths to compile properly.

USWDS 3.0 load paths must include a path to the /packages directory in the USWDS package, typically by updating an IncludePaths setting to include node_modules/@uswds/uswds/packages.

Here's how this might look in Gulp and in Webpack:

Gulp
.pipe(
  sass({
    includePaths: [
      "./node_modules/@uswds/uswds/packages",
    ],
  })
Webpack
loader: "sass-loader",
options: {
  sassOptions: {
    includePaths: [
      "./node_modules/@uswds/uswds/packages"
    ],
  },
},

Other useful compiler postprocessing

Sass and theme settings

The design system is customizable using the power of Sass (Syntactically Awesome Style Sheets). The critical files you'll need in your project are those in dist/scss/theme:

styles.scss looks something like the following code. It adds all the project theme settings, then adds USWDS source, and finally adds your project's custom styles:

@forward "uswds-theme";
@forward "uswds";
@forward "uswds-theme-custom-styles";

Technical note: The @forward 'uswds' statement above references the uswds package in node_modules/@uswds/uswds/packages. The compile functions included in uswds-compile automatically look for USWDS packages in the proper directory using includePaths.

JS customization

Unfortunately, customizing the JavaScript for the USWDS currently requires NodeJS and a module bundler like Browserify or Webpack. We apologize for this inconvenience, and are working to resolve it in a future release of the design system.

USWDS JavaScript is separated into components (just as with the CSS and HTML) and initialized with event handlers when the DOM is ready. These components are accessible as CommonJS modules that can be required in other JavaScript files, then built for the browser. The components are not accessible in the global browser scope, but can be extended to be included by requiring components and setting it to a global scope:

window.uswds = require("./components");

Each component has a standardized interface that can be used to extend it further. The components store a HTML class (like .usa-accordion__button[aria-controls]) used to link HTML elements with the JavaScript component. When a component is initialized, it searches through the current HTML DOM to find all elements that match the class and initializes the component JavaScript for those elements. The primary methods for each component include:

Some components have additional methods based on that component's functionality. Any additional methods are found in that component's JavaScript file.

If you’re using a modern framework like React or Angular you can import components and initialize them in your library's DOM ready lifecycle event.

Importing a modular component.

import USWDS from "@uswds/uswds/js";
const { characterCount, accordion } = USWDS; // deconstruct your components here

// Alternatively
import accordion from "@uswds/uswds/js/usa-accordion";

⚠️Requires webpack 5+

React hooks example:

function App() {
  const ref = document.body;

  useEffect(() => {
    // initialize
    characterCount.on(ref);
    // default ref is document.body, if you want to use
    // default you do not have to pass arguments
    accordion.on();

    // remove event listeners when the component un-mounts.
    return () => {
      characterCount.off();
      accordion.off();
    };
  });
}

Angular example:

export class App implements OnInit {
  constructor() {
    this.ref = document.body;
    // default ref is document.body, if you want to use
    // default you do not have to pass arguments
  }

  ngOnInit() {
    // initialize
    characterCount.on(this.ref);
    accordion.on();
  }

  // remove event listeners when the component un-mounts.
  ngOnDestroy() {
    characterCount.off();
    accordion.off();
  }
}

Style theming and tokens

USWDS 3.0 provides extensive support for theming via its theme settings files introduced in Sass and theme settings, above.

Set theme settings with USWDS design tokens, not with values directly. They tend to be quoted strings like 'desktop' or 'md' or unitless numbers like 2 or -1.5. Tokens are the values passed into the USWDS functions and mixins that parse them. They are the keys that, through the mechanism of a function or mixin, unlock a value — they are not the values themselves.

Visit the Design tokens section of USWDS 3.0 documentation for more on the available tokens for color, spacing units, font size, and more.

Using tokens in theme settings

The following is an example of theme settings from _uswds-theme.scss:

@use "uswds-core" with (
  $theme-grid-container-max-width: "desktop",
  $theme-site-margins-breakpoint: "desktop",
  $theme-site-margins-width: 4,
  $theme-site-margins-mobile-width: 2,
)

The USWDS uses those tokens to build component styles:

.usa-example {
  @include u-padding-x($theme-site-margins-mobile-width);
  max-width: units($theme-grid-container-max-width);

  @include at-media($theme-site-margins-breakpoint) {
    @include u-padding-x($theme-site-margins-width);
  }
}

This is the functional equivalent of:

.usa-example {
  @include u-padding-x(2);
  max-width: units("desktop");

  @include at-media("desktop") {
    @include u-padding-x(4);
  }
}

Which, if $theme-respect-user-font-size is set to true would output something like:

.usa-example {
  padding-left: 1rem;
  padding-right: 1rem;
  max-width: 64rem;
}

@media screen and (min-width: 64em) {
  .usa-example {
    padding-left: 2rem;
    padding-right: 2rem;
  }
}

In general, USWDS sets variables with tokens, and passes those variables into functions and mixins in the source Sass.

Set the base asset paths (fonts and images)

The values of $theme-font-path and $theme-image-path will be appended to USWDS font paths and image paths, respectively:

@use "uswds-core" with (
  $theme-font-path: "../fonts",
  $theme-image-path: "../img",
);

CSS architecture

For more information, visit: 18F’s CSS Guide

Browser support

We’ve designed the design system to support older and newer browsers through progressive enhancement. The current major version of the design system (3.0.0) follows the 2% rule: we officially support any browser above 2% usage as observed by analytics.usa.gov. Currently, this means that the design system version 3.0.0 supports the newest versions of Chrome, Firefox, and Safari.

As of USWDS 3.0.0, we no longer officially support Internet Explorer 11 (IE11). We continued to include IE11 polyfills and prefixing for the first few releases in USWDS 3.x. We started to remove IE11-related polyfills in USWDS 3.8.2, and removed the remaining polyfills in USWDS 3.10.0.

Accessibility

The design system also meets the WCAG 2.0 AA accessibility guidelines and conforms to the standards of Section 508 of the Rehabilitation Act. Additionally, we try to meet the requirements of WCAG 2.1.

We use the following tools to ensure USWDS is accessible:

If you find any issues with our accessibility conformance, please create an issue in our GitHub repo or send us an email at uswds@gsa.gov. We prioritize accessibility issues. See the Accessibility page of our website for more information.

Long-term support of v1.x

Version 1.x is no longer maintained.

Long-term support of v2.x

Version 2.x is in maintenance mode and will continue to get important bugfixes and security patches until May 2023.

Need installation help?

Do you have questions or need help with setup? Did you run into any weird errors while following these instructions? Feel free to open an issue here:

https://github.com/uswds/uswds/issues.

You can also email us directly at uswds@gsa.gov.

Contributing to the code base

For complete instructions on how to contribute code, please read CONTRIBUTING.md. These instructions also include guidance on how to set up your own copy of the design system style guide website for development.

If you would like to learn more about our workflow process, check out the Workflow and Issue label Glossary pages on the wiki.

If you have questions or concerns about our contributing workflow, please contact us by filing a GitHub issue or emailing our team.

Reuse of open-source style guides

Much of the guidance in USWDS leans on open source designs, code, and patterns from other civic and government organizations, including:

Licenses and attribution

A few parts of this project are not in the public domain. Attribution and licensing information for those parts are described in detail in LICENSE.md.

The rest of this project is in the worldwide public domain, released under the CC0 1.0 Universal public domain dedication.

Contributing

All contributions to this project will be released under the CC0 dedication alongside the public domain portions of this project. For more information, see CONTRIBUTING.md.