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:

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

<Container className="p-md gap-lg">
  <Card className="p-sm" />
  <Card className="px-xl py-sm" />
</Container>

Common Patterns

Component Spacing

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

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

Layout Spacing

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

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

Section Spacing

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