Spacing
Consistent spacing creates visual balance that makes the user interface easier for users to scan. Apply consistent spacing to improve the quality of the UI. All spacing for layouts and components is done in increments of 4 pixels. This 4px value forms the basic unit of measurement for spacing both vertically and horizontally. Where necessary, 2px can be used for more flexibility when making detailed smaller adjustments. We use incrementally measured spacing to create harmonious arrangements of components and text. This gives elements a predictable rhythm and makes the experience feel intentional and well designed. Beyond mathematical precision, spacing also reacts to the objects it surrounds — giving more space to large objects, less to small. Optical adjustments can be made if an element looks off. Typography doesn't use a traditional baseline grid. Instead, line heights are set in increments of 4px and spacing is measured from the edges of the text boxes. When laying out pages, use less space between small components or components that share a close functional relationship. Use more space between large components or between components which are less functionally related — for example, on the outer edges or between sections. Common padding values: 4px between icon and text, or field and error message text (built into components). 8px between buttons (built into the button group component). 16px vertically between form elements. 20px is the padding used in many components to give space to the content.
Usage Guidance
When to use
- +Apply consistent spacing to create visual balance and rhythm.
- +Use the 4px spacing system for all padding, margins, and gaps.
- +Use the common padding values (4px, 8px, 16px, 20px) for layout consistency.
When not to use
- −Don't use arbitrary pixel values outside the 4px system.
- −Don't use spacing values that don't align to the 4px grid (use 2px only for fine adjustments).
Examples
Code Samples
4px spacing system
All spacing is done in increments of 4 pixels. This 4px value forms the basic unit of measurement. Where necessary, 2px can be used for fine adjustments. The visual below shows how common spacing values translate to actual padding around a fixed-size element.
<div className="flex flex-col gap-3">
{[
{ cls: "p-0.5", label: "2px (p-0.5) — fine adjustment" },
{ cls: "p-1", label: "4px (p-1) — icon-to-text, field-to-error" },
{ cls: "p-2", label: "8px (p-2) — between buttons" },
{ cls: "p-4", label: "16px (p-4) — between form elements" },
{ cls: "p-5", label: "20px (p-5) — component content padding" },
].map((item) => (
<div key={item.cls} className="flex items-center gap-4">
<div className={`${item.cls} bg-blue-100 border border-blue-300 rounded`}>
<div className="bg-blue-500 rounded h-4 w-4" />
</div>
<span className="text-sm text-gray-600">{item.label}</span>
</div>
))}
</div>Common padding values
The Breeze spacing system defines four common padding values that cover the most frequent use cases: | Value | Usage | |---|---| | 4px | Between icon and text, or field and error message text. Built into components. | | 8px | Between buttons. Built into the button group component. | | 16px | Vertically between form elements. | | 20px | The padding used in many components to give space to the content. |
<div className="flex flex-col gap-6">
<div>
<p className="text-xs font-medium text-gray-500 mb-2">4px — icon to text</p>
<div className="flex items-center gap-1 text-sm text-gray-700">
<Icon icon="calendar" size={16} />
<span>March 6, 2026</span>
</div>
</div>
<div>
<p className="text-xs font-medium text-gray-500 mb-2">8px — between buttons</p>
<div className="flex gap-2">
<Button buttonType="transparent" compact>Cancel</Button>
<Button buttonType="primary" compact>Save</Button>
</div>
</div>
<div>
<p className="text-xs font-medium text-gray-500 mb-2">16px — between form elements</p>
<div className="flex flex-col gap-4 max-w-xs">
<input className="w-full border border-gray-300 rounded px-3 py-2 text-sm" placeholder="First name" />
<input className="w-full border border-gray-300 rounded px-3 py-2 text-sm" placeholder="Last name" />
</div>
</div>
</div>Laying out pages
Spacing is used to lay components on a page in a consistent and balanced way. Use less space between small components or components that share a close functional relationship. Use more space between large components or between components which are less functionally related — for example, on the outer edges or between sections.
<Card>
<CardHeader>Page layout spacing</CardHeader>
<div className="p-5 flex flex-col gap-6">
{/* Related group — tighter spacing (gap-3) */}
<div className="flex flex-col gap-3">
<p className="text-xs font-medium text-gray-500">Related items — gap-3 (12px)</p>
<div className="bg-gray-50 rounded p-3 border border-gray-200">
<p className="text-sm text-gray-700">Closely related item A</p>
</div>
<div className="bg-gray-50 rounded p-3 border border-gray-200">
<p className="text-sm text-gray-700">Closely related item B</p>
</div>
</div>
{/* Separate section — wider spacing (gap-6) */}
<div className="flex flex-col gap-3">
<p className="text-xs font-medium text-gray-500">Separate section — more space above</p>
<div className="bg-blue-50 rounded p-3 border border-blue-200">
<p className="text-sm text-blue-700">Unrelated section content</p>
</div>
</div>
</div>
</Card>Guidelines
Do
- ✓Use 4px increments for all spacing values.
- ✓Use less space between closely related components, more between unrelated ones.
- ✓Use 4px between icon and text, 8px between buttons, 16px between form elements, 20px for component padding.
- ✓Set line heights in increments of 4px.
- ✓Use Tailwind gap utilities on flex and grid containers rather than margin on individual children.
Don't
- ✗Don't use spacing values outside the 4px system without good reason.
- ✗Don't use large spacing within compact components.
- ✗Don't mix spacing scales in the same visual group.