● Foundations / Spacing
Spacing.
Spacing here is deliberate and repeatable. The system uses a shared 4px-based scale so layout, components, and content all move with the same rhythm.
How spacing behaves here
The system uses a restrained spacing scale instead of treating distance as an ad hoc styling decision. That keeps page structure, content stacks, and component internals feeling related.
In practice, the codebase repeats a small set of values across layout and UI: tight gaps for navigation and controls, mid-range spacing for content rhythm, and larger tokens for section and page framing.
Source of truth
Spacing is documented as explicit tokens, even though it maps to Tailwind's default scale. That makes reviews easier and keeps the system opinionated about which values are valid.
Scale roles
The token scale is numerical, but its use is semantic. These ranges describe how the values tend to behave across the interface.
Compact
1-3Micro spacing for icon gaps, tight controls, and small supporting UI.
Default
4-6Baseline rhythm for paragraphs, stacked content, and component interiors.
Section
8-12Breathing room between related groups, cards, and major content blocks.
Page
16-32Large-scale layout spacing for hero padding, page gutters, and vertical framing.
Spacing scale
Allowed values follow the shared token scale. Missing numbers are intentional and help keep the system from drifting into near-duplicate spacing choices.
Common rhythms
Tight UI gaps
2 / 0.5remButtons, breadcrumb items, small inline controls
Metadata and card rows
6 / 1.5remHeader gaps, project card meta rows, prose stacks
Section spacing
8 / 2remFoundation page sections and system layout columns
Heading offsets
12 / 3remSection headers and hero intro spacing
Page framing
32 / 8remHero vertical padding and large empty space
Guidelines
- Work from the shared 4px scale instead of inventing one-off values.
- Use a few repeated distances to create rhythm rather than many near-duplicates.
- Prefer layout wrappers like gap and space-y for vertical rhythm instead of margin on every child.
- Reserve the largest tokens for page framing and major section breaks, not routine component spacing.
- If two elements feel too close, move up to the next token in the scale instead of splitting the difference.
In practice
Is this an icon or small control relationship?
Start in the compact range.
Is this normal content stacking?
Use the default range.
Is this separating major groups?
Use the section range.
Is this framing a page or hero?
Use the page range.
Does this feel inconsistent with nearby layout?
Match an existing token before adding a new value.