Here are a few different ways to use the Standards within your project.
First, download the Web Design Standards assets:
Then, add the following folders into a relevant place in your code base — likely a directory where you keep third-party libraries:
uswds-1.4.3/ ├── js/ │ ├── uswds.min.js.map │ ├── uswds.min.js │ └── uswds.js ├── css/ │ ├── uswds.min.css.map │ ├── uswds.min.css │ └── uswds.css ├── img/ └── fonts/
Refer to these files by adding the following
into your HTML pages:
Add this to your
<link rel="stylesheet" href="/path/to/your/assets/css/lib/uswds.min.css">
Add this before the closing
And that’s it — you should be set to use the Standards.
If you have
node installed on your machine, you can use npm to install the Standards. Add
to your project’s
package.json as a dependency:
npm install --save uswds
The package will be installed in
node_modules/uswds. You can use the un-compiled files
found in the
src/ or the compiled files in the
node_modules/uswds/ ├── dist/ │ ├── css/ │ ├── fonts/ │ ├── img/ │ ├── js/ └── src/ ├── fonts/ ├── img/ ├── js/ └── stylesheets/
uswds module itself does not export anything.
The main Sass (SCSS) source file is here:
The non-minified CSS that’s been precompiled is here:
Using another framework or package manager
If you’re using another 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 download instructions. Please note that the core team isn’t responsible for all frameworks’ implementations.
If you’re interested in maintaining a package that helps us distribute the U.S. Web Design Standards, the project’s build system can help you create distribution bundles to use in your project. Please read our contribution guidelines to locally build distributions for your framework or package manager.
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:
You can also email us directly at firstname.lastname@example.org.
- The CSS foundation of this site is built with the Sass preprocessor language.
- Uses Bourbon for its simple and lightweight Sass mixin library, and the Neat library for the grid framework. Bourbon and Neat are open-source products from thoughtbot.
- The CSS organization and naming conventions follow 18F’s CSS Coding Styleguide.
- CSS selectors are prefixed with
.usa-button). This identifier helps the design system avoid conflicts with other styles on a site which are not part of the U.S. Web Design Standards.
- Uses a modified BEM approach created by 18F for naming CSS selectors. Objects in CSS are separated by single dashes. Multi-word objects are separated by an underscore (For example:
- Uses modular CSS for scalable, modular, and flexible code.
- Uses nesting when appropriate. Nest minimally with up to two levels of nesting.
- Hard-coded magic numbers are avoided and, if necessary, defined in the
- Media queries are built mobile first.
- Spacing units are as much as possible defined as rem or em units so they scale appropriately with text size. Pixels can be used for detail work and should not exceed 5px (For example: 3px borders).
For more information, visit: https://pages.18f.gov/frontend/css-coding-styleguide/
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 name (e.g.
off: The opposite of
hide: Hide the whole component.
show: Shows a whole, hidden component.
toggle: Toggles the visibility of a component on and off based on the previous state.
Some components have additional methods for manipulating specific aspects of them based on what they are and what they do. These can be found in the component’s JS file.
Customization and theming
The Standards can be customized to use different typography, colors and grid systems. The easiest way to do this is to use Sass and override the Standards’ global variables. If it isn’t possible to use Sass, do theming by overriding the CSS rules in the Standards set.
To start theming through Sass, copy the
core/variables file into your own project’s Sass folder, changing applicable variable values, and importing it before the WDS. Below is an example of customizing the import of the Standards all.scss file.
// src/main.scss @import 'path/to/my/scss/files/main/scss/my-custom-vars'; @import 'lib/uswds/src/stylesheets/all';
// path/to/my/scss/files/main/scss/my-custom_vars.scss // Colors $color-primary: #2c3e50; $color-secondary: #ad2020; $color-secondary-dark: #b0392e; // Typography $font-serif: 'Georgia', 'Times', serif; $h2-font-size: 2rem; $h3-font-size: 1.75rem; $heading-line-height: 1.4; // Grid/breakpoints $small-screen: 540px !default; $medium-screen: 620px !default; $large-screen: 1120px !default;
NOTE: If you plan on upgrading to newer versions of the Standards in the future, or are not using your own forked version of the Standards, try to avoid making changes in the Standards folder themselves. Doing so could make it impossible to upgrade in the future without undoing your custom changes.
Main variables that can be customized
- Colors can be found in the
core/variablesfile, line 35.
- Font families can be found in the
core/variablesfile, line 28.
- Typography sizing can be found in
core/variablesfile, line 13.
- Grid and breakpoint settings can be found in
core/variablesfile, line 87.
Where things live
- HTML markup for the components is located in:
src/htmlin the site root.
- Sass styles are located in:
src/stylesheets/ (/core, /elements, /components). Compiled CSS is located in the downloadable zip file .
- JS is located in:
src/js/components (accordion.js, toggle-field-mark.js, toggle-form-input.js, validator.js).
- Fonts are located in:
- Images and icons are located in:
We’ve designed the Standards to support older and newer browsers through progressive enhancement. The current major version of the Standards (1.0) is designed to support the newest versions of Chrome, Firefox, Safari, and Internet Explorer 9 and up. The next major release (2.0) will follow the 2% rule: we will officially support any browser above 2% usage as observed by analytics.usa.gov. Currently, this means that the Standards version 2.0 will support the newest versions of Chrome, Firefox, Safari, and Internet Explorer 11 and up.
The Standards also meet the WCAG 2.0 AA accessibility guidelines and are compliant with Section 508 of the Rehabilitation Act. We’re happy to answer questions about accessibility — email us for more information.
We’re so glad you’re thinking about contributing to the Standards! You can find our complete contribution guidelines in our repo — please review them before submitting your contribution.
If you have any questions about these guidelines (or the Standards, more generally), don’t hesitate to email us — we’ll get back to you within 48 hours.