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:
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.
1---2name: spacing-layout3description: 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.4---5# Spacing & Layout678-POINT GRID SYSTEM:8All spacing values must be multiples of 4pt. Standard scale:910| Token | Value | Use Case |11|-------------------|-------|---------------------------------------------|12| Spacing.xxSmall | 4pt | Icon-to-label gap, tight inline spacing |13| Spacing.xSmall | 8pt | Between related items (label + value) |14| Spacing.small | 12pt | List row internal padding |15| Spacing.medium | 16pt | Standard padding, outer margins |16| Spacing.large | 24pt | Section spacing, card-to-card gap |17| Spacing.xLarge | 32pt | Major section breaks |18| Spacing.xxLarge | 48pt | Screen-level top/bottom breathing room |1920NEVER use arbitrary values (5, 7, 10, 13, 15, 18, 25, etc.). Snap to the grid.2122STANDARD MARGINS:23- Outer screen margins: 16pt (.padding(.horizontal, AppTheme.Spacing.medium)).24- Card internal padding: 16pt (.padding(AppTheme.Spacing.medium)).25- Section spacing (between groups): 24pt.26- List row vertical padding: 12pt.27- Toolbar/header spacing: 16pt horizontal, 8pt vertical.2829TAP TARGET SIZES:30- Minimum: 44x44pt for ALL interactive elements (Apple HIG requirement).31- If visual element is smaller (e.g. 24x24 icon), expand hit area:32 .frame(minWidth: 44, minHeight: 44)33 .contentShape(Rectangle())34- Inline buttons in text: ensure surrounding padding creates 44pt height.35- Icon buttons: use .frame(width: 44, height: 44) even if icon is 20-24pt.3637VERTICAL RHYTHM:38- Consistent spacing within a section (all rows use same gap).39- Larger gap between sections than within sections.40- Example: 8pt between rows within a section, 24pt between sections.41- Headers get extra top spacing: 32pt above, 8pt below.4243DENSITY GUIDELINES (from plan's design.density):44- "spacious": Use .large/.xLarge gaps. Generous padding (20-24pt). Best for meditation, health, reading apps.45- "standard": Use .medium gaps. 16pt padding. Default for most apps.46- "compact": Use .small/.xSmall gaps. 12pt padding. Best for data-heavy apps (finance, productivity).4748CARD LAYOUT PATTERN:49```swift50VStack(alignment: .leading, spacing: AppTheme.Spacing.xSmall) {51 // Card content52}53.padding(AppTheme.Spacing.medium)54.background(AppTheme.Colors.surface)55.clipShape(RoundedRectangle(cornerRadius: AppTheme.Style.cornerRadius))56.shadow(color: .black.opacity(0.06), radius: 8, y: 4)57```5859HORIZONTAL LAYOUTS:60- Space between icon and label: 8pt.61- Space between label and trailing value: use Spacer().62- Button bar with 2-3 buttons: HStack with spacing: 12pt.63- 4+ buttons: wrap in ScrollView(.horizontal).6465SAFE AREA:66- Content respects safe areas by default — don't add redundant padding.67- Full-screen backgrounds use .ignoresSafeArea() to extend edge-to-edge.68- Overlays use .safeAreaInset(edge:) — never manual padding for safe areas.
abdullah4ai