CSS Refactoring Analysis

Overview

After reviewing all CSS files in /assets/css, I’ve identified significant duplication that can be consolidated into a shared base file.

Files Analyzed

1. homepage.css (454 lines) - Base styles, header, hero, sections
2. episode.css (441 lines) - Episode pages
3. search.css (271 lines) - Search page
4. page.css (293 lines) - Misc resource pages

Total: ~1,459 lines with substantial duplication

Major Duplication Found

1. Purple Gradient Pattern (appears 8+ times)

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

Found in:

• homepage.css: .header, .hero, .access-card, .session-group summary
• episode.css: .episode-hero
• search.css: .search-hero
• page.css: .page-hero

Recommendation: Create CSS variable --gradient-primary

2. Hero Section Pattern (3 duplicates)

All three page types have nearly identical hero sections:

episode.css (.episode-hero):

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 3rem 2rem 2rem;
text-align: center;

h1 {
    font-size: 2.5rem;
    margin-bottom: 1rem;
    font-weight: 800;
    line-height: 1.2;
}

search.css (.search-hero) - IDENTICAL structure page.css (.page-hero) - IDENTICAL structure

Recommendation: Create shared .hero-section class with variants

3. Content Typography (2 near-duplicates)

The .notes-content (episode.css) and .page-content (page.css) have 95% identical styling:

Both include:

• Identical h1, h2, h3, h4 styling
• Identical paragraph, list, link styling
• Identical code block styling
• Identical blockquote styling
• Identical table styling
• Identical image styling
• Identical hr styling

Lines duplicated: ~150 lines per file = 300 lines total

Recommendation: Create shared .content-area class

4. Card Pattern (3 variations)

Similar card patterns with slight variations:

• .episode-card (homepage.css)
• .search-result (search.css)
• .resource-card (page.css)

All share:

• White background
• border-radius: 12px
• Left border accent (border-left: 4px solid #667eea)
• Hover transform and shadow effects
• Similar padding

Recommendation: Create base .card class with modifiers

5. Section Container Pattern

Repeated across files:

background: white;
padding: 2rem;
border-radius: 12px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
margin: 2rem auto;

Found in:

• homepage.css: .section
• episode.css: .episode-player-section, .episode-notes-section
• search.css: .search-section
• page.css: .page-content-section

Recommendation: Create shared .section-container class

6. Responsive Breakpoints (4 duplicates)

All files use identical breakpoint:

@media (max-width: 768px) { ... }

With similar adjustments:

• Hero h1: 2.5rem → 1.8rem
• Subtitles: reduced
• Padding adjustments

Recommendation: Consolidate responsive utilities

7. Button Styles (multiple variations)

• .btn, .btn-primary, .btn-secondary (homepage.css)
• .nav-btn, .nav-btn-prev, .nav-btn-next, .nav-btn-edit (episode.css)
• .search-btn (search.css, homepage.css)

Many shared properties:

• padding: 0.75rem 1.5rem (or similar)
• border-radius: 8px
• font-weight: 600
• transition: all 0.2s
• Hover effects with transform

Recommendation: Create unified button system

8. Color Values (hardcoded throughout)

Repeated color values:

• #667eea (primary purple) - 40+ occurrences
• #764ba2 (gradient end) - 8+ occurrences
• #2c3e50 (dark text) - 25+ occurrences
• #f8f9fa (light background) - 20+ occurrences
• #e0e0e0 (borders) - 15+ occurrences

Recommendation: Use CSS variables

Proposed Refactoring Structure

New File: common.css or base.css

Contains:

1. CSS Variables
   • Colors (primary, secondary, text, backgrounds, borders)
   • Spacing scale
   • Border radius values
   • Shadow values
   • Font sizes
2. Reset & Base Styles
   • Universal box-sizing
   • Body font and colors
   • Container max-width
3. Header & Footer
   • Shared across all pages
4. Hero Section Pattern
   • Base .hero-section class
   • Modifiers for variants
5. Button System
   • Base .btn class
   • Color variants (primary, secondary, ghost)
   • Size variants
6. Card Pattern
   • Base .card class
   • Hover effects
   • Variants
7. Section Container
   • White background sections
   • Standard padding and shadow
8. Content Typography
   • Shared .content-area for markdown content
   • All typography, code, table, blockquote styles
9. Responsive Utilities
   • Standard breakpoint mixins/patterns

Updated File Structure

assets/css/
├── common.css        (NEW - ~400 lines)
├── homepage.css      (REDUCED to ~150 lines)
├── episode.css       (REDUCED to ~100 lines)
├── search.css        (REDUCED to ~80 lines)
└── page.css          (REDUCED to ~50 lines)

Total after refactoring: ~780 lines (46% reduction)

Estimated Savings

• Lines eliminated: ~680 lines (46% reduction)
• Maintenance: Single source for common patterns
• Consistency: Guaranteed visual consistency
• Performance: One shared CSS file cached across pages

Implementation Priority

Phase 1 (High Priority - Most Impact)

1. CSS Variables for colors and spacing
2. Hero section consolidation
3. Content typography (.content-area)
4. Button system

Phase 2 (Medium Priority)

1. Card pattern consolidation
2. Section container pattern
3. Header/Footer extraction

Phase 3 (Low Priority - Polish)

1. Responsive utilities
2. Animation/transition variables

eg.

1. Create CSS variables for colors, spacing, shadows, and other design tokens
2. Consolidate hero section pattern across episode, search, and page layouts
3. Extract shared content typography into .content-area class
4. Create unified button system consolidating all button variants
5. Consolidate card pattern (.episode-card, .search-result, .resource-card)
6. Create shared section container pattern
7. Migrate header and footer styles (already done, verify extraction)
8. Create responsive utility classes and consolidate breakpoints
9. Update animation/transition variables and standardize usage

Migration Notes

• Each page would need to include both common.css and its specific CSS
• Layout files would add: <link rel="stylesheet" href="/assets/css/common.css">
• Existing class names can be preserved with aliases during transition
• Can be done incrementally (one section at a time)