Space | Foundations

Space is used to bring structure and hierarchy to pages. Proper spacing enhances readability, guides user flow, and creates a clean, uncluttered interface.

We recommend that you do not alter the default spacing on SWAN components, as this may cause issues with the components' innate margin or padding that they may need for their internal layout. Instead, if you want to create space between two elements, we recommend that you wrap one of them in the Box component, and put the margin or padding onto the Box. Use Grid to assist structuring page content horizontally.

Space decisions are stored in design tokens which sync between code and Figma. All space-related design tokens start with the word space.

See the All Tokens page for a full list of space tokens.

Semantic space

A new concept introduced with in SWAN 3.3, semantic space brings more structured usage guidelines to common spacing needs. Designers can use semantic space variables in Figma, and engineers can use semantic space via props or tokens.

Scale

The space scale is designed to be used between and within components using margin and padding. It should not be for non-space related styling such as widths and heights. Note that the space scale has smaller values in Compact mode.

Compact mode

Compact mode increases the overall density of your page, from the space between sections to padding within components.

For more information, see Modes.

Props

Space contains two categories of core props: margin, and padding. Like other core props, the allowed values for these props align with our tokens. Both semantic and scale values can be used.

<Box px="4" mb="between-sections" />

<Box px="4" mb="between-sections" />

Space can be set in 1, 2, or 4 dimensions, similar to their shorthand CSS equivalents. Multiple props can be added to the same component, but setting multiple props that change the same dimension is not advised.

The full list of space-related props and their allowed values are:

Prop	Allowed values
margin / m	1-12, auto
marginX / mx	1-12, auto, between-actions, to-actions
marginY / my	1-12, auto, between-sections, between-subsections, between-actions, to-actions
marginTop / mt	1-12, auto, between-sections, between-subsections, between-actions, to-actions
marginRight / mr	1-12, auto, between-actions, to-actions
marginBottom / mb	1-12, auto, between-sections, between-subsections, between-actions, to-actions
marginLeft / ml	1-12, auto, between-actions, to-actions
padding / p	1-12
paddingX / px	1-12
paddingY / py	1-12
paddingTop / pt	1-12
paddingRight / pr	1-12
paddingBottom / pb	1-12
paddingLeft / pl	1-12

In the table above, "x" sets the x-axis (both left and right), while "y" sets the y-axis (both top and bottom).

The Vanilla API follows the format of swan-[shorthand property]-[size], e.g. swan-mt-2.

Responsive

All props support responsive values, allowing for different values on different screen sizes.

<Box px={{ xs: 3, sm: 4, md: 5 }} py={{ xs: 4, md: 6, lg: 4, xl: 7 }} />

<Box px={{ xs: 3, sm: 4, md: 5 }} py={{ xs: 4, md: 6, lg: 4, xl: 7 }} />

Best practices

All else equal, use margin instead of padding.
All else equal, use bottom spacing instead of top spacing.