docs: add Ghost theme migration task (Casper→Source)

Session 36 spent 2+ hours fighting Casper CSS specificity issues.
Even html body .class element !important gets overridden.
Gemini recommends migrating to Source theme (official, minimal, dev-friendly).
Task includes complete migration plan with rollback strategy.
This commit is contained in:
Claude
2026-03-21 06:27:04 +00:00
parent 2e7a4fe60c
commit 33347e55f4

View File

@@ -0,0 +1,103 @@
# 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