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.

Documentation

Documentation for developers

How to install Formation and use with your project.

Installation

If you are working in the vets-website repository, you can skip straight to the developer documentation. Otherwise, proceed below.

We are still improving how you can install Formation into your project. In the meantime, these instructions should help get you to get started with what is currently available.

How you implement Formation into your project depends on how your project is structured and your preferences. The easiest way to get started is by using npm. We will have a direct download available in the future.

Install Formation into your project

We recommend using npm to install the formation package into your project.

$ npm install --save @department-of-veterans-affairs/formation

This line installs Formation as a dependency. You can use the compiled files found in the node_modules/@department-of-veterans-affairs/formation/dist directory.

If you would like to use the un-compiled Sass files instead, you can find those in the node_modules/@department-of-veterans-affairs/formation/sass directory.

Note: We do not recommend editing files in the node_modules directory because once the packages are updated, you will lose all of your edits. We recommend using gulp to move files from your node_modules directory into your project folders. To see how this documentation site is moving files, look at the gulp build script.

Place the contents of the dist folder in your project. In this example, we placed the formation dist contents into assets/formation/, but you can place them anywhere in your project that you like. The fonts/ and img/ directories should remain relative to formation.min.css.

project-root
├── assets/
├──────├──formation/
├──────├──────├──────fonts/
├──────├──────├──────img/
├──────├──────├──────formation.js
├──────├──────├──────formation.min-css

If you prefer to change the location of the fonts/ and img/ directories relative to formation.min.css, set the following variables in your project:

$formation-asset-path: '../assets';
$formation-image-path: "#{$formation-asset-path}/img";
$formation-font-path: "#{$formation-asset-path}/fonts";

The example above is what is used on VA.gov, but you can customize this for your project.

Sass functions, variables, and interactive components

If you would like to use the Sass functions, such as for spacing, and variables in your project, you can either move the necessary files with gulp, or import the files from your project scss. This depends greatly on your project structure. This documentation site imports Formation’s Sass files in its application.scss.

CSS

When naming components, be sure to use Formation’s naming conventions.

Searchable selectors

Many of the features in Sass make it easy to use shorthand to reduce repetitive typing and write cleaner .scss files. However, this makes using search features in GitHub or text editors much more difficult because it is not always clear how the shorthand was written; finding the right query requires guesswork.

Do

Write out the full name of each selector.

.alert {
}

.alert--warning {
}

.alert--error {
}

Don’t

Don’t use Sass shorthand features, such as nesting with ampersands often used with BEM syntax.

.alert {
  &--warning {
  }
  &--error {
  }
}

Modifying components

Sometimes you will need to modify certain default properties of a component depending on how it scaffolds with nearby elements. Use utilites instead of writing new CSS.

Do

Use utility classes to override default properties. This allows components to maintain a well-defined baseline of properties.

HTML

<div class="a-container">
  <div class="a-component vads-u-margin-top--3"></div>
</div>

Don’t

Don’t change CSS properties based on a container or other context. This makes baseline properties for components unclear.

HTML

<div class="a-container">
  <div class="a-component"></div>
</div>

CSS

.a-container .a-component {
  margin-top: 24px;
}

Implementing design work

When a designer hands off work, it is vital to work through potential implications that design may have on Formation. Are there any new variations on components? Are there any new components not present on this site? For more on that process, read about how to contribute.

In general, some rules for implementing design work include:

  • Use spacing units instead of hard-coding pixel values for margins and padding
  • Use Sass variables for colors instead of hex codes
  • Discuss reusability of new design components and where is the most appropriate home for CSS and JS
  • Use the Formation naming convention
  • Do not use ID selectors