# Blog CSS Split Maintenance Guide

**Last Updated:** 2026-02-24

## Overview

Blog styles are split into three files for page-type-specific loading:

| File | Purpose | Loaded By |
|------|---------|-----------|
| **blog-base.css** | Variables, post-card, breadcrumbs, pagination, shared styles | All blog pages |
| **blog-index.css** | Hero, category cards, filters, pillar visuals, topic-hub | index.php, category.php, topic-hub.php |
| **blog-post.css** | Post header, content, TOC, related, FAQ, lightbox | post.php, v2/html/blog/*.html |

## When to Add to Each File

### blog-base.css
- `:root` variables
- `body.blog-page`, `[x-cloak]`
- Post card styles (used on index, category, post, topic-hub)
- Breadcrumbs, pagination
- Related posts grid
- Skeleton cards
- Post-header-category-link (used by PillarHeroSideBySide and PostHeader)
- Featured post hero (shared structure)

### blog-index.css
- Blog index hero, category cards
- Blog filter buttons
- Pillar hero, pillar visuals
- Topic-hub hero
- Blog posts section layout
- Category nav

### blog-post.css
- Post header (full), post content
- Blog TOC
- Blog FAQ
- Blog image lightbox
- Blog related carousel
- Content typography (`.post-content-inner` h1–h6, p, ul, blockquote, etc.)
- WordPress embed styles, formula-block, blog-note

## How to Run Selector Mapping

Before adding new styles, verify which file they belong to:

```bash
python3 v2/scripts/blog/blog-selector-page-mapping.py
```

Output: `docs/analysis/blog-selector-page-mapping.json` with `split_assignment` (base, index, post).

## Editing Workflow

**Edit the split files directly:** `blog-base.css`, `blog-index.css`, `blog-post.css`.

After editing any CSS file:

```bash
npm run minify
```

To consolidate duplicate media queries: `python3 v2/scripts/blog/consolidate-blog-media-queries.py` then `npm run minify`.

## Testing Checklist After CSS Changes

1. **Visual regression:** `php v2/scripts/blog/test-css-visual.php http://localhost:8003`
2. **Manual check:** Index, category (lexikon), post (minijob), topic-hub
3. **Verify:** Post cards, TOC, related carousel, FAQs, lightbox, pagination, filters
4. **Minify:** `npm run minify` → verify `.min.css` files updated

## Related Documentation

- [blog-css-split-mapping.md](../../analysis/blog-css-split-mapping.md) – Selector mapping and spot-check validation
- [CSS_ARCHITECTURE.md](../../systems/css/CSS_ARCHITECTURE.md) – Blog split section
- [CSS_OPTIMIZATION_REPORT.md](CSS_OPTIMIZATION_REPORT.md) – Split summary