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.
The preview has been updated.
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.
The preview has been updated.
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.
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.
ShareBest practices
- All else equal, use margin instead of padding.
- All else equal, use bottom spacing instead of top spacing.
