Skip to content
flyingsalmon

Spacing

Every space is a step on Tailwind’s 4px scale, and the gap grows with the distance between ideas.

Components use a handful of steps, the same step for the same job everywhere, so two screens built apart still agree. Three surfaces expose their padding as a variable you can override, and one bar height lines the sidebar up with the page header.

Tokens

The scale

One step is --spacing, 0.25rem. These are the steps the components use, with the job each one does.

SampleTokenValueJob
0.52pxThe gap between a field’s icon buttons, the padding around a date picker segment.
0.753pxThe inset of an icon button inside a field box.
14pxA title to its description, the error message under a field, menu padding, the gap between tabs.
1.56pxThe icon-to-label gap in a small button or chip.
28pxThe icon-to-label gap in a button, a checkbox or radio to its label, a label above its field, buttons in an actions row.
2.510pxInline padding of a small field and a tooltip.
312pxInline padding of a field and a small button, a label beside a date picker, stacked radio options, a small alert, a timeline marker to its content.
416pxInline padding of a button and a table cell, an alert, --card-spacing.
520pxThe gap between fields in a form.
624px--dialog-spacing, --timeline-spacing, radio options laid out in a row.

Control heights

Controls come in two heights, so a button, a field, and a chip line up on one row at either size. A table header row and the small marks, a badge, a checkbox, and a radio, keep fixed heights of their own.

SampleTokenValueJob
h-1040pxA table header row.
h-936pxDefault size: button, icon button, field box, toggle group chip, tab.
h-832pxSmall size: button, icon button, field box, chip, and a menu row.
h-520pxA badge, a checkbox, a radio.

Surface variables

Card, dialog, and timeline read their spacing from a variable instead of a prop. Every slot inside the surface uses the same variable, so overriding it on one instance moves every inset together: className="[--card-spacing:--spacing(6)]".

SampleTokenValueJob
--card-spacing--spacing(4)Card padding on every edge and the gap between its slots, so the header, content, and footer line up with the border.
--dialog-spacing--spacing(6)Dialog and drawer padding: the header, body, and footer insets, and where the close button sits.
--timeline-spacing--spacing(6)The gap between timeline items. The connectors that bridge the gap read the same variable.
--bar-height--spacing(18)The band the sidebar header and the first line of a page header share, so the wordmark, the page title, and the title’s actions sit on one centre line.
--page-header-inset--spacing(0)The side padding of the pane a page header sits in. The header bleeds out by it and pads back in, so its bottom rule meets both edges of the pane.
--page-header-max-widthnoneThe widest a page header lets its title and actions run. The row centres inside the header while the bottom rule keeps the full width.
--sidebar-width--spacing(72)The expanded sidebar column. It is set on the root, so a pane beside the sidebar can offset itself by the same width.
--sidebar-width-collapsed--spacing(14)The collapsed rail: the content inset, an item’s padding, and its icon, so the icons stay put as the sidebar collapses.

Inside a field, the label sits one step above the box and an error sits a step below it. Between fields in a form the gap is larger, and the actions row keeps its buttons close together. A title and its description sit tight; the slots of a card sit --card-spacing apart. A reader groups what is near, so the distances say what belongs together.

Usage rules

  • Do
    Give the same job the same space on every screen: a label to its field, one field to the next.Repeated distances are what make two screens built apart feel like one product.
  • Don’t
    Space two unrelated things as closely as two related ones.Equal gaps hide the grouping, so the reader has to work out what goes with what.
  • Don’t
    Nudge one gap between steps to make something fit.A space between steps lines up with nothing around it, and the eye reads it as a mistake.
  • Do
    Change a surface’s density as a whole: every edge and every gap between its parts together.The content keeps lining up with the border, so a denser card still looks deliberate.
  • Do
    Put a button, a field, and a chip of the same size on one row.Controls share their default and small heights, so a row lines up without adjustment.

  • Radius

    The corner scale that sits alongside the spacing scale.
  • Card

    Exposes --card-spacing.
  • Dialog

    Exposes --dialog-spacing.