Critical Image Priority and Dimensions Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Reduce LCP and layout instability by adding accurate dimensions and selective high-priority loading to truly critical homepage images without changing visual layout or image content.

Architecture: Update only homepage and any directly related template markup where key images are rendered. Keep the scope narrow: identify the actual above-the-fold/LCP candidate image(s), add exact width/height, and apply fetchpriority="high" only to those critical images. Non-critical images are left for later tasks.

Tech Stack: MkDocs Material, Markdown with embedded HTML, browser image loading attributes (width, height, fetchpriority)

Task 1: Identify real critical homepage images

Files: - Modify: docs/index.md - Verify: homepage image blocks around the hero/featured content

Step 1: Write the failing test

Manual failing criteria: - Homepage critical image markup lacks explicit width/height - Homepage likely LCP image is not marked with fetchpriority="high" - Some marquee or secondary images may be incorrectly treated as critical

Step 2: Run verification to confirm failure

Inspect docs/index.md and identify: - the truly above-the-fold prominent image (assets/IMG_023.jpg appears likely) - any other image currently visible but not actually LCP-critical

Expected: FAIL because dimensions and critical priority are not fully specified yet.

Step 3: Write minimal implementation

Add exact width and height to the true critical homepage image(s)
Add fetchpriority="high" only to the real LCP candidate image
Do not add fetchpriority="high" to marquee images, icon strips, gallery loops, or below-the-fold content
Preserve existing inline styles and layout behavior

Step 4: Run verification to confirm success

Manual checks: - The homepage still renders visually the same - No image distortion appears - Only one or very few truly critical images receive fetchpriority="high"

Expected: PASS.

Step 5: Commit

git add docs/index.md
git commit -m "perf: prioritize critical homepage image loading"

Task 2: Add explicit dimensions to remaining homepage image groups that affect stability

Files: - Modify: docs/index.md - Verify: marquee images and server icon strip on homepage

Step 1: Write the failing test

Manual failing criteria: - Homepage image groups still render without explicit dimensions - Browser cannot reserve exact layout box before image decode

Step 2: Run verification to confirm failure

Inspect image tags in: - marquee section (assets/C (...)) - server icon strip (assets/TCYserver (...))

Expected: FAIL because dimensions are still missing or partial.

Step 3: Write minimal implementation

Add exact width/height attributes to homepage image groups where size is known and stable
Do not alter CSS layout model or replace inline style structure
Do not change image paths or loading behavior beyond dimensions for this task

Step 4: Run verification to confirm success

Manual checks: - Images display at same visible size as before - No distortion, no broken layout, no wrapping regressions

Expected: PASS.

Step 5: Commit

git add docs/index.md
git commit -m "perf: add stable dimensions to homepage image groups"

Task 3: Verify homepage rendering remains unchanged

Files: - Verify only unless regression found

Step 1: Write failing verification checklist

Define failure conditions: - Key image visibly stretched or squashed - Marquee layout shifts or clips unexpectedly - Server icon strip spacing changes - Critical image priority applied too broadly

Step 2: Run verification

Check homepage in browser: - hero/featured image - marquee image strip - server icon section

Expected before verification: regressions unknown.

Step 3: Minimal implementation if needed

Only fix incorrect dimensions or over-applied priority. No extra optimizations.

Step 4: Re-run verification

Expected: homepage looks identical, with only loading metadata improved.

Step 5: Commit

git add docs/index.md
git commit -m "fix: preserve homepage layout after image priority updates"

Plan complete and saved to docs/plans/2026-03-07-critical-image-priority-plan.md. Two execution options:

1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration

2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints

Which approach?