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 or between modern and traditional styles.

Scale
Honest UI spacing tokens
PreviewTokenValueUse
--hui-space-12pxHairline gaps and very small optical adjustments
--hui-space-24pxTight inline gaps and compact control padding
--hui-space-38pxIcon-to-label gaps and compact component padding
--hui-space-412pxSmall control padding and related-item gaps
--hui-space-516pxCommon component padding and comfortable gaps
--hui-space-620pxMedium component padding
--hui-space-724pxCard padding and gaps between related groups
--hui-space-828pxLarge control dimensions and generous component spacing
--hui-space-932pxSection padding and common control height
--hui-space-1040pxLarge control height and compact section gaps
--hui-space-1148pxSpacing between distinct content groups
--hui-space-1256pxSmall page-section spacing
--hui-space-1364pxMajor content divisions
--hui-space-1472pxGenerous page-section spacing
--hui-space-1580pxLarge layout separation
--hui-space-1696pxExtra-large page sections
--hui-space-17120pxMaximum spacing in the shared scale

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.