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:

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

Button Spacing:

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

Form Inputs:

<div className="space-y-4">  {/* 16px vertical spacing */}
  <Input />
  <Input />
</div>

2. Layout Spacing

Section Spacing:

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

Grid Gaps:

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

Container Padding:

<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:

<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)

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

Avoid (Not 8px Aligned)

<div className="p-3 gap-5 space-y-7">  {/* 12px, 20px, 28px */}
  <Component />
</div>

Better Alternative

<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