Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Latest release: Component Library: v51.2.0 released on Jul 10, 2025 | Guidance: Sprint 6 released on Jul 16, 2025 | Figma: Changelog

About

Install

The VA Design System has two main packages that can be used to build custom applications: the CSS-Library and the Web Component library. The CSS-Library provides a set of stylesheets, tokens, and utilities. The Web Component library provides a set of reusable Web Components.

Install the CSS-Library into your project

How you implement VA Design System (VADS) into your project depends on how your project is structured and your preferences. The easiest way to get started is by using yarn to install the CSS-Library package into your project:

yarn add @department-of-veterans-affairs/css-library

Once the package is installed, import the main CSS files into your project:

@import "@department-of-veterans-affairs/css-library/dist/stylesheets/core";
@import "@department-of-veterans-affairs/css-library/dist/stylesheets/uswds-typography";
@import "@department-of-veterans-affairs/css-library/dist/stylesheets/utilities";

Fonts will need to be loaded from the CSS-Library fonts/ directory. For example:

$css-library-font-path: "../../node_modules/@department-of-veterans-affairs/css-library/dist/fonts";

/* latin - Source Sans Pro Regular */
@font-face {
  font-family: "Source Sans Pro";
  font-style: normal;
  font-weight: 400;
  src:
    local("Source Sans Pro Regular"),
    local("SourceSansPro-Regular"),
    url('#{$css-library-font-path}/sourcesanspro-regular-webfont.woff2') format("woff2"),
    url('#{$css-library-font-path}/sourcesanspro-regular-webfont.woff') format("woff");
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215;
}

[... other font-face declarations ...]

Tokens, utilities, and modules

The CSS-Library provides a set of tokens, utilities, and modules that can be used in your project.

Utilities

The utility classes are helpful, single-property classes that can provide more flexibility for inline styling. You can review the utilities in the design system documentation for more information.

Tokens

The tokens are variables that can be used to style your project inline or in your stylesheets. Review the tokens in the design system documentation for more information.

The CSS-Library provides design tokens in a number of formats: CSS, SCSS, and JSON. Review the available token formats in the CSS-Library repository.

We recommend using the CSS custom properties format by loading the CSS file globally just once and using the custom properties in the stylesheets across your application like this:

<link rel="stylesheet" href="@department-of-veterans-affairs/css-library/dist/tokens/css/variables.css">


.your-class {
  background-color: var(--vads-color-base);
}

Modules

While many of the original modules have been converted to web components, some are still available in the CSS-Library. If there is a comparable web component available in the Web Component library, we recommend using that instead.

If you would like to use a module stylesheet, reference this documentation site which imports the CSS Library Sass file modules into the application.scss stylesheet.

Load the Web Component library

The Design System team has developed a library of reusable Web Components that can be used on any HTML page or React application.

This is already handled for the vets-website repository. To get the Web Component library set up in a new project, here is what we recommend:

  • Add the component-library dependency to your node/yarn project:
yarn add @department-of-veterans-affairs/component-library
  • Import the global CSS file:
import "@department-of-veterans-affairs/component-library/dist/main.css";
  • Import the defineCustomElements JS function:
import {
  applyPolyfills, // Only necessary if you wish to support older browsers such as IE11
  defineCustomElements,
} from "@department-of-veterans-affairs/component-library";
  • In the same JS file, call the defineCustomElements function, optionally chained after a call to applyPolyfills:
applyPolyfills().then(() => {
  defineCustomElements();
});

Icons Sprite Sheet

If you’re using a component that requires the icons sprite sheet (e.g. va-icon), the sprite sheet must be loaded from the same origin as your application. By default, the sprite sheet is loaded inside of the components from the /img/sprite.svg path.

The sprite sheet is included in the @department-of-veterans-affairs/component-library package at /dist/img/sprite.svg. We recommend adding that file to your project as part of your build process to ensure you’re receiving the most recent version of the sprite sheet and that it’s available at the correct path.

If you need to override the default sprite sheet path from /img/sprite.svg to a different path within your project, you can do so by calling initIconSpriteLocation as part of the component library initialization and setting the sprite sheet path using globalThis.setVaIconSpriteLocation:

import { initIconSpriteLocation  } from '@department-of-veterans-affairs/web-components';
import {
  applyPolyfills,
  defineCustomElements,
} from '@department-of-veterans-affairs/component-library/src/main';

applyPolyfills().then(() => {
  defineCustomElements();
  initIconSpriteLocation();
  globalThis.setVaIconSpriteLocation('/your/path/to/sprite.svg');
});

Integration Examples

This integration-examples directory contains examples of how to install the VA Design System into different frameworks and build tools outside of vets-website (VA.gov).

Available Examples

Edit this page in GitHub (Permissions required)
Last updated: Jul 11, 2025