# Blog Post Performance Checklist

**Last Updated:** 2026-01-18

Use this checklist when creating or updating blog posts to ensure optimal performance and Core Web Vitals scores.

## Pre-Publication Checklist

### Images

- [ ] **All images have width/height attributes** in HTML `<img>` tags
- [ ] **Featured image** has width/height in JSON `featured_image` object
- [ ] **Content images** have width/height in JSON `images[]` array
- [ ] **Image files exist** on filesystem (`/img/insights/`)
- [ ] **Images are WebP format** (except SVGs)
- [ ] **Featured image** uses `fetchpriority="high"` and `loading="eager"`
- [ ] **Content images** use `loading="lazy"` with dimensions
- [ ] **Responsive images** have `srcset` with width descriptors
- [ ] **Sizes attribute** matches display size
- [ ] **Alt text** present for all images

### CSS & Layout

- [ ] **Image containers** use appropriate CSS (`aspect-ratio`, `contain: layout`)
- [ ] **Featured image wrapper** has `aspect-ratio: 16/9` CSS
- [ ] **Calculator containers** have `min-height` to prevent CLS
- [ ] **No inline styles** that could cause layout shifts
- [ ] **Font loading** uses `font-display: swap` (already configured)

### Content

- [ ] **Alpine.js calculators** have explicit container heights
- [ ] **Dynamic content** reserves space before loading
- [ ] **No render-blocking scripts** above fold
- [ ] **Lazy loading** used for below-fold content

## Validation Scripts

Run these scripts before publishing:

```bash
# 1. Audit image dimensions
python3 v2/scripts/blog/audit-image-dimensions.py

# 2. Analyze HTML images
python3 v2/scripts/blog/analyze-html-images.py

# 3. Verify image files exist
php v2/scripts/blog/verify-image-files.php

# 4. Fix missing dimensions (if needed)
python3 v2/scripts/blog/fix-json-image-attributes.py
python3 v2/scripts/blog/fix-image-attributes.py

# 5. Test performance (sample)
php v2/scripts/blog/analyze-blog-performance.php --limit=1 --strategy=desktop
```

## Performance Targets

- **LCP (Largest Contentful Paint):** < 2.5s
- **INP (Interaction to Next Paint):** < 200ms
- **CLS (Cumulative Layout Shift):** < 0.1 (CRITICAL)
- **PageSpeed Score:** > 90 (mobile and desktop)

## Common Issues & Fixes

### Issue: Missing Image Dimensions

**Fix:**
```bash
python3 v2/scripts/blog/fix-json-image-attributes.py
python3 v2/scripts/blog/fix-image-attributes.py
```

### Issue: High CLS Score (> 0.1)

**Check:**
1. All images have width/height attributes
2. Image containers have proper CSS
3. Calculator containers have min-height
4. No dynamic content causing layout shifts

**Fix:**
- Add missing image dimensions
- Update CSS for image containers
- Add min-height to calculator containers

### Issue: Missing Image Files

**Fix:**
1. Verify image exists in `/img/insights/`
2. Check filename matches JSON reference
3. Ensure WebP format (except SVGs)
4. Check file permissions (644)

## Post-Publication Monitoring

After publishing, monitor performance:

```bash
# Run PageSpeed analysis
php v2/scripts/blog/analyze-blog-performance.php --post={category}/{slug}

# Check CLS issues
php v2/scripts/blog/identify-cls-issues.php --date=$(date +%Y-%m-%d)
```

## Related Documentation

- `.cursor/rules/blog-templates.mdc` - Blog template patterns and performance requirements
- `docs/content/blog/BLOG_PERFORMANCE_OPTIMIZATION.md` - Complete performance optimization guide
- `docs/content/blog/IMAGE_STORAGE_GUIDE.md` - Image storage and optimization guide