Consistent spacing creates visual balance that makes the user interface (UI) easier for merchants to scan. Apply consistent spacing to improve the quality of the UI.
The spacing system
All spacing for components and typography is done in increments of 4 pixels. This 4 px value forms the basic unit of measurement for spacing.
Typography doesn’t use a traditional baseline grid. Instead, line heights are set in increments of 4 px and spacing is measured from the edges of the text boxes.
Many components are sized in increments of 20 px to match the line height of body text. This makes it easy to create harmonious arrangements of components and text.
For example, the standard sizes of the avatar component have been chosen to match the line height of body text:
Spacing in code
You can apply spacing in code in several ways:
- Using stylesheets
- Using utility components provided by Polaris React
Applying spacing with stylesheets
If you’re using Polaris with plain CSS, set values in increments of 4px. If
you’re using Polaris’ built-in Sass library, you can use
rem units or access
common values via the
|CSS||Sass (rem function)||Sass (spacing function)|
Applying spacing with components
Use the text container component to wrap and automatically add the correct spacing between a set of paragraphs, lists, or other textual components.
The stack component can be used to arrange arbitrary components in a horizontal row or vertical stack with space in between.
It accepts the same values as the Sass spacing function to control spacing between the items.
How to choose spacing
Use less space between small components, or components that share a close functional relationship.
Use more space between large components, or between components which are less functionally related.
Coordinate small and large values, along with structural components like cards, to create visual groupings of related things. This helps merchants understand the interface and find what they’re looking for.
For screens with specialized layouts, adjust overall spacing based on the density of the content. For example, a simple login screen on desktop display has more room to breathe, so more space can be used.
4px (extra-tight) between icon and text
The button component has this spacing built in.
8px (tight) between buttons
The button group component has this spacing built in.
16 or 20px between form fields:
16px (base) vertically
20px (loose) horizontally
The form layout component has this spacing built in.
20px (loose) padding in cards
16px (base) side padding on small screen
The card component has this built in.
20px (loose) between cards
The card component automatically adds vertical space between it and any preceding card.
For horizontal spacing, use the layout component to create multi-column layouts.
When text is vertically centered inside a component, the top and bottom padding can be any size.
The side padding within pill shapes can also be an odd number to match the shape’s radius.
Allow the length of text to determine the width of components and where they fall horizontally when placed in a row.
Sometimes an element is larger than it appears. Spacing based on the invisible edges of the element will feel wrong. Correct for these optical effects by adjusting the space in 4 px increments until it looks more balanced.
Without optical adjustment, the disclosure icon appears too far from the right edge of the button.
After optical correction, the perceived spacing is more balanced.