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
Spacing example heading (lg)
--spacer-5
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 (