Draft U.S. Web Design Standards

The Draft 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 Draft 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.

To begin using the Draft Web Design Standards (to help you contribute to it or reuse it for your own purposes), go to Getting Started. To run the Draft Web Design Standards website locally on your machine, go to Setup for your local environment.

Reuse of open source style guides

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

Getting started

To begin using the Draft Web Design Standards on your project, include the CSS and JavaScript files in each HTML page in your project. Download the Draft Web Design Standards assets: https://github.com/18F/web-design-standards/archive/v0.8.3.zip. Add the dist directory files into a relevant places in your code base.

- dist
  - fonts/
  - img/
  - js/
  - css/

Refer to these files by adding a <link> and a <script> element into your HTML pages:

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

Install with NPM

If you have node installed on your machine, you can use npm to install the Draft Web Design Standards.

cd path/to/project-using-npm
npm install --save uswds

This will add the Draft Web Design Standards as a dependency for your project and save it to your package.json file. The package will be installed in node_modules under uswds.

Refer to these files by adding a <link> and a <script> element into your HTML pages:

If your project does not already include jQuery please use the version of jQuery that is included in the package.

<!-- CSS Includes -->
<link rel="stylesheet" href="./node_modules/uswds/assets/css/google-fonts.css">
<link rel="stylesheet" href="./node_modules/uswds/assets/css/uswds.css">

<!-- JavaScript Includes -->
<script src="./node_modules/uswds/assets/js/vendor/jquery-1.11.3.min.js"></script>
<script src="./node_modules/uswds/assets/js/components.js"></script>

If your project already includes jQuery via a script tag, feel free to use that version of jQuery.

<!-- CSS Includes -->
<link rel="stylesheet" href="./node_modules/uswds/assets/css/uswds.css">
<link rel="stylesheet" href="./node_modules/uswds/assets/css/google-fonts.css">

<!-- JavaScript Includes -->
<script src="./node_modules/uswds/assets/js/components.js"></script>

Using uswds with an npm-based asset pipeline

With the uswds package installed in your node_modules directory, you can access various included dependencies from the package itself. These dependencies include both JavaScript and Sass files.

Running require( 'uswds' ) will include the contents of the components.js file in your project. This file does not export currently export anything so it doesn't need to be assigned to a variable. This library depends on jQuery and $ to be on the window object before it is required. So please be sure that you include the jQuery dependency on your HTML page or via npm and set it to the window object as jQuery and $.

window.$ = window.jQuery = require( 'jquery' );
require( 'uswds' );
// ...

To use the styles from the Draft Web Design Standards you can import it into your main Sass file like so:

@import './node_modules/uswds/assets/_scss/all.scss';

Your HTML file may be structured like this:

<!-- CSS Includes -->
<link rel="stylesheet" href="./node_modules/uswds/assets/css/google-fonts.css">

<!-- Your compiled CSS, which imports the Draft Web Design Standards -->
<link rel="stylesheet" href="./path/to/assets/style.css">

<!-- Your compiled JavaScript, which creates jQuery on the `window` object. -->
<script src="./path/to/assets/start-app.js"></script>

Note: You might get an npm warning related to lodash, but you can generally ignore it. This error is related to a dependency found in node-sass.

Setup for your local environment

Requirements

These setup instructions are for running the Draft Web Design Standards website locally on your machine and not for using the assets (CSS, JavaScript, etc) on your own project. If you want to use the standards assets, go to Getting Started. For context, the styleguide website uses Jekyll (a static site generator), which is run via a ./go script. At 18F, we then use 18F Pages to publish and serve the site.

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

Note: The website is published with 18F Pages.

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 git@github.com:18F/web-design-standards.git
$ cd web-design-standards
$ npm install
$ gulp website:watch

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

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.

Gulp workflow

The Draft Web Design Standards repository includes gulp to help with the automation of certain tasks. Once the project is installed on your local machine, you can run gulp within the project directory and see all available commands.

The gulp-cli package will need to be installed globally in order to use the gulp tasks.

npm install --global gulp-cli

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 uswebdesignstandards@gsa.gov.

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