U.S. Web Design Standards

The U.S. Web Design Standards is 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 reuse 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 Web Design Standards are designed to support government product teams in creating beautiful and easy-to-use online experiences for the American people. Learn more about this project in our announcement blog post.

Design files of all the assets included on this site are available for download here: https://github.com/18F/web-design-standards-assets.

The structural setup of this repo is based off of https://github.com/18F/pages.

Reuse of open source style guides

Much of the guidance in 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

Getting started

To begin using the U.S. Web Design Standards, include the CSS and JavaScript files in each HTML page of your project. Copy the full _site/assets/ directory to a relevant place in your code base cp ./_site/assets/css/main.css /path/to/your/repo/static/dir. Add the following <link> and <script> elements in your HTML:

• <link rel="stylesheet" href="/path/to/your/assets/css/main.css">
• <link rel="stylesheet" href="/path/to/your/assets/css/google-fonts.css">
• <script src="/path/to/your/assets/js/components.js"></script>

Setup for your local environment

Requirements

You will need Ruby ( > version 2.2.3 ). You may consider using a Ruby version manager such as rbenv or rvm to help ensure that Ruby version upgrades don't mean all your gems will need to be rebuilt.

On OS X, you can also use Homebrew to install Ruby in /usr/local/bin, which may require you to update your $PATH environment variable. Here are the commands to follow to install via homebrew:

$ brew update
$ brew install ruby

Installation

Now that you have verified that you have Ruby installed, clone and run the following go script commands to initialize and serve the library locally.

$ git clone [email protected]:18F/web-design-standards.git
$ cd web-design-standards
$ ./go serve

You should now be able to visit http://127.0.0.1:4000/ and view the web design standards locally.

Questions or need help with setup? Feel free to open an issue here https://github.com/18F/web-design-standards/issues.

Contributing to the code base

See CONTRIBUTING.

Deployment and workflow

• The staging branch 18f-pages-staging is automatically deployed to our staging site: https://pages-staging.18f.gov/designstandards/.
• The production branch 18f-pages is automatically deployed to our production site: https://playbook.cio.gov/designstandards/.

All development and pull requests should be done against the 18f-pages-staging branch.

18f-pages-staging is already set to the default branch in this repository.

Deployments to production will be done by site admins, using pull requests from 18f-pages-staging to 18f-pages.

Got feedback?

Please create a GitHub Issue.

If you'd rather email, you can reach us at [email protected].

Licenses and attribution

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

The Source Sans Pro font files in assets/fonts are a customized subset of Source Sans Pro, licensed under the SIL Open Font License, and copyright 2010, 2012, 2014 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 assets/fonts are from Google Web Fonts, licensed under the SIL Open Font License, and copyright © 2010-2013, Sorkin Type Co with Reserved Font Name 'Merriweather'.

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

The files in assets/_scss/lib/bourbon are from Bourbon, copyright © 2011–2015 thoughtbot, inc., under the MIT license.

The files in assets/_scss/lib/neat are from Neat, copyright © 2012–2015 thoughtbot, inc., also under the MIT license.

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

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

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

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

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

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

The file assets/js/vendor/selectivisr-min.js is from Selectivizr, copyright © Keith Clark, under the MIT license.

The files assets-styleguide/js/vendor/prism.js and assets-styleguide/css/prism.css are from Prism, copyright © 2012-2013 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.