Grid System Optimization Plan

Update (July 14, 2025): The core layout refactoring (Phase 1) has been completed! See Baseline Grid Refactoring Complete for details.

Executive Summary

This plan outlines a comprehensive optimization of the spacing and grid system, transitioning from the current partially-implemented 4px baseline grid to a fully-integrated, typography-driven vertical rhythm system.

1. Current State Analysis

Existing System

• Base Grid: 4px (0.25rem) baseline grid
• Font Sizes: Fluid type scale from 0.64rem to 4.05rem
• Line Heights: 1.05 to 1.6 (varies by element)
• Spacing Scale: Mix of semantic tokens and hardcoded values

Key Issues Identified

1. Typography-Grid Mismatch: Base font (15-17px) doesn’t align with 16px spacing unit
2. Compound Spacing Jumps: 50-69% increases break visual rhythm
3. Hardcoded Values: ~40% of spacing uses arbitrary values
4. Inconsistent Application: Components mix semantic and arbitrary spacing

2. Proposed Grid System

Foundation Principles

/* Base Typography Metrics */
--base-font-size: 16px (1rem)
--base-line-height: 1.5
--baseline-unit: 24px (1.5rem) /* font × line-height */
 
/* Grid Unit */
--grid-unit: 6px (0.375rem) /* 24px ÷ 4 */

Why 6px Grid Unit?

• Divides evenly into 24px baseline (4 units per line)
• More flexible than 4px for typography alignment
• Allows half-line spacing (12px = 2 units)
• Better accommodates various font sizes

Spacing Scale (Based on Grid Units)

/* Micro Spacing */
--space-1: 6px   (1 unit)   /* Hairline */
--space-2: 12px  (2 units)  /* Tight */
--space-3: 18px  (3 units)  /* Compact */
 
/* Flow Spacing */
--space-4: 24px  (4 units)  /* Base - 1 baseline */
--space-6: 36px  (6 units)  /* Flow - 1.5 baselines */
--space-8: 48px  (8 units)  /* Section - 2 baselines */
 
/* Layout Spacing */
--space-12: 72px  (12 units) /* Large - 3 baselines */
--space-16: 96px  (16 units) /* Huge - 4 baselines */
--space-24: 144px (24 units) /* Massive - 6 baselines */

Responsive Scaling

/* Mobile (320-768px) */
--baseline-mobile: 22px (1.375rem)
--grid-unit-mobile: 5.5px (0.34375rem)
 
/* Desktop (768px+) */
--baseline-desktop: 24px (1.5rem)
--grid-unit-desktop: 6px (0.375rem)

3. Typography Alignment Strategy

Paragraph Spacing

p {
  margin-bottom: var(--space-4); /* 1 baseline */
  line-height: 1.5; /* Maintains rhythm */
}
 
p + p {
  margin-top: 0; /* Prevents doubling */
}

Heading Placement

/* Space ratios: above = 2-3x below */
h1 { 
  margin-top: var(--space-8);    /* 2 baselines */
  margin-bottom: var(--space-3);  /* 0.75 baselines */
  line-height: 1.1;
  /* Padding to align to grid */
  padding-top: 0.1em;
  padding-bottom: 0.1em;
}
 
h2 { 
  margin-top: var(--space-6);    /* 1.5 baselines */
  margin-bottom: var(--space-2);  /* 0.5 baselines */
  line-height: 1.15;
}
 
h3 { 
  margin-top: var(--space-4);    /* 1 baseline */
  margin-bottom: var(--space-2);  /* 0.5 baselines */
  line-height: 1.2;
}

Component Spacing

/* Cards/Sections */
.card {
  padding: var(--space-4);      /* 1 baseline */
  margin-bottom: var(--space-6); /* 1.5 baselines */
}
 
/* Lists */
li + li {
  margin-top: var(--space-1);   /* 0.25 baseline */
}
 
/* Blockquotes */
blockquote {
  padding-left: var(--space-4);  /* 1 baseline */
  margin: var(--space-6) 0;      /* 1.5 baselines */
}

4. Implementation Phases

Phase 1: Foundation (Week 1)

1. Update CSS variables to new grid system
2. Replace b notation with semantic spacing
3. Test critical layouts for breakage
4. Document migration patterns

Phase 2: Component Updates (Week 2)

1. Update all component spacing
2. Remove arbitrary values
3. Ensure baseline alignment
4. Test responsive behavior

Phase 3: Polish (Week 3)

1. Fine-tune optical adjustments
2. Add debug grid overlays
3. Performance optimization
4. Final documentation

5. Migration Guide

Quick Reference

Component Patterns

/* Old Pattern */
.component {
  padding: 4b;
  margin-bottom: 8b;
}
 
/* New Pattern */
.component {
  padding: var(--space-4);     /* 24px */
  margin-bottom: var(--space-8); /* 48px */
}

Tailwind Classes

<!-- Old -->
<div class="p-4b mb-8b">
 
<!-- New -->
<div class="p-4 mb-8">

6. Visual Rhythm Examples

Article Layout

[H1 - 48px margin-top]
    ↓ 18px (0.75 baseline)
[Paragraph]
    ↓ 24px (1 baseline)
[Paragraph]
    ↓ 36px (1.5 baselines)
[H2 - 36px margin-top]
    ↓ 12px (0.5 baseline)
[Paragraph]

Card Grid

[Card - 24px padding]
    ↓ 36px gap (1.5 baselines)
[Card - 24px padding]
    ↓ 36px gap (1.5 baselines)
[Card - 24px padding]

7. Testing Checklist

Visual Tests

• All text aligns to baseline grid
• Consistent vertical rhythm maintained
• No visual regressions at breakpoints
• Print stylesheet maintains grid

Technical Tests

• No hardcoded pixel values remain
• All spacing uses CSS variables
• Responsive scaling works correctly
• Performance metrics unchanged

Browser Tests

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers

8. Success Metrics

Quantitative

• 100% semantic spacing usage
• 0 arbitrary pixel values
• <5ms additional render time
• Consistent 24px baseline maintained

Qualitative

• Improved visual harmony
• Easier maintenance
• Better responsive behavior
• Clear documentation

9. Rollback Plan

If issues arise:

1. CSS variables can be reverted to old values
2. Component changes are isolated
3. Git history maintains all changes
4. Gradual rollout possible

10. Long-term Benefits

Developer Experience

• Single source of truth for spacing
• Predictable visual rhythm
• Easier debugging with grid overlays
• Clear documentation

Design Consistency

• Mathematical relationships
• Harmonic proportions
• Responsive without breakpoints
• Maintains brand guidelines

Performance

• Reduced CSS complexity
• Fewer unique values
• Better caching
• Smaller file sizes

This plan ensures a smooth transition to a more robust, maintainable grid system that enhances both developer experience and visual design quality.