Typography System Documentation

This document tracks the complete typography system implementation, including all phases completed and the current state of the system.

Overview

The typography system has been developed through multiple phases, each building upon the previous to create a sophisticated, scalable design system.

Phase 1: Foundation Cleanup (Completed)

Goals Achieved

• ✅ Removed legacy CSS and unused font declarations
• ✅ Consolidated typography tokens into single source of truth
• ✅ Established baseline grid system (6px)
• ✅ Implemented CSS custom properties for all spacing

Key Changes

• Removed 500+ lines of redundant CSS
• Migrated from scattered font-size declarations to semantic classes
• Established --space-* CSS variables for consistent spacing

Phase 2: Semantic Typography System (Completed)

Implemented Components

• ✅ Fluid type scale (text--2 through text-6)
• ✅ Semantic heading classes (heading-1 through heading-6)
• ✅ Body text variants (text-body, text-body-sm, text-lead)
• ✅ Component-specific typography (text-caption, text-meta)

Typography Scale

Using a 1.25 ratio (major third) with fluid scaling:

/* Base size scales from 15px to 17px */
text-0: 0.94rem → 1.06rem (body text)
text-1: 1.17rem → 1.33rem (large text)
text-2: 1.46rem → 1.66rem (h3)
text-3: 1.83rem → 2.08rem (h2)
text-4: 2.29rem → 2.59rem (h1)

Phase 3: Advanced Typography Features (Completed)

3.1 Enhanced Prose Configuration

• Strict baseline grid alignment for all prose elements
• Mathematical spacing relationships
• Improved readability measures (45ch narrow, 65ch optimal, 75ch wide)

3.2 Typography Utilities

• Reading measure controls
• Optical alignment utilities
• Font feature controls (kerning, ligatures, etc.)

3.3 Mobile Typography Optimization

• Responsive font sizing without breakpoints
• Touch-friendly tap targets
• Optimized line lengths for mobile reading

3.4 Code Block Typography

• Baseline-aligned code blocks
• Consistent syntax highlighting
• Optimized monospace sizing

Phase 4: Dark Mode Typography (Completed)

Implemented Optimizations

• ✅ Increased font weights (+50-100 units in dark mode)
• ✅ Adjusted opacity values for reduced eye strain
• ✅ Fine-tuned contrast ratios
• ✅ Variable font weight adjustments

Dark Mode Specifics

/* Light mode: 400 weight → Dark mode: 450 weight */
h1: { font-weight: 450; opacity: 0.95; }
h2: { font-weight: 475; opacity: 0.93; }
h3: { font-weight: 525; opacity: 0.92; }

Phase 5: Header & Footer Refinements (Completed)

Typography Enhancements

• Site title with optical adjustments and variable font features
• Navigation links with precise baseline alignment
• Footer hierarchy with distinct text sizes

Spacing Refinements

• Golden ratio-based header height
• Reduced excessive spacing throughout
• Mobile-first responsive adjustments

Current System Architecture

Font Stack

--font-headline: 'Newsreader', Georgia, serif;
--font-body: 'IBM Plex Sans', system-ui, sans-serif;
--font-mono: 'IBM Plex Mono', 'Cascadia Code', monospace;

Grid System

• Base Unit: 6px (--grid-unit: 0.375rem)
• Baseline: 24px (--baseline: 1.5rem)
• Spacing Scale: Multiples of grid unit (6px, 12px, 18px, 24px, etc.)

Responsive Strategy

• Fluid typography scales smoothly between 320px and 1280px
• No jarring breakpoint jumps
• Mobile-first approach with progressive enhancement

Usage Guidelines

When to Use Each Text Size

• text--2: Legal text, tiny captions
• text--1: Secondary text, metadata
• text-0: Body text, default size
• text-1: Lead paragraphs, emphasized text
• text-2 to text-6: Headings and display text

Spacing Best Practices

1. Always use grid-based spacing values
2. Maintain vertical rhythm with baseline multiples
3. Use semantic spacing tokens, not arbitrary values
4. Test at extreme viewport sizes (320px and 1280px)

Component Integration

Every component should:

• Use semantic typography classes
• Align to the baseline grid
• Respect the spacing scale
• Account for dark mode variations

Performance Considerations

Font Loading

• Preloaded critical fonts
• font-display: swap for non-blocking render
• Subset fonts to reduce file size

CSS Architecture

• CSS custom properties for runtime flexibility
• Minimal specificity for easy overrides
• Efficient cascade usage

Phase 6: Grid Alignment Refinement (January 17, 2025)

Goals Achieved

• ✅ Perfect alignment of all components to 6px baseline grid
• ✅ Visual baseline grid test class for development
• ✅ Typography quick wins (letter-spacing utilities)
• ✅ Complete prose spacing refactor

Key Changes

Visual Development Tools

• Added .show-baseline class for 24px grid visualization
• Creates horizontal lines every 24px for vertical rhythm testing
• Can be applied to <body> tag during development

Typography Enhancements

• Added letter-spacing utilities:
  • tightest: -0.02em
  • tighter: -0.015em
  • wideUpper: 0.05em
• Updated nav-link letter-spacing to 0.05em
• Applied -0.015em letter-spacing to heading-1

Component Updates

All components now use grid-aligned spacing:

• Comments.astro: gap-x-5 → gap-x-5b, h-12 w-12 → h-8b w-8b
• Likes.astro: ps-2 → ps-2b, -ms-2 → -ms-2b
• PostSearch.astro: right-3 → right-3b, w-5 h-5 → w-3b h-3b
• TOC.astro: top-2 right-2 → top-2b right-2b
• SkipLink.astro: focus:start-1 focus:top-1.5 → focus:start-1b focus:top-2b
• ResearchCard.astro: gap-1 → gap-1b, h-3 w-3 → h-2b w-2b

Layout Refinements

• Footer.astro: All spacing now uses semantic tokens (—space-s, —space-l)
• Prose plugin: Updated to use grid-aligned CSS variables
• Verified negative margins are intentional for hover effects

Grid System Reference

• Unit: 6px (--grid-unit: 0.375rem)
• Baseline: 24px (--baseline: 1.5rem)
• Notation: *b (1b = 6px, 4b = 24px, etc.)

Phase 7: Optical Typography Refinements (January 17, 2025)

Goals Achieved

• ✅ Enhanced body text readability with micro-adjustments
• ✅ Optimized dark mode for reduced eye strain
• ✅ Created advanced typography utilities
• ✅ Maintained perfect grid alignment

Body Text Refinements

Letter-Spacing Enhancement

• Applied subtle 0.005em letter-spacing to body text
• Improves word-shape recognition and reduces reading fatigue
• Particularly effective for long-form content

Dark Mode Optimization

• Text color: hsl(30deg 10% 95% / 0.95) - slightly off-white
• Font weight: 380 (reduced from 400) to compensate for halation
• Results in more comfortable extended reading sessions

UI Text Refinements

New Letter-Spacing Utilities

letterSpacing: {
  nav: "0.05em",           // Navigation elements
  "caps-generous": "0.075em", // Generous uppercase
  "caps-loose": "0.1em",      // Maximum uppercase clarity
}

True Small Caps

Created .text-small-caps utility class:

• Uses proper OpenType features (smcp, c2sc)
• Includes 0.075em letter-spacing
• More refined than fake small caps

Technical Details

• All uppercase text components verified for proper spacing
• OpenType features fully utilized (kern, liga, calt, ss01)
• Variable font capabilities preserved
• Zero impact on baseline grid alignment

Future Enhancements

Planned Improvements

• Variable font animations
• Enhanced OpenType features
• Improved print stylesheet
• Advanced grid visualization tools

Experimental Features

• Optical margin alignment
• Dynamic measure adjustment
• Context-aware spacing

Debugging

Visual Grid Tools

Add these classes to any element:

• .show-grid: Displays 6px grid
• .show-baseline: Displays 24px baseline
• .show-grid-baseline: Shows both

Typography Inspector

Use browser DevTools to verify:

• Computed font sizes match expected values
• Line heights align to baseline
• Spacing uses grid units

Migration Guide

From Old System

1. Replace pixel values with spacing tokens
2. Use semantic text classes instead of arbitrary sizes
3. Remove redundant media queries (fluid type handles it)
4. Update component spacing to use grid units

Quick Reference

/* Old */
font-size: 18px;
margin-bottom: 20px;
 
/* New */
@apply text-1;
@apply mb-4;

This documentation represents the current state of the typography system. All phases have been successfully implemented and the system is production-ready.