Skip to documentation content

Spacing

Use Honest UI's 17-step spacing scale for consistent component sizing, padding, gaps, and page layout.

Honest UI uses one spacing scale for component details and larger layouts. The 17 steps run from 2px to 120px, which keeps common values easy to recognize while leaving enough range for page-level composition.

Spacing tokens are theme-independent. They do not change between light and dark themes.

To make a whole section tighter or roomier without choosing new steps by hand, use a density scope.

Scale

Honest UI spacing tokens
PreviewTokenValue
--hui-space-1Hairline gaps and very small optical adjustments2px
--hui-space-2Tight inline gaps and compact control padding4px
--hui-space-3Icon-to-label gaps and compact component padding8px
--hui-space-4Small control padding and related-item gaps12px
--hui-space-5Common component padding and comfortable gaps16px
--hui-space-6Medium component padding20px
--hui-space-7Card padding and gaps between related groups24px
--hui-space-8Large control dimensions and generous component spacing28px
--hui-space-9Section padding and generous component spacing32px
--hui-space-10Comfortable-density control height and compact section gaps40px
--hui-space-11Spacing between distinct content groups48px
--hui-space-12Small page-section spacing56px
--hui-space-13Major content divisions64px
--hui-space-14Generous page-section spacing72px
--hui-space-15Large layout separation80px
--hui-space-16Extra-large page sections96px
--hui-space-17Maximum spacing in the shared scale120px

Choose a step

Start with the relationship between elements, not the number itself:

RangeRelationshipTypical use
1–3Very closeIcon details, inline content, dense controls
4–7RelatedComponent padding, form-field parts, card content
8–11GroupedComponent groups, panels, compact sections
12–17SeparatePage sections and major layout divisions

Repeated relationships should use repeated tokens. For example, if every field pairs a label and description with --hui-space-2, keep that relationship stable even when the field appears in a larger layout.

Tailwind usage

Use a spacing variable anywhere Tailwind accepts an arbitrary length:

<form className="grid gap-[var(--hui-space-7)]">
  <div className="grid gap-[var(--hui-space-2)]">
    <label htmlFor="name">Project name</label>
    <input id="name" />
  </div>

  <div className="mt-[var(--hui-space-5)] flex flex-wrap gap-[var(--hui-space-3)]">
    <Button>Save</Button>
    <Button variant="secondary">Cancel</Button>
  </div>
</form>

Tailwind v4 shorthand such as gap-(--hui-space-7) is equivalent. Use the explicit gap-[var(--hui-space-7)] form when matching the copied Honest UI source.

Practical guidance

  • Use logical properties such as margin-inline and padding-block when direction or writing mode may change.
  • Do not use spacing alone to communicate grouping. Headings, landmarks, borders, and labels should make the structure clear too.
  • A token can size a control, but interactive targets still need to meet the product's target-size requirements. Add invisible target padding where a compact visual control must remain easy to operate.
  • At narrow widths and high zoom, allow groups to wrap or stack instead of shrinking gaps and text until they become difficult to use.
  • Use an explicit pixel value only when it represents a real exception, such as a one-pixel border—not as a second spacing scale.