Spacing & shape¶
- MUI
spacing(1) = 8px. Default tospacingmultiples — no ad-hoc pixel values in componentsx. borderRadius = 6globally. Buttons and inputs inherit; chips override to 4 (slightly squarer to read as labels rather than pills).
Proximity tiers — spacing carries meaning¶
The gap between two elements should reflect how related they are. Uniform spacing flattens the visual hierarchy and makes everything read as equally adjacent; tiered spacing groups related elements and separates unrelated ones. Use these four tiers:
| Tier | Gap | Relationship | Examples |
|---|---|---|---|
| Cluster | 4px | Two parts of one unit | Title + subtitle, label + value pair |
| Control | 8px | Within a single control | Field label + helper text (MUI default), icon + label |
| Sibling | 16px | Repeating items of the same kind | Field ↔ field in a stack, row ↔ row in a list |
| Block | 24px | Distinct concerns within the same surface | Header ↔ body, last field ↔ submit, image ↔ caption block |
Section-to-section gaps on a long page (e.g. /design) go larger still — spacing={6} (48px) — because they're crossing topic boundaries, not block boundaries.
Use the tier closest to the relationship, not the one that "looks right" — visual judgment will drift; the tiers won't. If two elements need a tier that doesn't exist (e.g. "between sibling and block"), the right fix is almost always to regroup, not to invent a 20px gap.
Card interior padding¶
- Card content padding: 24px (
p: 3). This matches the block tier so the largest interior gap and the gutter to the edge feel like one rhythm. - Cards that act as a tray for media that bleeds to the edge (e.g. a hero image followed by a text block) use 8px gutter on the media side; text blocks below revert to 24px.
Vertical rhythm in pages¶
- Between top-level sections of a page:
Stack spacing={6}(48px). - Within a section:
Stack spacing={2}(16px) for sibling content,Stack spacing={3}(24px) when the section has multiple distinct blocks. - Page horizontal padding comes from MUI
Container.