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 beds-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 | |
Heading--md | --spacer-4 | 32px | |
Heading--lg | --spacer-5 | 40px | |
Heading--xl | --spacer-6 | 48px | |
Heading--2xl | --spacer-7 | 56px | |
Heading--3xl | No variable | 72px |
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.
Variable | Value | Example |
---|---|---|
--spacer-half | 4px | |
--spacer-1 | 8px | |
--spacer-2 | 16px | |
--spacer-3 | 24px | |
--spacer-4 | 32px | |
--spacer-5 | 40px | |
--spacer-6 | 48px | |
--spacer-7 | 56px |
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.
- For example: for a 16px font size (the system's default body copy size), paragraphs should have 32px (