Spacing tokens separate elements inside components and layout blocks — both horizontally, and vertically.
Our spacing scale helps make things consistent, while also making content easier to scan in a screen layout.
- Use tokens coming from the design system.
- Use semantic tokens instead of token values.
- Don’t use custom or hard-coded values.
Horizontal spacing refers to how elements distribute inside a component — for example, avatars from texts and actions. It also applies to cases where components go next to each other in a given layout.
The smallest token is used on error messages on inputs, to space the icon from the text that goes alongside it.
Most of the inputs use an 8px horizontal spacing to separate the content inside the field.
Small interactive components use an 8px separation to space the icon and text inside a component.
More complex components that may host a series of elements such as icons, actions, titles and descriptions, use a separation of 16px. This is so they have space to breathe, and their content is easier to read.
Vertical spacing refers to how sections of a screen separate within a layout. It also applies to the spacing between components, and elements inside a component.
When stacking content that's closely related, use very little vertical spacing.
Remember that some components which stack (such as items on a list) already include top and bottom padding within the component itself.
When a layout has different subsections on the same screen, consistent vertical spacing helps show all subsections are related. These subsections are usually separated by the section header component.
Headings are surrounded by different elements, top and bottom. Spacing will be different depending on what those elements are. In some cases, components below headings already include some padding, so separation needs to be adjusted accordingly.
Separation between content and other main wrappers allows information to be visible and distinct, and makes sure it doesn’t clash with the rest of the content.