United States Web Design System

 !Snyk vulnerabilities    

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](#recent-updates)
• [Getting started](#getting-started)
• [What's included in USWDS](#whats-included-in-uswds)

• [Installing the design system](#installing-the-design-system)
• [Using USWDS CSS and JavaScript in your project](#using-uswds-css-and-javascript-in-your-project)
• [Compiling USWDS Sass into CSS](#compiling-uswds-sass-into-css)

• [JS customization](#js-customization)
• [Style theming and tokens](#style-theming-and-tokens)
• [CSS architecture](#css-architecture)
• [Browser support](#browser-support)
• [Accessibility](#accessibility)
• [Long-term support of v1.x](#long-term-support-of-v1x)
• [Long-term support of v2.x](#long-term-support-of-v2x)
• [Need installation help?](#need-installation-help)
• [Contributing to the code base](#contributing-to-the-code-base)
• [Reuse of open-source style guides](#reuse-of-open-source-style-guides)
• [Licenses and attribution](#licenses-and-attribution)
• [Contributing](#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.](#installing-the-design-system)
• 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

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

[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

• /.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

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

Install using Node and npm

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

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

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:

shell
   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:

shell
   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

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.

• 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](#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 tag. Find this file in /dist/js.

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

html
<!DOCTYPE html>

  
    
    
    
    My Example Project

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.

###

…

Collapse