The VA design system

va, sass, css, html, js, formation, vads
npm install @department-of-veterans-affairs/formation@6.17.3


Veteran Facing Services tools

This repo contains front end code and documentation used by the Veteran facing services on VA.gov. It's a monorepo managed by Lerna, a tool for managing versioning and publishing for multiple modules located in a single repo.

There is another repository for the documentation site. The documentation site can be viewed at design.va.gov. See also: contributing to Formation.



  • You need Homebrew. To install Homebrew, follow these instructions
  • You also need Yarn. To install Yarn, you'll use Homebrew. In Terminal, run brew install yarn

Clone the veteran-facing-services-tools repo:

You can put the repo anywhere on your computer, but as a suggestion:

  • In Terminal, navigate to your desktop: cd ~/desktop
  • Clone the Github repo by running: git clone https://github.com/department-of-veterans-affairs/veteran-facing-services-tools.git
  • Then: cd veteran-facing-services-tools
  • Run yarn to install dependencies for each module


Available npm scripts:

  • build: Builds the code in each repo and outputs it to the appropriate locations for publishing
  • test: Runs the tests in each repo
  • lint: Runs the linter in each repo

Updating formation

The process for updating formation can be found at https://department-of-veterans-affairs.github.io/veteran-facing-services-tools/getting-started/common-tasks/updating-formation



error "gatsby-mdx" threw an error while running the onCreateNode lifecycle

Example error: unknown: Expected corresponding JSX closing tag for <img>

The documentation package uses the gatsby-source-git Gatsby plugin to sync content from the va.gov-team repo.

Unfortunately, invalid HTML in va.gov-team Markdown files can break the build of the veteran-facing-services-tools repo.

invalid HTML in va.gov-team .md files can break the veteran-facing-services-tools build


To fix the Expected corresponding JSX closing tag for <img> error, you need to do the following:

  1. Find the invalid HTML in the va.gov-team repo
    1. Look for a string from the error message in the va.gov-team repo to find the offending Markdown file
    2. Look for HTML tags in that Markdown file
  2. Fix the invalid HTML
    • For example, replace HTML images with markdown images
      - <img src="zenhub-license-request.png" alt="zenhub license request"></img>
      + ![zenhub license request](zenhub-license-request.png)
  3. Rerun veteran-facing-services-tools build
    • Options
      • Rerun the Jenkins job restart jenkins build
      • Whitespace push
Example va.gov-team PR: https://github.com/department-of-veterans-affairs/va.gov-team/pull/9869