# How to create a UI spacing system

A UI spacing system defines reusable gaps, padding, and margins. Start with a small scale, assign values to relationships such as label-to-field and section-to-section, then test those relationships in real components. Consistent meaning matters more than forcing every measurement onto a grid.

By The Design Project. Updated 2026-10-21.

## What you will make

A spacing token scale and a documented set of layout relationships.

## Before you start

- A form, a card, and a page layout
- Access to the current spacing values
- Real short and long content

## Spacing communicates relationships
A spacing system defines reusable distances between and inside interface elements. Its purpose is to make relationships clear: a label belongs to its field, a group of controls belongs together, and one section is distinct from the next. A tidy numeric scale is useful only when those relationships survive real content.

TDP’s design-system work emphasizes shared foundations that both people and agents can apply. Spacing belongs in that foundation alongside type, color, and component rules. If the documentation only lists numbers, each contributor still has to invent when to use them.

Start with a form, a card, and a page layout. These three specimens reveal component padding, local gaps, and larger section relationships without requiring a complete product redesign.

## Step 1. Audit relationships
Measure the gaps inside a component and between components. A label should appear connected to its field, while unrelated sections need more separation. Record where spacing changes without an obvious reason. Group repeated relationships before deciding which exact values to keep.

## Step 2. Choose a small starter scale
A four-pixel base is a useful example, but it is not a required standard. Start with values that fit your content and platform. Keep the number of choices manageable so a designer can explain why one value applies.

```css
:root {
  --space-1: .25rem;
  --space-2: .5rem;
  --space-3: .75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
  --space-12: 3rem;
}
```

## Step 3. Assign semantic relationships
The table is an example mapping to test, not a universal rule. Record what a token means so people can select it without guessing from a screenshot.

| Relationship | Example value at a 16px root | Reason to test |
| --- | --- | --- |
| Label to field | 8px | Keep the label visibly associated |
| Between fields | 16px | Separate tasks without breaking the group |
| Card padding | 24px | Give content room inside its boundary |
| Between sections | 32px | Communicate a larger change of subject |

## Step 4. Apply tokens to a full layout
Use layout properties such as gap and padding consistently. Compare a compact table, a form, and a content card. A dense interface may need a documented compact variant rather than scattered one-off reductions. Keep interactive hit areas usable; visual gaps and clickable area dimensions are related but different decisions.

## Step 5. Stress-test the layout
Try a long translation, multiline error, narrow viewport, and increased text size. Let content determine height where possible. If the system only works with short placeholder text, revise the component structure. Use the spacing demo to compare density, then make the final decision in your actual product.

## Worked example: make a form easier to scan
Imagine every gap in a form is the same size. The label, hint, input, and next field all appear equally related. A clearer layout uses smaller gaps within a field group and larger gaps between groups. The exact values can vary, but the relationship should remain recognizable.

| Relationship | Intended meaning | Review question |
| --- | --- | --- |
| Label to control | These belong together | Is the label closer to its own field than the next one? |
| Control to hint or error | This text explains this control | Does wrapping preserve the association? |
| Field group to field group | Separate inputs in one task | Can users scan the form without losing place? |
| Section to section | A new group of decisions | Is the grouping visible without extra decoration? |
| Content to container edge | Comfortable enclosure | Does the card feel cramped at narrow widths? |

Use these relationships to choose from your scale. Do not assign a number merely because it is the next multiple in a sequence.

## Build a small scale and name important uses
A base increment can make implementation easier, but exceptions may be justified by optical alignment, borders, or component behavior. Record the reason for an exception instead of pretending every measurement follows a strict grid.

Keep primitive spacing values separate from higher-level roles when the product benefits from that distinction. A card-padding role can change at a breakpoint without requiring every card consumer to choose a new raw value.

```css
:root {
  --space-2: .5rem;
  --space-3: .75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --field-group-gap: var(--space-4);
  --section-gap: var(--space-6);
}
```

This is a starter example. Test it with your font, component sizes, and content before adopting it as a product rule.

## Review density separately from consistency
A dense table and a spacious onboarding screen can both use a consistent system. They serve different tasks and may need different approved density modes. Explain those modes rather than treating one screen as an exception to everything else.

Avoid solving density only by reducing text size. Consider column count, progressive disclosure, grouping, and whether every piece of metadata needs equal emphasis. Space and hierarchy work together.

## Test long content and responsive composition
Replace short labels with realistic long ones, add an error message, and inspect the smallest supported layout. Fixed heights and tightly coupled margins can break when text wraps. Prefer layout relationships that allow content to grow.

Check the entire flow after changing a token. A larger field gap can improve one form while pushing important actions below an unexpectedly long region elsewhere. Review consumers of shared values rather than approving the token in isolation.

## Document a spacing decision with a specimen
Show the form and card examples with named relationships, not only a ruler diagram. A contributor should be able to match a new layout to an existing pattern and explain any deviation.

When an agent introduces new spacing, ask it to identify the intended role and compare with the approved specimen. This produces a more useful correction than “make it consistent.” Connect the specification to [design.md](https://designproject.io/resources/guides/write-design-md/) so future UI work can find it.

## Completion checklist
- Repeated relationships use named values.
- Compact variants have an explicit purpose.
- Containers expand for realistic text.
- Narrow layouts preserve grouping and reading order.
- Exceptions are documented with a reason.

## Common questions
### Must every measurement be a multiple of four or eight?
No. A scale reduces unnecessary variation. Optical adjustments and component constraints may justify exceptions; explain them instead of enforcing a grid mechanically.
### Are margin and padding interchangeable?
Padding is inside an element’s boundary; margin separates it from surrounding elements. Use the property that expresses the intended relationship and inspect how it behaves in the chosen layout.

## Sources and related reference
- [MDN: the CSS box model](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model)
- [W3C: text spacing and adaptable layouts](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html)


## Related guides

- [How to create a UI type scale with CSS examples](https://designproject.io/resources/guides/create-ui-type-scale/)

- [Font weight, border width, and icon strokes: a UI guide](https://designproject.io/resources/guides/font-weight-borders-strokes/)

- [How to write a design.md file: a step-by-step guide](https://designproject.io/resources/guides/write-design-md/)

[Product design glossary](https://designproject.io/resources/glossary/)

Canonical: https://designproject.io/resources/guides/create-spacing-system/

## Keep learning

- [Font weight, border width, and icon strokes: a UI guide](https://designproject.io/resources/guides/font-weight-borders-strokes/)
- [Product design glossary: 44 terms explained](https://designproject.io/resources/glossary/)
- [Extract a design system](https://designproject.io/resources/skills/extract-design-system/)