Spacing units

Why multiples of 8?

The number 8 is easily broken down into smaller measurements before it approaches sub-pixel units. Additionally, many popular screen sizes are also divisible by 8.

• Read more about the 8-point grid

Spacing tokens

The VA follows the USWDS spacing unit tokens and then adds additional semantic tokens.

Primitive

Semantic

Layout

Using the spacing units

Use spacing unit tokens to keep spacing consistent throughout VA.gov. Tokens are the preferred approach for all margins, padding, and other spacing dimensions.

When you need a custom value outside the token system, use relative units (rem or em) for layout spacing such as margins, padding, and gaps. While pixels scale with page zoom, they don’t respond to user-set default font sizes in browser settings. Using relative units for layout spacing ensures your design adapts to user preferences, which is required for WCAG 2.2 AA SC 1.4.4 Resize Text. Pixels are still appropriate for non-scaling details like borders and box shadows.

In order to access the unit tokens in your project, you will need to import the variables file into your project. Here is how this site is doing that.

There are two ways of using the spacing tokens in your code.

Output CSS as REM units (recommended)

Use units() to output spacing in rem. This is the recommended approach because rem units scale with user font size preferences and support accessible text resizing.

.foo {
  margin: units(5);
  padding: units(2.5);
}

will compile to:

.foo {
  margin: 4rem;
  padding: 2rem;
}

Output CSS as PX units

Use units-px() only when a pixel value is specifically required, such as for borders or box shadows that shouldn’t scale with text size. For margins, padding, and font sizes, prefer units() to support accessible text resizing.

.foo {
  margin: units-px(5);
  padding: units-px(2.5);
}

will compile to:

.foo {
  margin: 40px;
  padding: 20px;
}