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.
| Sample | Token | Value | Job |
|---|---|---|---|
| 0.5 | 2px | The gap between a field’s icon buttons, the padding around a date picker segment. | |
| 0.75 | 3px | The inset of an icon button inside a field box. | |
| 1 | 4px | A title to its description, the error message under a field, menu padding, the gap between tabs. | |
| 1.5 | 6px | The icon-to-label gap in a small button or chip. | |
| 2 | 8px | The 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.5 | 10px | Inline padding of a small field and a tooltip. | |
| 3 | 12px | Inline 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. | |
| 4 | 16px | Inline padding of a button and a table cell, an alert, --card-spacing. | |
| 5 | 20px | The gap between fields in a form. | |
| 6 | 24px | --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.
| Sample | Token | Value | Job |
|---|---|---|---|
| h-10 | 40px | A table header row. | |
| h-9 | 36px | Default size: button, icon button, field box, toggle group chip, tab. | |
| h-8 | 32px | Small size: button, icon button, field box, chip, and a menu row. | |
| h-5 | 20px | A 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)]".
| Sample | Token | Value | Job |
|---|---|---|---|
| --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-width | none | The 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. |
Closer means related
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
- DoGive 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’tSpace 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’tNudge 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.
- DoChange 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.
- DoPut 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.