Baseline Grid Refactoring Complete

ESSAY • JULY 14, 2025 • 1,000 WORDS

Today marks a significant milestone in our design system evolution: the successful enforcement of our 6px baseline grid across all core layout components.

What Was Done

Following the comprehensive audit and action plan outlined in our baseline grid refactoring plan, we’ve systematically updated all spacing values in our core layout components to align with the 6px grid unit.

Components Updated

1. Header Component (Header.astro)

  • Horizontal padding: px-5 (20px) → px-4b (24px)
  • Element heights: h-8 (32px) → h-5b (30px)
  • Icon sizes: size-8 (32px) → size-5b (30px)
  • Navigation gaps: gap-8 (32px) → gap-5b (30px)
  • Actions margin: ml-8 (32px) → ml-5b (30px)
  • Icon gaps: gap-4 (16px) → gap-3b (18px)
  • Title margin: ms-3 (12px) → ms-2b (12px)
  • Horizontal padding: px-5 (20px) → px-4b (24px)
  • Content gap: gap-4 (16px) → gap-3b (18px)

3. Base Layout (Base.astro)

  • Mobile top margin: mt-20 (80px) → mt-13b (78px)
  • Desktop top margin: md:mt-8 (32px) → md:mt-5b (30px)

Why This Matters

Visual Harmony

Every spacing value now aligns perfectly with our baseline grid. This creates an invisible structure that guides the eye naturally through the content.

Mathematical Foundation

Our 6px grid unit divides evenly into our 24px baseline, creating these harmonious relationships:

  • 1 grid unit = 6px
  • 2 grid units = 12px (half baseline)
  • 3 grid units = 18px (3/4 baseline)
  • 4 grid units = 24px (full baseline)
  • 5 grid units = 30px (1.25 baselines)

Consistency at Scale

With these changes, every structural element of the site now speaks the same visual language. This consistency compounds as more components adopt the grid system.

Technical Implementation

The refactoring used our established grid-aligned spacing utilities:

/* Grid-aligned spacing scale */
.px-4b { padding-left: 24px; padding-right: 24px; }
.gap-5b { gap: 30px; }
.h-5b { height: 30px; }
.ml-5b { margin-left: 30px; }
.gap-3b { gap: 18px; }
.ms-2b { margin-inline-start: 12px; }
.mt-13b { margin-top: 78px; }
.md:mt-5b { margin-top: 30px; /* on medium screens */ }

Verification Process

Each change was verified through:

  1. Development server inspection
  2. Browser developer tools measurement
  3. Visual regression checking
  4. Full production build testing

Next Steps

With the core layout components aligned, the next priorities are:

  1. Component-level spacing: Refactor remaining components (cards, buttons, forms)
  2. Prose typography: Ensure all content typography aligns with the grid
  3. Micro-interactions: Apply grid principles to animations and transitions
  4. Documentation: Update all component documentation with grid-aligned examples

Lessons Learned

The senior engineer’s code review was invaluable in highlighting that we already had a well-designed system – we just weren’t using it consistently. This refactoring proves that systematic application of existing design principles often yields better results than creating new systems.

Impact

This foundational work establishes the vertical rhythm that will guide all future development. Every new component can now reference these core layouts as examples of proper grid implementation.

The baseline grid is no longer an aspiration – it’s now the reality of how our site is built.