veza/apps/web/src/styles/GRID_SYSTEM.md

# 8px Grid System - Kodo Design System

**Last Updated**: 2025-01-27  
**Purpose**: Document the 8px grid system for establishing visual rhythm and consistent spacing

## Overview

The Kodo Design System uses an **8px base grid** for establishing visual rhythm and ensuring consistent spacing throughout the application. All spacing values should align to multiples of 8px.

## Grid Base

- **Base Unit**: 8px (0.5rem)
- **Grid System**: 8px × 8px grid overlay
- **Purpose**: Create visual rhythm, ensure consistent spacing, improve alignment

## Spacing Scale (8px Multiples)

The spacing scale is defined in `apps/web/src/styles/design-tokens.css` and uses Tailwind's spacing utilities.

### Recommended 8px-Aligned Values

| Tailwind Class | Pixels | Rem | Use Case |
|---------------|--------|-----|----------|
| `gap-0`, `p-0`, `m-0` | 0px | 0 | No spacing |
| `gap-1`, `p-1`, `m-1` | 4px | 0.25rem | ⚠️ Not 8px aligned - use sparingly |
| `gap-2`, `p-2`, `m-2` | 8px | 0.5rem | ✅ **Base unit** - Tight spacing, small gaps |
| `gap-3`, `p-3`, `m-3` | 12px | 0.75rem | ⚠️ Not 8px aligned - use sparingly |
| `gap-4`, `p-4`, `m-4` | 16px | 1rem | ✅ **2× base** - Standard padding, medium gaps |
| `gap-6`, `p-6`, `m-6` | 24px | 1.5rem | ✅ **3× base** - Large padding, section spacing |
| `gap-8`, `p-8`, `m-8` | 32px | 2rem | ✅ **4× base** - Extra large spacing, card padding |
| `gap-10`, `p-10`, `m-10` | 40px | 2.5rem | ⚠️ Not 8px aligned - use sparingly |
| `gap-12`, `p-12`, `m-12` | 48px | 3rem | ✅ **6× base** - Section spacing, large containers |
| `gap-16`, `p-16`, `m-16` | 64px | 4rem | ✅ **8× base** - Page-level spacing |
| `gap-20`, `p-20`, `m-20` | 80px | 5rem | ⚠️ Not 8px aligned - use sparingly |
| `gap-24`, `p-24`, `m-24` | 96px | 6rem | ✅ **12× base** - Maximum spacing |

### Preferred Values (8px Aligned)

**Primary spacing values** (preferred):
- `gap-2`, `p-2`, `m-2` (8px) - Base unit
- `gap-4`, `p-4`, `m-4` (16px) - Standard
- `gap-6`, `p-6`, `m-6` (24px) - Large
- `gap-8`, `p-8`, `m-8` (32px) - Extra large
- `gap-12`, `p-12`, `m-12` (48px) - Section spacing
- `gap-16`, `p-16`, `m-16` (64px) - Page spacing
- `gap-24`, `p-24`, `m-24` (96px) - Maximum

**Avoid** (not 8px aligned):
- `gap-1`, `p-1`, `m-1` (4px) - Use `gap-2` instead
- `gap-3`, `p-3`, `m-3` (12px) - Use `gap-2` or `gap-4` instead
- `gap-10`, `p-10`, `m-10` (40px) - Use `gap-8` or `gap-12` instead
- `gap-20`, `p-20`, `m-20` (80px) - Use `gap-16` or `gap-24` instead

## Usage Guidelines

### 1. Component Spacing

**Card Padding**:
```tsx
<Card className="p-6">  {/* 24px - 3× base */}
  <CardContent>...</CardContent>
</Card>
```

**Button Spacing**:
```tsx
<Button className="px-4 py-2">  {/* 16px horizontal, 8px vertical */}
  Click me
</Button>
```

**Form Inputs**:
```tsx
<div className="space-y-4">  {/* 16px vertical spacing */}
  <Input />
  <Input />
</div>
```

### 2. Layout Spacing

**Section Spacing**:
```tsx
<section className="space-y-8">  {/* 32px between sections */}
  <Section1 />
  <Section2 />
</section>
```

**Grid Gaps**:
```tsx
<div className="grid grid-cols-3 gap-6">  {/* 24px gap between items */}
  <Item />
  <Item />
  <Item />
</div>
```

**Container Padding**:
```tsx
<div className="container mx-auto px-4 py-8">  {/* 16px horizontal, 32px vertical */}
  <Content />
</div>
```

### 3. Responsive Spacing

Use responsive utilities to adjust spacing for different screen sizes:

```tsx
<div className="p-4 md:p-6 lg:p-8">  {/* 16px → 24px → 32px */}
  Content
</div>
```

### 4. Semantic Spacing

The design tokens also provide semantic spacing values:

- `gap-xs` (4px) - ⚠️ Not 8px aligned
- `gap-sm` (8px) - ✅ Base unit
- `gap-md` (16px) - ✅ 2× base
- `gap-lg` (24px) - ✅ 3× base
- `gap-xl` (32px) - ✅ 4× base
- `gap-2xl` (48px) - ✅ 6× base
- `gap-3xl` (64px) - ✅ 8× base

**Prefer numeric scale** (`gap-2`, `gap-4`, `gap-6`) over semantic scale for 8px alignment.

## Alignment Rules

1. **All spacing should be multiples of 8px** when possible
2. **Use 4px values sparingly** - only when absolutely necessary for fine-tuning
3. **Avoid arbitrary values** - use `gap-[7px]` → `gap-2` (8px) or `gap-4` (16px)
4. **Consistent spacing** - use the same spacing value for similar elements
5. **Visual rhythm** - maintain consistent spacing patterns across pages

## Migration Notes

The current spacing system in `design-tokens.css` uses a 4px base. To align with the 8px grid:

- ✅ Values that are already 8px aligned: `spacing-2`, `spacing-4`, `spacing-6`, `spacing-8`, `spacing-12`, `spacing-16`, `spacing-24`
- ⚠️ Values that need attention: `spacing-1` (4px), `spacing-3` (12px), `spacing-5` (20px), `spacing-10` (40px), `spacing-20` (80px)

**Action 11.2.1.2** will verify and update the spacing scale to ensure all values align to 8px.

## Examples

### Good (8px Aligned)
```tsx
<div className="p-4 gap-6 space-y-8">  {/* 16px, 24px, 32px */}
  <Component />
</div>
```

### Avoid (Not 8px Aligned)
```tsx
<div className="p-3 gap-5 space-y-7">  {/* 12px, 20px, 28px */}
  <Component />
</div>
```

### Better Alternative
```tsx
<div className="p-4 gap-6 space-y-8">  {/* 16px, 24px, 32px */}
  <Component />
</div>
```

## Tools

- **Visual Grid Overlay**: Action 11.2.1.4 will add a dev tool to visualize the 8px grid
- **Spacing Audit**: Action 11.2.1.3 will align all elements to the 8px grid

## References

- Design Tokens: `apps/web/src/styles/design-tokens.css`
- Color Usage: `apps/web/src/styles/COLOR_USAGE.md`
- Component Usage: `apps/web/src/components/COMPONENT_USAGE.md`