# Spacing Layout

> Spacing and layout metrics: 8pt grid system, standard margins, 44pt tap targets, vertical rhythm, density guidelines. Use when setting padding, margins, spacing between elements, or ensuring touch target sizes. Triggers: padding, spacing, margin, tap target, 44pt, grid, density, contentMargins.

- Skill: `abdullah4ai/spacing-layout` (Agent Skill)
- Install (CLI): `npx skillmds@latest add abdullah4ai/spacing-layout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abdullah4ai/spacing-layout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: abdullah4ai (https://skillmd.com/u/abdullah4ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/abdullah4ai/spacing-layout

---

# Spacing & Layout

8-POINT GRID SYSTEM:
All spacing values must be multiples of 4pt. Standard scale:

| Token             | Value | Use Case                                    |
|-------------------|-------|---------------------------------------------|
| Spacing.xxSmall   | 4pt   | Icon-to-label gap, tight inline spacing     |
| Spacing.xSmall    | 8pt   | Between related items (label + value)        |
| Spacing.small     | 12pt  | List row internal padding                    |
| Spacing.medium    | 16pt  | Standard padding, outer margins              |
| Spacing.large     | 24pt  | Section spacing, card-to-card gap            |
| Spacing.xLarge    | 32pt  | Major section breaks                         |
| Spacing.xxLarge   | 48pt  | Screen-level top/bottom breathing room       |

NEVER use arbitrary values (5, 7, 10, 13, 15, 18, 25, etc.). Snap to the grid.

STANDARD MARGINS:
- Outer screen margins: 16pt (.padding(.horizontal, AppTheme.Spacing.medium)).
- Card internal padding: 16pt (.padding(AppTheme.Spacing.medium)).
- Section spacing (between groups): 24pt.
- List row vertical padding: 12pt.
- Toolbar/header spacing: 16pt horizontal, 8pt vertical.

TAP TARGET SIZES:
- Minimum: 44x44pt for ALL interactive elements (Apple HIG requirement).
- If visual element is smaller (e.g. 24x24 icon), expand hit area:
  .frame(minWidth: 44, minHeight: 44)
  .contentShape(Rectangle())
- Inline buttons in text: ensure surrounding padding creates 44pt height.
- Icon buttons: use .frame(width: 44, height: 44) even if icon is 20-24pt.

VERTICAL RHYTHM:
- Consistent spacing within a section (all rows use same gap).
- Larger gap between sections than within sections.
- Example: 8pt between rows within a section, 24pt between sections.
- Headers get extra top spacing: 32pt above, 8pt below.

DENSITY GUIDELINES (from plan's design.density):
- "spacious": Use .large/.xLarge gaps. Generous padding (20-24pt). Best for meditation, health, reading apps.
- "standard": Use .medium gaps. 16pt padding. Default for most apps.
- "compact": Use .small/.xSmall gaps. 12pt padding. Best for data-heavy apps (finance, productivity).

CARD LAYOUT PATTERN:
```swift
VStack(alignment: .leading, spacing: AppTheme.Spacing.xSmall) {
    // Card content
}
.padding(AppTheme.Spacing.medium)
.background(AppTheme.Colors.surface)
.clipShape(RoundedRectangle(cornerRadius: AppTheme.Style.cornerRadius))
.shadow(color: .black.opacity(0.06), radius: 8, y: 4)
```

HORIZONTAL LAYOUTS:
- Space between icon and label: 8pt.
- Space between label and trailing value: use Spacer().
- Button bar with 2-3 buttons: HStack with spacing: 12pt.
- 4+ buttons: wrap in ScrollView(.horizontal).

SAFE AREA:
- Content respects safe areas by default — don't add redundant padding.
- Full-screen backgrounds use .ignoresSafeArea() to extend edge-to-edge.
- Overlays use .safeAreaInset(edge:) — never manual padding for safe areas.