How to create a UI spacing system

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.

: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.

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.

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.

: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 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
• W3C: text spacing and adaptable layouts