Draft U.S. Web Design Standards

The Draft U.S. Web Design Standards include a library of open source UI components and a visual style guide for U.S. federal government websites.

These tools follow industry-standard web accessibility guidelines and use the best practices of existing style libraries and modern web design. Created and maintained by U.S. Digital Service and 18F designers and developers, the Draft Web Design Standards are designed for use by government product teams who want to create beautiful, easy-to-use online experiences for the public. To learn more about the project, check out this blog post.

Getting started

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

Designers: Check out our Getting Started for Designers information.
- Design files of all the assets included on this site are available for download.
Developers: Follow the instructions in this README to get started.
- CSS, JavaScript, image, and font files of all the assets on this site are available for download.

Here are a few different ways to use the Standards within your project.

Download

To use the Draft Web Design Standards on your project, you’ll need to include the CSS and JavaScript files in each HTML page in your project.

First, download the Draft Web Design Standards assets:

https://github.com/18F/web-design-standards/releases/download/v0.9.1/uswds-0.9.1.zip

Then, add the dist directory files into a relevant place in your code base — likely a directory where you keep third-party libraries:

uswds-0.9.1/
├── 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 <link> and <script> elements into your HTML pages:

Add this to your <head> element:

<link rel="stylesheet" href="/path/to/your/assets/css/lib/uswds.min.css">

Add this before the closing </body> tag:

<script src="/path/to/your/assets/js/lib/uswds.min.js"></script>

We offer two versions — a minified version, and an un-minified one. Use the minified version in a production environment or to reduce the file size of your downloaded assets. And the un-minified version is better if you are in a development environment or would like to debug the CSS or JavaScript assets in the browser. The examples above recommend using the minified versions.

This version of the Standards includes jQuery version 2.2.0 bundled within the JavaScript file. Please make sure that you're not including any other version of jQuery on your page.

And that’s it — you should be set to use the Standards.

Using npm

If you have node installed on your machine, you can use npm to install the Standards. Add uswds 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 files found in the src/ directory.

node_modules/uswds/
├── dist/
│   ├── css/
│   ├── fonts/
│   ├── img/
│   ├── js/
└── src/
    ├── fonts/
    ├── img/
    ├── js/
    └── stylesheets/

require('uswds') will load all of the Draft U.S. Web Design Standard's JavaScript onto the page. The uswds module itself does not export anything.

The main Sass (SCSS) source file is here:

node_modules/uswds/src/stylesheets/all.scss

The non-minified CSS that’s been precompiled is here:

node_modules/uswds/dist/css/uswds.css

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 Draft Web Design Standards, the project's build system can help you create distribution bundles to use in your project. Please read our contributing 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:

https://github.com/18F/web-design-standards/issues.

You can also email us directly at uswebdesignstandards@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 Standards style guide website for development.

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 the Draft Web Design Standards leans on open source designs, code, and patterns from other civic and government organizations, including:

Consumer Financial Protection Bureau’s Design Manual
U.S. Patent and Trademark Office’s Design Patterns
Healthcare.gov Style Guide
UK’s Government Digital Service’s UI Elements
Code for America’s Chime Styleguide
Pivotal Labs Component Library

Licenses and attribution

A few parts of this project are not in the public domain

The Source Sans Pro font files in src/fonts are a customized subset of Source Sans Pro, licensed under the SIL Open Font License, and copyright Adobe Systems Incorporated, with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.

The Merriweather font files in src/fonts are from Google Web Fonts, licensed under the SIL Open Font License, and copyright Sorkin Type Co with Reserved Font Name 'Merriweather'.

The files in src/img are from Font Awesome by Dave Gandy under the SIL Open Font License 1.1.

The files in src/stylesheets/_scss/lib/bourbon are from Bourbon, copyright thoughtbot, inc., under the MIT license.

The files in src/stylesheets/_scss/lib/neat are from Neat, copyright thoughtbot, inc., also under the MIT license.

The file src/stylesheets/css/normalize.min.css is from Normalize.css, copyright Nicolas Gallagher and Jonathan Neal, under the MIT license.

The file src/js/component.js includes politespace.js from Politespace, copyright Zach Leatherman, under the MIT license.

The file src/js/vendor/html5shiv.js is from HTML5 Shiv, copyright Alexander Farkas (aFarkas), under the MIT license.

The file src/js/vendor/jquery-1.11.3.min.js is from jQuery, copyright The jQuery Foundation, under the MIT license.

The file src/js/vendor/rem.min.js is from REM unit polyfill, copyright Chuck Carpenter, under the MIT license.

The file src/js/vendor/respond.js is from Respond.js, copyright Scott Jehl, under the MIT license.

The file src/js/vendor/selectivizr-min.js is from Selectivizr, copyright Keith Clark, under the MIT license.

The files docs/assets/js/vendor/prism.js and assets-styleguide/css/prism.css are from Prism, copyright Lea Verou, under the MIT license.

The rest of this project is in the public domain

The rest of this project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

hstonel/web-design-standards