Space is the distance between objects in your design. It should be used to complement the purpose of a page, by creating hierarchy and helping the content become more useful and understandable.

A visual example of a polaris unit

Spacing must...

Illustrations of blocks representing each principle

1. Create visual groupings

The more items are related, the closer they should be to each other.

2. Complement function

Use tighter spacing for large amounts of information, use looser spacing for more focused content.

3. Be harmonious

Use Polaris space tokens in a way that is consistent with the rest of the experience.

Spacing tools

Polaris space units

All measurements used across the experience (space, width, height, etc) must reference Polaris space units to guarantee visual consistency and balance.

A visual example of a polaris unit

Space scale

ValueSpacepx valuerem value
1 (base)--p-space-140.25

Polaris units are more dense at a small scale, and less so as dimensions increase. This is intentional to provide a good range to work with, but you must be deliberate in the units you decide to pair. We encourage designing with rhythm and contrast to achieve clear visual hierarchy. This often means skipping at least one unit in the scale when you’re pairing different spaces.

Examples of different variations of spacing

Repeating the same amount of spacing (left) and using more variation (right).

Column grid

The column grid is meant to give teams agency for page layouts, while still providing low level constraints that ensure consistent pages across the experience. This means teams should feel empowered to experiment with layout, as long as they use the column grid as a grounding element.


The grid adapts to the viewport width. The amount of columns will change depending on how much space there is. This is a recommendation for how much should be displayed horizontally. Less columns means less content.

Screen sizeColumnsMarginGutterNavigation
Small tablets

The grid is meant to serve as a point of reference for page level design and alignment, but this doesn’t need to apply to component level layouts.

Essentials for designing with space

Gestalt principles

The perception of any given page goes beyond the individual elements presented, and the space between them. People’s perception is heavily influenced by their own expectations and motivations. When designing, it’s key to consider that people look for patterns, and will always perceive things in their simplest form. For instance, a bunch of similar items stacked on top of each other will likely read as a list.

Different types of list items, such as menus, popovers, and dropdowns

People look for patterns instinctively, and they lean of visual cues like:


Grouping things based on physical appearance (shape, color, size, orientation).

Index table


Grouping things based on distance between objects.

Customers and orders page


Grouping things based on the way they are arranged.

Tag multiselect popover and media card

Shadows inside popovers act as visual cues to indicate additional content when scrolled (left). Cards placed horizontally in a media carousel communicates related topics (right).


Grouping things that are implicitly enclosed by a larger object.

Order details page

Common fate

Grouping things based on how they move.

Common Region

Grouping things that are explicitly enclosed by a larger object.

Customer details card

Because people perceive these instinctively, we can use them as tools to create hierarchy, visual rhythm, and guide the user's eye to what’s important.


Alternating between objects and space creates a pattern. Repeated patterns create visual rhythm, which can be used to effectively direct the viewer’s attention. Anything can establish rhythm: space, typography, icons, color, shape, and size.

Like in music, different types of rhythm serve a different purpose, in design there’s three worth highlighting:

Example of data table

Regular rhythm is predictable, which makes it a useful way to organize large sets of objects that have the same level of importance.

Location profile page

Flowing rhythm is organic, and it can bring a high level of scannability to something that would be otherwise a random collection of objects.

Home page with progressive disclosure card

Progressive rhythm is a gradual progression, and is very effective in giving the eye a path to follow, along the progression. This is great to establish hierarchy and aid the user through a series of steps.

Rhythm plays another job in designs, it’s the norm that enables the introduction of variation and points of attention, otherwise known as contrast.


The overall perception people get from the space between information as a whole is density. It can range from tight to loose, and there is a very different purpose for each end of the spectrum.

Examples showign tigher versus looser spacing

Tighter spacing (left) makes it easier to scan and comprehend large sets of data, like lists and tables. It also naturally enables one to fit more elements in a given page. Looser space (right) can help attract the user attention and make a layout feel more user-friendly.


Contrast is meant to create sticking points that help make content easy to scan, highlight important pieces of information, or just to give viewers a moment to breathe.

Marketing page and empty state

Highlights (left): Callout cards are used to encourage merchants to take an action related to a new feature or opportunity.

Breather moment (right): Empty states provide explanation or guidance to help merchants progress.

Contrast can play a role at very different levels, but it must be used sparingly, otherwise its effect gets diluted.

Examples on the analytics page to show contrast

Home feed overview (left) and location profile analytics (right).

Optical adjustment

Sometimes software will say two objects are aligned, or that they have the same size, but visually they don’t feel like that. This happens because computers aren’t great at perceiving visual weight or simultaneous color contrast, so we can’t fully rely on them to create balanced compositions.

That means designers must make optical corrections, using Polaris units until the space feels balanced. Some things to keep an eye out for:

Visual weight ≠ Size

Two things can have the same size, but feel unbalanced.

Before and after comparison of optical adjustment applied to a button

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.

Before and after comparison of optical adjustment applied to an icon

The square icon seems larger compared to the circle icon without optical adjustment, however, they in fact have the same size and diameter. The shapes look visually closer to each other after decreasing the size of the square.

Colors affect each other

Two things can have the same colour, but feel unbalanced.

Before and after comparison of applying the same colour versus slightly different colours to a banner component