veza/apps/web/docs/SPACING_GUIDE.md

# Spacing System Guide

**Last Updated**: 2025-01-27  
**Action**: 7.2.1.7 - Create SPACING_GUIDE.md  
**Status**: ✅ Complete

## Overview

The Veza spacing system is built on a **4px base scale** and provides both **numeric** and **semantic** spacing utilities. All spacing utilities are automatically generated by Tailwind v4 from CSS variables defined in `design-tokens.css`.

## Spacing Scale

### Numeric Scale (Recommended for Most Cases)

The numeric scale uses numbers (0-24) that map to 4px increments:

| Value | Rem | Pixels | Common Usage |
|-------|-----|--------|--------------|
| `0` | 0 | 0px | No spacing |
| `1` | 0.25rem | 4px | Tight spacing, icons |
| `2` | 0.5rem | 8px | Small spacing, compact layouts |
| `3` | 0.75rem | 12px | Medium-small spacing |
| `4` | 1rem | 16px | Base spacing (most common) |
| `5` | 1.25rem | 20px | Medium spacing |
| `6` | 1.5rem | 24px | Large spacing |
| `8` | 2rem | 32px | Extra large spacing |
| `10` | 2.5rem | 40px | Section spacing |
| `12` | 3rem | 48px | Large section spacing |
| `16` | 4rem | 64px | Page section spacing |
| `20` | 5rem | 80px | Major section spacing |
| `24` | 6rem | 96px | Maximum spacing |

### Semantic Scale (For Design System Consistency)

The semantic scale provides named values for design system consistency:

| Name | Value | Pixels | Equivalent Numeric |
|------|-------|--------|-------------------|
| `xs` | 0.25rem | 4px | `1` |
| `sm` | 0.5rem | 8px | `2` |
| `md` | 1rem | 16px | `4` |
| `lg` | 1.5rem | 24px | `6` |
| `xl` | 2rem | 32px | `8` |
| `2xl` | 3rem | 48px | `12` |
| `3xl` | 4rem | 64px | `16` |
| `4xl` | 5rem | 80px | `20` |
| `5xl` / `xxl` | 6rem | 96px | `24` |

## Available Utilities

All spacing utilities are automatically generated by Tailwind v4. You can use both numeric and semantic values:

### Gap Utilities
- **Numeric**: `gap-0`, `gap-1`, `gap-2`, `gap-3`, `gap-4`, `gap-5`, `gap-6`, `gap-8`, `gap-10`, `gap-12`, `gap-16`, `gap-20`, `gap-24`
- **Semantic**: `gap-xs`, `gap-sm`, `gap-md`, `gap-lg`, `gap-xl`, `gap-2xl`, `gap-3xl`, `gap-4xl`, `gap-5xl`, `gap-xxl`

### Padding Utilities
- **Numeric**: `p-0`, `p-1`, `p-2`, `p-3`, `p-4`, `p-5`, `p-6`, `p-8`, `p-10`, `p-12`, `p-16`, `p-20`, `p-24`
- **Directional**: `px-*`, `py-*`, `pt-*`, `pr-*`, `pb-*`, `pl-*`
- **Semantic**: `p-xs`, `p-sm`, `p-md`, `p-lg`, `p-xl`, `p-2xl`, `p-3xl`, `p-4xl`, `p-5xl`, `p-xxl`

### Margin Utilities
- **Numeric**: `m-0`, `m-1`, `m-2`, `m-3`, `m-4`, `m-5`, `m-6`, `m-8`, `m-10`, `m-12`, `m-16`, `m-20`, `m-24`
- **Directional**: `mx-*`, `my-*`, `mt-*`, `mr-*`, `mb-*`, `ml-*`
- **Semantic**: `m-xs`, `m-sm`, `m-md`, `m-lg`, `m-xl`, `m-2xl`, `m-3xl`, `m-4xl`, `m-5xl`, `m-xxl`

### Space Between Utilities
- **Numeric**: `space-x-*`, `space-y-*` (0-24)
- **Semantic**: `space-x-xs`, `space-y-md`, etc.

## Usage Guidelines

### When to Use Numeric Scale

✅ **Use numeric scale for:**
- Most common spacing needs
- Precise pixel control
- Following Tailwind conventions
- Consistency with existing codebase

**Examples:**
```tsx
<div className="flex gap-4 p-6">
  <Card className="p-4" />
  <Card className="px-8 py-2" />
</div>
```

### When to Use Semantic Scale

✅ **Use semantic scale for:**
- Reusable component libraries
- Design system consistency
- When spacing meaning is more important than exact pixels
- Building design tokens

**Examples:**
```tsx
<Container className="p-md gap-lg">
  <Card className="p-sm" />
  <Card className="px-xl py-sm" />
</Container>
```

## Common Patterns

### Component Spacing

```tsx
// Card with consistent padding
<Card className="p-4">...</Card>

// Card with semantic padding
<Card className="p-md">...</Card>
```

### Layout Spacing

```tsx
// Grid with gap
<div className="grid grid-cols-3 gap-4">...</div>

// Flex with gap
<div className="flex gap-2">...</div>
```

### Section Spacing

```tsx
// Vertical spacing between sections
<section className="space-y-6">...</section>

// Large section spacing
<section className="py-12">...</section>
```

## Best Practices

### ✅ Do

- Use scale values (0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24)
- Prefer numeric scale for most cases
- Use semantic scale for design system components
- Be consistent within components
- Use `gap-*` for flexbox/grid layouts
- Use `space-y-*` / `space-x-*` for spacing between children

### ❌ Don't

- Use arbitrary values (`gap-[7px]`, `p-[9px]`) - use nearest scale value
- Mix numeric and semantic inconsistently
- Use spacing values outside the scale (7, 9, 11, 13, 14, 15, etc.)
- Use `margin` when `gap` or `space-*` would work
- Override spacing with inline styles

## ESLint Enforcement

An ESLint rule enforces spacing scale usage:

- **Warns on**: Arbitrary spacing values like `gap-[7px]`, `p-[9px]`, etc.
- **Allows**: All scale values (0-24 numeric, xs-xxl semantic)
- **Exceptions**: Use `eslint-disable` comments for legitimate exceptions

## Migration Guide

### Replacing Arbitrary Values

If you find arbitrary spacing values, replace them with the nearest scale value:

| Arbitrary | Replace With | Reason |
|-----------|--------------|--------|
| `gap-[7px]` | `gap-6` | 7px (28px) → 6 (24px) |
| `p-[9px]` | `p-8` | 9px (36px) → 8 (32px) |
| `gap-[11px]` | `gap-12` | 11px (44px) → 12 (48px) |

### Converting to Semantic Scale

For design system components, consider converting to semantic scale:

| Numeric | Semantic | Use Case |
|---------|----------|----------|
| `gap-2` | `gap-sm` | Small spacing |
| `p-4` | `p-md` | Base padding |
| `gap-6` | `gap-lg` | Large spacing |
| `p-12` | `p-2xl` | Extra large padding |

## Statistics

Based on the spacing audit (Action 7.2.1.2):

- **Total spacing instances**: 2,761 across 366 files
- **Most common**: `gap-2` (519 instances), `p-4` (357 instances), `space-y-4` (159 instances)
- **Scale compliance**: ~99% of spacing uses valid scale values

## Related Documentation

- **Design Tokens**: `apps/web/src/styles/design-tokens.css`
- **Spacing Audit**: `apps/web/docs/SPACING_AUDIT_REPORT.md`
- **ESLint Config**: `apps/web/eslint.config.js`

## Questions?

If you're unsure which spacing value to use:

1. **Check existing patterns** in similar components
2. **Use numeric scale** for most cases (gap-2, p-4, etc.)
3. **Use semantic scale** for design system components
4. **Follow the 4px base** - all values should align to 4px increments
5. **Run ESLint** - it will warn on invalid spacing values