Login.gov Design System
Installation and usage
See the documentation for installation and usage instructions.
Configuring for development
The following dependencies are required to build the documentation and assets within this repository:
After satisfying the above language dependencies and cloning this repository, install package dependencies:
npm install bundle install
In development, build the documentation site with assets, watch source files for changes, and serve the compiled site at localhost:4000 by running:
src/ by running:
npm run lint
This project uses Prettier to format code. When running the lint command above, you may notice errors relating to unexpected code formatting. It's recommended that you install an editor integration to automatically format code on save, but you can also resolve these errors automatically from the command-line by running:
npm run lint -- --fix
Visual regression tests
When a pull request is submitted, a visual regression test will be automatically run to check for any visual changes between the working copy of the branch and the live documentation site. These will be reported as the
ci/circleci: visual-regression GitHub status check.
A failure of this status check only indicates that a visual change was detected. Depending on the types of changes being proposed, this may be expected. Anyone with access to the CircleCI dashboard can review the specific changes by following the status check "Details" link and comparing the set of screenshots under the "Artifacts" tab. If the visual changes are acceptable, the pull request can be merged, even if the status check is reported as a failure.
Deploying documentation updates
Documentation deploys are performed automatically upon merging to
main by Federalist. Federalist performs the following steps:
npm install --production(a no-op, as this package has no production dependencies)
npm run federalist
bundle exec jekyll build
More information can be found in Federalist’s How Builds Work.
Publishing a release to
When you're ready to release a new version of the
identity-style-guide package there are just a few steps to take.
Before starting, make sure that all changes intended for release should be merged into the
main branch. You will need permissions to publish the package to npm. Check current package owners by running
npm owner ls or by consulting the list of admins through the Services and Accounts handbook page. If you do not have access, contact an owner to have access granted or to publish on your behalf.
- Check out the latest main branch on your local machine by running
git checkout main, followed by
- Decide the version number for the new release.
CHANGELOG.mdshould ideally include all pending changes under an "Unreleased" heading.
- This project uses semantic versioning: breaking changes should bump the major version, backwards-compatible changes should bump the minor version, and bug fixes should bump the patch version.
- Since the main branch is protected, you will need to bump the version in a new branch and open a pull request. Start by creating a new branch.
git checkout -b release-4-3-1
- Change the "Unreleased" heading in
CHANGELOG.mdto the version you decided in Step 3. Commit this change to your new branch.
npm versionto bump the package version, passing one of
majordepending on what you had decided in Step 3 for the next version.
npm version patch
- A new version will be created. This will update
package-lock.jsonautomatically and create a commit.
- Do a trial publish by running
npm publish --dry-run.
- Consider: In the files listed, are there any that should or shouldn't be included? Does the version match what you expect?
- If everything looks alright, continue with publishing by running
- Push your release branch to the GitHub repository and open a pull request.
- Once approved and merged, create a new release on the GitHub "Releases" page.
mainas the target.
- The release version should match the version just published to
- Use the version name as the release title.
- Use the release notes to link to any important issues or pull requests that were addressed in the release. You may copy this from