Code guidelines

Welcome!

We’re so glad you’re thinking about contributing to a Technology Transformation Services (TTS) open source project! If you’re unsure about anything, just ask — or submit your issue or pull request anyway. The worst that can happen is we’ll politely ask you to change something. We appreciate all friendly contributions.

TTS is committed to building a safe, welcoming, harassment-free culture for everyone. We expect everyone on the TTS team and everyone within TTS spaces, including contributors to our projects, to follow the TTS Code of Conduct.

We encourage you to read this project’s CONTRIBUTING policy (you are here), its LICENSE, README and its Workflow process.

Guidelines

Contributor Guidelines for Design

We have provided some guidelines for folks that would like to submit new components to the U.S. Web Design System and the lifecycle those new components will go through. For more detail, please visit the guidelines on our wiki.

Submitting an issue

To help us get a better understanding of the issue you’re submitting, follow our ISSUE TEMPLATE and the guidelines it describes.

Running locally

The U.S. Web Design System uswds package (the zip download and the
files needed to use the Design System on your project) is built primarily with
two Node.js tools: Fractal and Gulp. Once you’ve cloned this
repository, you’ll need to install its dependencies:

npm install

ProTip: You can also use Yarn, which tends to install dependencies more quickly than npm.

Then, visit localhost:3000 in a web browser to
peruse the component library. While the server is running, any changes that
you make to the component templates or configurations will reload the page
automatically.

If you’re working on the JavaScript or CSS, you can run the “watch” task in
another shell to automatically rebuild the distribution files that Fractal
references with:

npm run watch

Testing

To run the component unit tests, run:

npm test

This will also run eslint and stylelint to ensure that the JavaScript
and SCSS source files meet our coding standards. To lint without the unit
tests, you’ll need Gulp. Install it globally (npm install -g
gulp-cli), then run:

gulp eslint
gulp stylelint

(Or, if you don’t want to install Gulp globally, you can run $(npm
bin)/gulp instead of gulp.)

Note that running the tests also requires an installation of
Chrome v59 or higher (v60 if you’re on Windows).

For non-OSX users:
Before running the tests, if you are developing on a machine running an operating system other than OSX,
you’ll need to export a CHROME_PATH environment variable that points to Chrome’s binary location. This ensures chrome-launcher
can find a version of Chrome for our aXe visual acceptence tests. A table of the locations of the binary
for each OS can be found here.

Visual regression testing

The Design System comes with optional tooling for detecting visual regressions,
which can be especially useful if you’re refactoring CSS.

These tests work by comparing current screenshots of the Design System’s Fractal
components to “golden” screenshots that represent what the components are
supposed to look like.

Golden screenshots are stored on your local development system only;
they’re not version controlled. This means that after making changes to a branch,
you can switch to the branch you’d like to compare it to (e.g. the develop
branch) to generate your golden screenshots.

To generate the golden screenshots, run:

node spec/visual-regression-tester.js test --updateGolden

Then, make any CSS refactorings (or switch to a branch that has them).

To compare the current state of your CSS to the golden screenshots, run:

node spec/visual-regression-tester.js test

If the current screenshots don’t match their golden counterparts, you will
be directed to an HTML file that visually shows the differences between
any conflicting screenshots.

Building

To build the uswds package in preparation for releases, run:

npm run release

Coding guidelines

The purpose of our coding styleguides are to create consistent coding practices across 18F. The styleguide should be treated as a guide — rules can be modified according to project needs.

This project follows the 18F Front End Guide CSS and JavaScript. Please use this guide for your reference.

Code coverage

We use code coverage tools to understand how much of our JavaScript is tested by our unit test suite. Code coverage is one way (among many) of measuring code quality more generally. Here’s how it works for contributions:

Code Climate then posts a status message back to GitHub that lists the coverage percentage on that branch, and the difference between that number and the one last reported on our default branch.

For JavaScript contributions, we will review the code coverage percentage and change to ensure that the quality of our code is not dramatically affected.

High code coverage numbers are generally good, and we would prefer that our coverage increases over time. We will not categorically reject contributions that reduce code coverage, but we may ask contributors to refactor their code, add new unit tests, or modify existing tests to avoid significant reductions in coverage.

Contributions will be released into the public domain

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.

Become part of the community

The U.S. Web Design System has grown into a blossoming, open source community of government engineers, content specialists, and designers. We currently support dozens of agencies and more than 100 sites, which is fueled through an active community of contributors both in and out of government.