Spacing
Basalt UI uses a 4px base unit with a restrictive spacing scale. Only defined values are available—this intentional limitation forces consistency and prevents arbitrary spacing that leads to visual chaos.
Spacing Philosophy
4px Base Unit
All spacing values are multiples of 4px. This creates a harmonious, predictable rhythm throughout the interface and aligns with common screen pixel densities.
Restricted Scale
Unlike default Tailwind, Basalt UI only provides specific spacing values. Values like 7, 9, 11, 13-15, and others are intentionally omitted to prevent arbitrary spacing and maintain visual consistency.
Consistency Over Flexibility
A limited spacing scale ensures every component uses the same rhythm. This creates visual harmony and makes layouts feel intentional rather than arbitrary.
Spacing Scale
Common Use Cases
p-2 Small internal padding (8px)
p-4 Default padding (16px)
p-6 Comfortable padding (24px)
p-8 Large padding (32px)
gap-2 Tight spacing between items (8px)
gap-4 Default gap (16px)
gap-6 Comfortable gap (24px)
gap-8 Large gap (32px)
m-4 Small external margin (16px)
m-8 Default margin (32px)
m-12 Section margin (48px)
m-16 Large margin (64px)
Spacing in Action
Tight padding (p-2)
Default padding (p-4)
Comfortable padding (p-6)
Large padding (p-8)
Small gap (gap-2)
Default gap (gap-4)
Comfortable gap (gap-6)
Large gap (gap-8)
Stack components use margin-top on children (except first) to create consistent vertical rhythm
What's Missing and Why
Missing Values
p-7 p-9 p-11 p-13 p-14 p-15 p-17 p-18 Design Rationale
The gaps in our spacing scale are intentional. They prevent the "pixel-perfect" trap where every component needs unique spacing values.
If you need p-7 (28px):
Ask yourself: "Is this meaningfully different from p-6 (24px) or p-8 (32px)?" Usually, the answer is no.
If you need p-15 (60px):
Use p-16 (64px) instead. The 4px difference won't be noticeable to users, but consistency across components will be.
If you really need a custom value:
Consider if this represents a new semantic spacing level that should be added to the design system itself.
Usage Guidelines
- • Use spacing values from the defined scale (0, 1, 2, 3, 4, 5, 6, 8, 10...)
- • Favor p-4 (16px) and p-6 (24px) for most internal padding
- • Use gap-4 (16px) for most flexbox/grid layouts
- • Use larger values (12, 16, 20, 24) for section spacing
- • Use smaller values (1, 2, 3) for tight spaces and compact UIs
- • Maintain consistent spacing patterns within related components
- • Don't use arbitrary spacing values (p-[13px], m-[27px])
- • Don't use undefined scale values (p-7, p-9, p-11, etc.)
- • Don't mix spacing systems (rem + px + arbitrary values)
- • Don't obsess over 4px differences—use nearest defined value
- • Don't create one-off spacing values for individual components
- • Don't ignore the scale—it exists to maintain consistency
Implementation
Use spacing variables directly in custom styles
.my-component {
padding: var(--spacing-4); /* 16px */
margin-bottom: var(--spacing-8); /* 32px */
gap: var(--spacing-6); /* 24px */
}
.my-section {
padding-top: var(--spacing-16); /* 64px */
padding-bottom: var(--spacing-16);
}
.my-card {
padding: var(--spacing-6);
margin: var(--spacing-4);
} Use utility classes for rapid development
<!-- Padding --> <div class="p-4">16px padding all sides</div> <div class="px-6 py-4">24px horizontal, 16px vertical</div> <!-- Margin --> <section class="mb-16">64px bottom margin</section> <!-- Gap (flexbox/grid) --> <div class="flex gap-4">16px gap between items</div> <div class="grid gap-6">24px gap between cells</div> <!-- Space (vertical stack) --> <div class="space-y-4">16px between children</div>