Skip to main content

An official website of the United States government

Here's how you know

An official website of the United States government

Here's how you know

Theme:

Design system switcher

Version:

Design system switcher

Theme:

Design system switcher

Version:

Design system switcher

Spacing

The design system uses multiples of 8px for all spacing values: dimensions, padding, and margins. The goal behind this is to achieve a consistent vertical rhythm and to reduce the cognitive load of fiddling with different spacing options.

Usage

  • Use the margin and padding utility classes to change a UI's spacing. These utility classes are named in a way that allows you to use the modifier to calculate the amount of spacing. For example, a margin utility class that adds 16px of spacing would be ds-u-margin--2. We can calculate this by looking at the class's modifier (2) and multiplying that by our multiple: 2 × 8px = 16px
  • If you've imported the design system's CSS file, you can also use the spacer CSS variables, which follow the format --spacer-* where * is a number between 1–7 (i.e. --spacer-4)

Spacing typography

How to use spacers

  • Use spacers that correspond to the header being applied. If you use the heading--lg header, apply a --spacer-5 spacer to the body content below the header.
  • When it comes to content relationships, header sizes should be of equal or smaller size to the body content.
Header sizeVariableValueExample
Heading--sm--spacer-324px
Heading--md--spacer-432px
Heading--lg--spacer-540px
Heading--xl--spacer-648px
Heading--2xl--spacer-756px
Heading--3xlNo variable72px

Examples

Spacing example heading (2xl)

--spacer-7
We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

Spacing example heading (lg)

--spacer-5
We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

Spacing between components

Existing design components in Figma have built-in spacing, including margins and padding.

If you need additional paddings and margins, use spacers to maintain the 8pt rhythm established by the design system.

  • Consider the existing vertical rhythm on Core when making decisions about how to vertically space components.
  • As a general rule, default to 16px (--spacer-2) above and below each component or content area.
  • Avoid spacing larger than --spacer-7 either vertically or horizontally.
  • Avoid spacing smaller than --spacer-half either vertically or horizontally.
  • Use the existing grid to determine horizontal spacing between components. As a general rule, the system uses a 12-column grid with 16px(--spacer-2) gutters.
VariableValueExample
--spacer-half4px
--spacer-18px
--spacer-216px
--spacer-324px
--spacer-432px
--spacer-540px
--spacer-648px
--spacer-756px

Accessibility

Existing components' spacing conforms to accessibility best practices for legibility and interaction.

When creating your own components or layouts, consider these best practices to ensure your content is accessible.

  • Use a minimum of 24px (--spacer-3) between interactive elements.
  • If not using the ds-content class to format text, space between paragraphs of body copy should be two times the font size in use to ensure readability.
    • For example: for a 16px font size (the system's default body copy size), paragraphs should have 32px (--spacer-4) of space beneath or between them.

Learn more