# 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](/utilities/margin/) and [padding](/utilities/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 size  | Variable        | Value | Example                                                      |
| ------------ | --------------- | ----- | ------------------------------------------------------------ |
| Heading--sm  | `--spacer-3`    | 24px  | <div class="ds-u-fill--secondary example-spacer-3"></div>    |
| Heading--md  | `--spacer-4`    | 32px  | <div class="ds-u-fill--secondary example-spacer-4"></div>    |
| Heading--lg  | `--spacer-5`    | 40px  | <div class="ds-u-fill--secondary example-spacer-5"></div>    |
| Heading--xl  | `--spacer-6`    | 48px  | <div class="ds-u-fill--secondary example-spacer-6"></div>    |
| Heading--2xl | `--spacer-7`    | 56px  | <div class="ds-u-fill--secondary example-spacer-7"></div>    |
| Heading--3xl | No variable     | 72px  |                                                              |

## 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  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](/foundation/layout-grid/layout-grid/) to determine horizontal spacing between components. As a general rule, the system uses a 12-column grid with 16px(`--spacer-2`) gutters.

| Variable        | Value | Example                                                      |
| --------------- | ----- | ------------------------------------------------------------ |
| `--spacer-half` | 4px   | <div class="ds-u-fill--secondary example-spacer-half"></div> |
| `--spacer-1`    | 8px   | <div class="ds-u-fill--secondary example-spacer-1"></div>    |
| `--spacer-2`    | 16px  | <div class="ds-u-fill--secondary example-spacer-2"></div>    |
| `--spacer-3`    | 24px  | <div class="ds-u-fill--secondary example-spacer-3"></div>    |
| `--spacer-4`    | 32px  | <div class="ds-u-fill--secondary example-spacer-4"></div>    |
| `--spacer-5`    | 40px  | <div class="ds-u-fill--secondary example-spacer-5"></div>    |
| `--spacer-6`    | 48px  | <div class="ds-u-fill--secondary example-spacer-6"></div>    |
| `--spacer-7`    | 56px  | <div class="ds-u-fill--secondary example-spacer-7"></div>    |

## 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

- [The 8-Point Grid](https://spec.fm/specifics/8-pt-grid)