USWDS website and documentation
This repo includes code and documentation for the U.S. Web Design System website. For information on the USWDS components and codebase, please visit our uswds Github repo.
Note that this README includes steps to pull the latest version of USWDS into your local instance of the documentation.
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.
Recommended before install:
You will need to have the following installed on your machine before following the commands below:
* If you're running into node-gyp issues onnpm installyou'll need to install python v2.7, which is the recommended version as ofnpm config set python /usr/bin/python2.7or wherever you have installed. You can find that withwhereis pythoncommand.
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:
Now that all of your dependencies are installed, you can run your local server by running the following command:
127.0.0.1:4000in your browser — you should be viewing a local instance of designsystem.digital.gov.
Here are a few other utility commands you may find useful:
npm run clean: Cleans out copied-over dependency assets.
npm run lint: Runs
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 -- --incrementalor
npm run serve: Runs your local server with incremental regeneration enabled to greatly improve build time. Use instead of
Sometimes you will want to use the latest version of the
uswdsrepo. Follow these steps to do so:
npm installto install the dependencies required for the package in the
npm run buildto create the built version of USWDS in the
npm linkin the root level of the
uswdsdirectory on your local machine.
npm link uswdsin the root level of the
uswds-sitedirectory on your local machine.
npm startin the
uswdsdirectory, and make a note of the
Local URLthat Fractal is serving.
FRACTAL_BASE_URLenv var to the running Fractal instance for
uswds. In your terminal window in the
export FRACTAL_BASE_URL="http://127.0.0.1:3000"(or the
Local URLnoted above).
npm run servein the
uswds-sitedirectory to start the Jekyll server.
npm run watchin the
uswds-sitedirectory to have changes to that repo automatically built and compiled. Note:
uswds-sitewill not automatically rebuild when there are changes in
uswds, you'll need to trigger a site rebuild manually to reflect changes in the
You are now linked and using the local version of USWDS. To unlink this version, type
npm unlink uswdsfrom the root level of the
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_componentJekyll tag, which takes the full name of the fractal component as a parameter.
This site is deployed on Federalist, which automatically builds the public site whenever commits are pushed to
main. Federalist also builds public previews for each branch pushed to GitHub.
To update the version of USWDS being used, change the version that
package.jsonspecifies in its
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.rbfor details). Therefore, be sure to use an actual version tag on all
mainbranch commits--otherwise a commit hash will show up as the version on the production site, which would be confusing.
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
The dynamic content is stored in the
.jekyll_get_cachedirectory 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.