Spacing

01Overview

One scale covers component insets, the gaps between elements and the space around sections. It's built on 4px: space-N is N × 4px, so the names match Tailwind's default spacing numbers.

• Whole steps (0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20) are the layout scale: gaps between components, card and panel padding, space between sections.
• Half steps (0-5, 1-5, 2-5, 3-5) add 2px increments below 16px. Use them inside components, where a 4px jump is too coarse for optical balance: button insets, icon gaps, focus offsets.
• The scale stops at 80px. Larger distances are layout decisions (grid, breakpoints), not spacing tokens.

02Tokens

Every spacing token in @nuton/tokens, in generated order: whole steps first, then half steps. The bar shows the value at full size.

03Usage

CSS variables

Load @nuton/tokens/tokens.css once, then reference the variables in any property that takes a length.

.lesson-card {
  display: grid;
  gap: var(--nu-space-3);
  padding: var(--nu-space-5);
}

/* Subtract a 1px border so the outer size stays on the scale (as Input does) */
.space-chip {
  border: 1px solid var(--nu-stroke-soft-200);
  padding-inline: calc(var(--nu-space-3) - 1px);
}

Tailwind

The Tailwind v4 theme and v3 preset in @nuton/tokens expose semantic colours, the type scale, radius, shadows, easing and breakpoints. They don't generate spacing utilities. Reference the variables with Tailwind's arbitrary-value syntax instead. Tailwind's built-in spacing numbers line up with the token names, but they aren't bound to the tokens, so they won't follow a future change to the scale.

<div className="grid gap-(--nu-space-3) p-(--nu-space-5)">
  …
</div>

<div className="grid gap-[var(--nu-space-3)] p-[var(--nu-space-5)]">
  …
</div>

Inside @nuton/ui, a lint rule blocks arbitrary Tailwind values: components set spacing in their CSS through --nu-space-* and their own component variables.

Choosing a token

• Inside a control, use the component's variables (--nu-button-pad-inline, --nu-input-pad-inline). Override them on a wrapper only for a documented exception.
• Related items sit closer than unrelated ones. Field parts are space-1 (4px) apart; actions in a row use space-2 (8px); cards in a grid use space-3 or space-4.
• Insets grow with the control. Bigger controls get bigger insets, and an icon edge sits closer to the border than a text edge (P1).
• Stay on the scale. If a value isn't a token, round to the nearest step. When a border would push a size off the scale, subtract it with calc().

04In use

Spacing decisions in real components. P1, approved at the owner's request, is the clearest example: the padding on buttons and inputs was rebalanced so insets scale with size, while every height stayed the same.

Button insets

<Button size="sm" leadingIcon={<RiAddLine />}>New lesson</Button>
<Button size="md" leadingIcon={<RiAddLine />}>New lesson</Button>
<Button size="lg" leadingIcon={<RiAddLine />}>New lesson</Button>

Heights are measured in the browser (see Button). Figma uses one fixed text inset at every size, so large buttons looked cramped and small ones loose; P1 replaced it with the steps above. Figma still shows the old padding (FC-08).

Input insets

<Field label="Search lessons">
  <Input leadingIcon={<RiSearchLine />} placeholder="Photosynthesis" />
</Field>
<Field label="Search lessons, small">
  <Input size="sm" leadingIcon={<RiSearchLine />} placeholder="Photosynthesis" />
</Field>

Gap between actions

<div className="actions"> {/* gap: var(--nu-space-2) */}
  <Button size="sm" appearance="stroke">Save draft</Button>
  <Button size="sm" trailingIcon={<RiArrowRightLine />}>Publish lesson</Button>
</div>

05Accessibility

Spacing decides how big a target is and how close it sits to the next one. WCAG 2.2 AA (2.5.8 Target size, minimum) asks for targets of at least 24 × 24 CSS pixels.

A smaller target still passes if a 24px circle centred on it doesn't overlap another target or that target's circle. So when a control can't grow, the gap around it has to. space-6 (24px) is the minimum target size, which makes it a useful check: a control plus its share of the surrounding gap should reach it.

• Spacing tokens are in px. They scale with browser zoom, which is what WCAG 1.4.4 and 1.4.10 test.
• Space is never the only grouping cue for meaning: a field's label and hint are tied to the control with aria-labelledby and aria-describedby, not just placed nearby.

You must: keep every target at 24 × 24 or give it enough space around it; check new components with axe's target-size rule.

06Guidelines and related

Do and don't

Related

• RadiusThe other interim dimension scale; corners grow with control size too.
• Layout and responsiveBreakpoints and layering for page-level structure.
• ButtonInsets per size, rebalanced by P1.
• Inputs and fieldsInput padding and the label, control and hint stack.
• Button groupItem spacing and the open 2xs target-size gap (C26).
• Link buttonA padding-free target that relies on surrounding space (C28).