Spacing + Layout

This UI system uses a small set of spacing rules to keep layouts consistent, predictable, and easy to maintain.

The goal is simple:

• clean vertical rhythm
• consistent padding across surfaces
• layouts that scale without “random spacing”

Spacing principles

1) Use a spacing scale (not one-off values)

Spacing should come from a shared scale so the UI feels intentional.

If something looks “slightly off”, the fix should be choosing the next step in the scale, not inventing a new number.

2) Prefer vertical rhythm over visual noise

Most layouts should follow a simple stack pattern:

• title
• supporting text
• content
• actions

Spacing should guide the eye, not compete for attention.

3) Padding is part of the component

Cards, panels, and sections should feel consistent even when the content changes.

That means padding shouldn’t vary wildly between components.

Layout conventions

Page container

Most pages use a centered container with a consistent max width.

Example:

<main class="mx-auto w-full max-w-5xl px-6 py-12">
  ...
</main>

Section spacing

Pages are built using stacked sections with consistent spacing between them.

Example:

<div class="space-y-8">
  <header class="space-y-3">...</header>
  <section class="space-y-4">...</section>
</div>

Grid conventions

Default grid

Most collections (projects, cards, etc.) use:

1 column on mobile

2 columns on medium screens and up

<section class="grid gap-6 md:grid-cols-2">
  ...
</section>

Gap rules

Use gap-* for layout spacing inside grids.

• gap-4 for compact lists
• gap-6 for cards
• gap-8 for larger sections

Practical defaults I use most

These show up everywhere in the codebase:

• space-y-2 for tight text groups
• space-y-3 for headers and intro sections
• space-y-4 for forms and content blocks
• space-y-8 for page-level spacing
• p-6 for cards and surfaces
• py-12 for page padding
• gap-6 for card grids

Notes

Spacing is one of the easiest places for a UI system to drift over time.

This page exists so layout decisions stay consistent as new components and pages get added.