firefrost-operations-manual/docs/tasks/ghost-theme-migration/README.md

Task: Migrate from Casper to Source Theme

Priority: HIGH

Reason: Current Casper theme creates CSS specificity battles that waste hours per session. Even !important rules with high specificity get overridden.

Problem Statement

Casper theme has opinionated CSS architecture that:

• Overrides custom CSS even with html body .class element !important specificity
• Fights full-width layouts with rigid .gh-canvas grid system
• Requires inline !important on every font-size property as workaround
• Makes future customization painful and time-consuming

Evidence: Session 36 spent 2+ hours debugging why html body .ffg-custom-text h2 { font-size: 4rem !important; } was overridden by Casper's base h2 { font-size: 2.8rem; } rule despite lower specificity.

Recommended Solution

Migrate to Source theme (official Ghost theme)

Why Source:

• Official Ghost core team theme
• Minimal CSS opinions, designed as blank canvas
• Guaranteed compatibility with Ghost updates
• HTML cards span naturally without grid constraints
• Uses CSS variables for easy theming

Alternatives considered:

• Ghost Starter Theme (too bare, requires building everything)
• Edition (newsletter-focused, less suitable for gaming community)

Migration Process (Zero Downtime)

Pre-Migration Backup

1. Backup current Casper fork:

   • Ghost Admin → Settings → Design & Branding → Customize
   • Click Advanced (top right) → Download
   • Store in /home/claude/ghost-backups/casper-fork-YYYY-MM-DD.zip

2. Backup site content:

   • Settings → Labs → Export your content
   • Save JSON file to /home/claude/ghost-backups/content-YYYY-MM-DD.json

3. Backup routes:

   • Settings → Labs → Routes → Download current routes.yaml
   • Save to /home/claude/ghost-backups/routes-YYYY-MM-DD.yaml

CSS Variable Setup

BEFORE activating new theme, add Fire/Frost branding variables to Site Header:

:root { /* Fire/Frost Brand Colors */ --ffg-teal: #4ecdc4; --ffg-orange: #ff6b35; --ffg-purple: #a855f7; --ffg-gold: #FFD700;

/* Backgrounds */
--ffg-bg-dark: #0f0f1e;
--ffg-bg-darker: #0a0a1a;

/* Typography */
--ffg-text-primary: #ffffff;
--ffg-text-secondary: #a8dadc;
--ffg-text-tertiary: #6b7280;

}

Theme Installation

1. Download Source theme: https://github.com/TryGhost/Source
2. Upload to Ghost: Settings → Design & Branding → Change Theme → Upload Theme
3. Click Preview button (not Activate)

QA Checklist (In Preview Mode)

• Section 1 (Hero) - full width, logo visible, text readable
• Section 2 (Choose Your Destiny) - cards display properly
• Section 3 (Why Firefrost) - 3-column grid intact
• Section 4 (Community Awaits) - stats display correctly
• Section 5 (Origin Story) - text formatting preserved
• Footer - all 3 columns, social links visible

Activation

1. Click Activate in theme preview
2. Open incognito window
3. Visit firefrostgaming.com and hard refresh

Post-Migration Cleanup

1. Refactor homepage HTML sections - remove all inline font-size: X !important
2. Consolidate CSS in Site Header injection
3. Test responsiveness on mobile/tablet

Rollback Plan

1. Settings → Design & Branding → Change Theme → Upload backed-up Casper fork
2. Activate immediately

Success Criteria

• Homepage renders identically to current Casper version
• Custom CSS applies without inline !important workarounds
• Typography sizes match design (4rem h2, 2.5rem h3, etc.)
• Full-width layout works without right-shift
• Zero downtime during migration

Estimated Time: ~2 hours

---

Created: Session 36 (The Chronicler #36) Status: PENDING