internetforkids/IMPLEMENTATION_GUIDE.md

# Implementation Guide: Typography Redesign
## For internetforkids.org (Hugo + Congo Theme)

### EASIEST PATH: Modify Congo Theme

The Congo theme is already set up - no need to switch themes. Just customize typography files.

#### Step 1: Update Font Imports
**File:** `layouts/partials/head.html` or `config/_default/params.toml`

Add Google Fonts (if using Option A or B):
```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Crimson+Text:wght@400;600&family=Oxygen:wght@400;700&display=swap" rel="stylesheet">
```

Or for Option B:
```html
<link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,wght@0,400;0,600;1,400&display=swap" rel="stylesheet">
```

#### Step 2: Override Congo's CSS
**File:** `assets/css/custom.css` (create if doesn't exist)

```css
/* Option A: Sam Altman Style */
:root {
  --font-serif: 'Crimson Text', Georgia, serif;
  --font-sans: 'Oxygen', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

body {
  font-family: var(--font-sans);
  font-size: 16px;
  line-height: 1.6;
  color: #555;
}

h1, h2, h3, h4, h5, h6 {
  font-family: var(--font-serif);
  font-weight: 400;
}

h1 { font-size: 50px; }
h2 { font-size: 28px; }
h3 { font-size: 24px; }

article {
  max-width: 600px;
  margin: 0 auto;
}

/* Add spacing between articles */
article + article {
  margin-top: 80px;
}
```

Or Option B (Dario Amodei):
```css
:root {
  --font-serif: Georgia, 'Times New Roman', serif;
}

body {
  font-family: var(--font-serif);
  font-size: 20px;
  line-height: 1.6;
  color: #1f1e1d;
  background-color: #f0ede6;
}

h1, h2, h3, h4, h5, h6 {
  font-family: var(--font-serif);
  font-weight: 600;
}

h1 { font-size: 36px; }
h2 { font-size: 24px; }

article {
  max-width: 800px;
  margin: 0 auto;
  padding: 40px 20px;
}

p {
  margin-bottom: 20px;
}
```

#### Step 3: Update Congo config
**File:** `config/_default/params.toml`

```toml
# Change this line if using warm background:
# colorScheme = "avocado"  # Current
colorScheme = "slate"      # For Option A (darker)

defaultAppearance = "light"

[article]
  showDate = true
  showReadingTime = true
  showAuthor = true
  showBreadcrumbs = true
  showTableOfContents = true
```

#### Step 4: Build & Test
```bash
hugo server
# Visit http://localhost:1313 to preview changes
```

---

### MEDIUM PATH: Switch to Blowfish Theme

Blowfish is modern, actively maintained, and Tailwind-based.

**Pros:**
- Better performance (Tailwind CSS)
- Modern design foundation
- Easy typography customization

**Cons:**
- Requires theme migration
- May need content restructuring

**Steps:**
1. Clone Blowfish: `git submodule add https://github.com/nunocoracao/blowfish themes/blowfish`
2. Update `config.toml`: `theme = "blowfish"`
3. Customize `assets/css/custom.css` with serif fonts
4. Copy content structure from Congo

---

### CUSTOM THEME PATH: Build from Scratch

**Only if neither Congo customization nor Blowfish works.**

Would require:
1. Creating new Hugo theme folder
2. Implementing all layouts (baseof.html, single.html, list.html, etc.)
3. Writing custom CSS
4. Time investment: 15-20 hours

---

### RECOMMENDED IMPLEMENTATION ORDER

#### Phase 1: Quick Win (Day 1)
1. Add Google Fonts to layout
2. Add custom.css with typography rules
3. Test locally with `hugo server`
4. Check all article pages render correctly

#### Phase 2: Fine-tuning (Day 2)
1. Adjust font sizes for mobile responsiveness
2. Test on different screen sizes
3. Verify links, navigation, colors work
4. Get feedback from team

#### Phase 3: Deployment (Day 3)
1. Deploy to staging if available
2. Live testing on actual domain
3. Deploy to production
4. Monitor for issues

---

### RESPONSIVE CONSIDERATIONS

Add mobile breakpoints to custom.css:

```css
/* Mobile adjustments */
@media (max-width: 768px) {
  body {
    font-size: 16px;  /* Don't go smaller on mobile */
  }
  
  h1 {
    font-size: 28px;  /* Scale down headings */
  }
  
  h2 {
    font-size: 20px;
  }
  
  article {
    max-width: 100%;  /* Use full width on mobile */
    padding: 20px;    /* But add side padding */
  }
}
```

---

### TESTING CHECKLIST

- [ ] Homepage renders correctly
- [ ] Article pages display proper typography
- [ ] Mobile view is readable
- [ ] Dark mode works (if enabled)
- [ ] Links are visible and clickable
- [ ] Images scale properly
- [ ] Code blocks are readable
- [ ] Lists and blockquotes look good
- [ ] Date/author metadata is clear
- [ ] Sidebar navigation works

---

### ROLLBACK PLAN

If changes don't work:
1. Delete `assets/css/custom.css`
2. Revert `config/_default/params.toml` changes
3. Restart Hugo server
4. Original Congo theme returns

No destructive changes - fully reversible.

---

### FILE LOCATIONS TO MODIFY

```
internetforkids/
├── config/
│   └── _default/
│       └── params.toml          # Update font settings
├── assets/
│   └── css/
│       └── custom.css           # ADD new file with typography
├── layouts/
│   └── partials/
│       └── head.html            # ADD Google Fonts link
└── themes/
    └── congo/                   # Don't modify directly
```

---

### QUICK COMMAND REFERENCE

```bash
# View live preview
hugo server

# Check for errors
hugo server --debug

# Build static site
hugo

# Watch for changes
hugo server --watch
```

---

### FONT PAIRING LOGIC

**Rule:** Serif + Sans creates visual contrast

- Serif headings = authority, elegance
- Sans body = modern, readable
- Same serif throughout = literary, unified

Pick ONE approach and stick with it.