United States Web Design System

The United States Web Design System is a toolkit of principles, guidance, and code — a library of public domain and open source user interface components and a visual style guide designed for U.S. federal government websites, but useful in many other applications.

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.

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.

Getting started

So glad you’re interested — 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.
Everyone and anyone: The USWDS Tutorial can be helpful. Follow the instructions in that 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. You can also learn from this live tutorial.

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, the USWDS codebase is centered around functional packages, typically components. You can see our Packages documentation for more about USWDS package organization. In each of the following examples, [package] represents 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 dependencies for that component. 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's 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's 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. Typically you 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 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.

Install Node/npm. Be sure to use the right install method for your operating system:

- Node (see .nvmrc for version number), Installation guides

Note for Windows users: If you're using Windows but aren't familiar with Node or npm, we recommend following Team Treehouse's tutorial for more information.

Make sure you installed it correctly:

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

Create a package.json file. You can do this manually, but it's easier to use the npm init command, which will prompt you with a few questions to create your package.json file.

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. If you do that, you'll lose one of the major benefits of using a package manager — its ease of upgrade and installation. If you customize files in the package, any upgrade or re-installation will wipe out those changes.

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.

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

Copy these files and folders into a relevant place in your project's code base. Here's an example structure:

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

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

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.

Stylesheet: This is the compiled CSS stylesheet that describes how design system components look. To start, reference either uswds.css or uswds.min.css in the of your document. Find this file in /dist/css. Most projects will want to compile their own CSS from USWDS source Sass instead of using the precompiled version. For more about this, see Compiling USWDS Sass into CSS, below.
Library: This is the compiled JavaScript that controls component interactivity. Reference either uswds.js or uswds.min.js at the end of the of your document. Find this file in /dist/js.
Initializer: This small JavaScript file (less than 1 KB minified) helps the browser know if the USWDS JavaScript library is loading properly. This prevents component content from "flashing" or "shifting" while the page loads. Reference uswds-init.min.js in the of your page, or inline its contents directly into the Chat with me

uswds/uswds: The U.S. Web Design System helps the federal government build fast, accessible, mobile-friendly websites.