Skip to content
USWDS website and documentation
Branch: master
Clone or download
thisisdano Merge pull request #795 from uswds/fix-autoprefixer
Revert autoprefixer to earlier settings
Latest commit 1e31b1e Jun 21, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Try adding browsers tag to add chrome May 8, 2019
.github Replace more fonts and USWDS instances Mar 22, 2019
_components Convert 2.0 references to 2 Jun 7, 2019
_data Merge pull request #742 from uswds/add-new-homepage-design Apr 8, 2019
_drafts publish Fractal + Federalist on 4/26 Apr 24, 2017
_includes Merge branch 'v2' into merge-v2 Jun 7, 2019
_layouts Update to 2.0.3 Jun 3, 2019
_plugins Split tokens into separate files Nov 6, 2018
_posts Merge branch 'add-v2-blog-post' into add-new-homepage-design Apr 8, 2019
config Revert to v2 browserlist settings Jun 21, 2019
css Remove -2px margin Apr 11, 2019
files/uswds-for-designers Add newest sketch assets Jun 7, 2019
img Update slack logo Jun 13, 2019
js Constrain sibling margin / Disable sticky sidenav [at least temporarily] Sep 27, 2018
pages Add z() function Jun 14, 2019
spec Update repo path Feb 3, 2018
utils Update check-contrast.js Feb 2, 2019
.browserslistrc Revert to v2 browserlist settings Jun 21, 2019
.eslintrc Initial commit. Jul 27, 2016
.gitattributes Declare package lock a binary in gitattributes Feb 25, 2019
.gitignore Adds POC contrasst checker Aug 27, 2018
.nvmrc Use node 8 Feb 25, 2019
.ruby-version Add more recent ruby-version to support scss-lint Jun 21, 2019
.scss-lint.yml Disable comment rule Aug 14, 2018
.snyk Package security updates Mar 7, 2019 Update May 22, 2018
Gemfile Remove redundant deps and rebuild gemfile Jun 21, 2019
Gemfile.lock Remove redundant deps and rebuild gemfile Jun 21, 2019 Lowercased "government" Aug 11, 2016 Replace more fonts and USWDS instances Mar 22, 2019
_config.yml Use proper version for external previews Jun 13, 2019
gulpfile.js Migrate to Gulp 4.0 May 15, 2018
package-lock.json Remove normalize package Jun 21, 2019
package.json Remove normalize package Jun 21, 2019

U.S. Web Design System documentation

This repo includes code and documentation for the U.S. Web Design System website. For information on USWDS (components) themselves, please visit web-design-standards.

Note that this README includes steps to pull the latest version of USWDS into your local instance of the documentation.

Running locally

The U.S. Web Design System documentation is built using Jekyll for the file framework, gulp for task management, and the node module for USWDS.

Before you start

You will need to have the following installed on your machine before following the commands below:

  1. Ruby v2.2.2+, Installation guides
  2. Node v4.2.3+, Installation guides
  3. Bundler v1.12.3+, Installation guides
  4. Chrome v59 or higher (v60 if on Windows)

Building the documentation with gulp

Some parts of the documentation are built using gulp.

To work on the site, switch to your local copy of the repository in terminal then run the following command to install project dependencies:

npm install

Now that all of your dependencies are installed, you can run your local server by running the following command:

npm start

Go to in your browser — you should be viewing a local instance of

Here are a few other utility commands you may find useful:

  • npm run clean: Cleans out copied-over dependency assets.

  • npm run lint: Runs eslint and sass-lint against JavaScript and Sass files.

  • npm test: Runs all tests and linters.

  • npm run watch: Runs a series of commands that watches for any changes in both USWDS node module and the root level asset folders in this repo.

  • npm start -- --incremental: Runs your local server with incremental regeneration enabled to greatly improve build time. Use instead of npm start.

Using the latest version of the uswds package

Sometimes you will want to use the latest version of the web-design-standards repo. Follow these steps to do so:

  1. Clone the latest version of the web-design-standards repo.
  2. Run npm install to install the dependencies required for the package in the web-design-standards directory.
  3. Run npm run build to create the built version of USWDS in the web-design-standards directory.
  4. Run npm link in the root level of the web-design-standards directory on your local machine.
  5. Run npm link uswds in the root level of the web-design-standards-docs directory on your local machine.
  6. Set the FRACTAL_BASE_URL env var to the running fractal instance for web-design-standards. In your terminal window in the web-design-standards-docs directory, enter export FRACTAL_BASE_URL="".
  7. Run npm run watch in both project directories to have changes automatically built and compiled on changes to any asset files.
  8. In a new terminal window, run npm start in the web-design-standards-docs directory to start the Jekyll server locally.

You are now using the latest version of USWDS via your cloned version on your local machine. To stop using this version, type npm unlink uswds from the root level of the web-design-standards-docs directory.

Fractal components

USWDS uses the fractal design system builder to organize and document the components. This documentation site pulls the components from fractal to showcase them on the site. This is done with a custom fractal_component Jekyll tag, which takes the full name of the fractal component as a parameter.

Deployment and previews

This site is deployed on Federalist, which automatically builds the site whenever commits are pushed to master.

Federalist also builds public previews for each branch pushed to GitHub. For instance, to see the latest build of the develop branch, visit:

Updating the USWDS version

To update the version of USWDS being used, change the version that package.json specifies in its dependencies section.

We currently pull USWDS via git rather than npm, as it allows us to use any tag or commit during development. To install a specific commit, you can use e.g.:

npm install --save "uswds/uswds#fb49e4f"

Alternatively, to use a specific version tag, use e.g.:

npm install --save "uswds/uswds#v1.3.1"

This version number or commit hash is automatically parsed when the site is built and used for display on the site (see _plugins/uswds_version.rb for details). Therefore, be sure to use an actual version tag on all master branch commits--otherwise a commit hash will show up as the version on the production site, which would be confusing.

Adding content to the "Updates" section

See the _posts directory for instructions on adding updates.

Dynamic content

Some of the content on the documentation site is dynamically fetched from GitHub. If you want to ensure that its API won't rate-limit you, you may want to create an access token and assign it to your GITHUB_ACCESS_TOKEN environment variable.

The dynamic content is stored in the .jekyll_get_cache directory and won't be re-fetched once it's cached there. However, this means that your data can get stale over time, so if you want to ensure that your site is using the very latest data, you'll want to clear the cache by running:

rm -rf .jekyll_get_cache


Please read through our contributing guidelines. These guidelines are directions for opening issues and submitting pull requests, and they also detail the coding and design standards we follow.

You can’t perform that action at this time.