# Spacing

Our spacing system exists to support the foundational visual design principle of
[proximity-based grouping:](https://www.nngroup.com/articles/gestalt-proximity/)

> Using varying amounts of whitespace to either unite or separate elements is
> key to communicating meaningful groupings.

In the shortest, simplest terms: the closer two elements are related, the
tighter the spacing between them should be.

With this in mind, let's start small and work our way up.

## Design & usage guidelines

### Minuscule and Smallest

At their respective sizes (`1px` and `2px` equivalent), these values should
mostly be used to provide optical adjustments where an element is visually
misaligned.

### Smaller

The `smaller` spacing value can be used between contents of a single component.
For example, see the spacing between an Icon and the label inside of a
[Button.](../Button/Button.md)

### Small

Sibling items within a container can be separated by the `small` value to
reflect their relation to each other. An example would be the spacing between
[Chips in a selection group.](../Chips/Chips.md)

### Slim

Use `slim` spacing when you don't quite need a `small` space, but `base` is just
too much. This is often useful for optically balancing the internal padding of a
UI element.

### Base

Use `base` as the default spacing in larger content containers with multiple
children of their own, such as [Card.](../Card/Card.md)

`Base` should also be used as the default starting point for spacing
form elements.

### Large

Use `large` spacing for higher-level "parent" containers.
[Modal](../Modal/Modal.md) uses `large` spacing in its header and around the
edges to give itself a bit more prominence as a standalone view, in a similar
manner to [Page](../Page/Page.md).

`Large` can also be used to help give a "floating" element some clear separation
from the edge of the viewport, as seen in [Toast](../Toast/Toast.md).

### Larger

`Larger` doubles the value of `base` to very clearly delineate two groups of
content. It can be useful if you have a long list of mixed content types that
need to be broken up.

### Largest

`Largest` is useful for giving content-rich containers ample breathing room to
create hierarchy. When the parent has such generous spacing, it allows for the
children to leverage a broader range of techniques for grouping amongst
themselves.

### Extravagant

`Extravagant` is used infrequently in Jobber’s web and mobile applications, but
can be useful for lower-density consumer applications like websites.

***

## Implementation

### Content

Use the [Content component](../Content/Content.md) for any instances where you
need uniform spacing between elements.

Content can set its spacing to any of the spacing token values; follow the
guidelines above as needed.

### Values

You can use spacing tokens directly in your stylesheets using the values below.

| Name                  | Visual | Value |
| :-------------------- | :----- | :---- |
| `--space-minuscule`   |        |       |
| `--space-smallest`    |        |       |
| `--space-smaller`     |        |       |
| `--space-small`       |        |       |
| `--space-slim`        |        |       |
| `--space-base`        |        |       |
| `--space-large`       |        |       |
| `--space-larger`      |        |       |
| `--space-largest`     |        |       |
| `--space-extravagant` |        |       |