Thumbnail and Original Image Separation Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Reduce page weight and image loading cost by separating display thumbnails from original/lightbox images, while preserving current page layout and gallery browsing behavior.
Architecture: Keep existing gallery and image sections visually unchanged, but replace inline/list/card image sources with smaller thumbnail assets where beneficial, while preserving full-resolution targets for glightbox or dedicated download/original links. Apply changes incrementally to the most image-heavy pages first.
Tech Stack: MkDocs Material, Markdown, HTML, image assets, glightbox
Task 1: Identify pages where displayed images and original images are currently the same asset
Files:
- Inspect: docs/index.md
- Inspect: docs/gallery/gallery.md
- Inspect: docs/gallery/2026newyear.md
- Inspect: docs/portal.html
- Inspect: related assets under docs/assets/
Step 1: Write the failing test
Manual failing criteria: - Card/list/gallery display images use the same file as the enlarged or original image target. - Large files are still being loaded in contexts where a smaller thumbnail would suffice.
Step 2: Run verification to confirm failure
Inspect markup and identify image-heavy sections where:
- <img src> points to the same file that lightbox/open/full view uses
- no thumbnail/original separation exists yet
Expected: FAIL because the same assets are still reused for display and original contexts in multiple places.
Step 3: Write minimal implementation strategy
Define the first-wave scope: - prioritize homepage marquee / gallery-heavy sections / new year gallery grids - avoid touching pages where no zoom/full-size behavior exists yet unless image display is clearly oversized - preserve all existing captions and links
Step 4: Run verification to confirm understanding
Expected: clear list of first-wave pages/components for safe conversion.
Step 5: Commit
git add <only files changed if notes/comments were added>
git commit -m "chore: map thumbnail and original image usage"
Task 2: Separate thumbnail and original assets in the highest-impact gallery section
Files:
- Modify: docs/gallery/2026newyear.md
- Modify: docs/gallery/gallery.md
- Possibly create: exact thumbnail asset files under docs/assets/... if missing
Step 1: Write the failing test
Manual failing criteria: - The page still loads larger original image files directly into visible card/grid image slots. - Lightbox behavior relies on the same asset as the displayed image.
Step 2: Run verification to confirm failure
Inspect representative image blocks and confirm displayed image and enlarged image are the same asset.
Expected: FAIL.
Step 3: Write minimal implementation
- Use small thumbnail asset for visible
<img> - Preserve original larger asset for lightbox/open/full view target where applicable
- Keep existing captions, ordering, and layout unchanged
- Do not redesign gallery structure
- Only change file paths and attributes required for thumbnail/original separation
Step 4: Run verification to confirm it passes
Expected: - Page looks the same visually - Thumbnails load faster/lighter - Lightbox or original view still opens full image correctly
Step 5: Commit
git add docs/gallery/2026newyear.md docs/gallery/gallery.md docs/assets/<thumbnails-if-added>
git commit -m "perf: separate gallery thumbnails from original images"
Task 3: Apply the same separation to homepage and portal image showcases where safe
Files:
- Modify: docs/index.md
- Modify: docs/portal.html
- Possibly create: thumbnail asset files under docs/assets/
Step 1: Write the failing test
Manual failing criteria: - Homepage/portal display strips still use assets that are larger than necessary for visible display.
Step 2: Run verification to confirm failure
Check marquee/showcase image sections and compare displayed image usage to available original assets.
Expected: FAIL where same heavy assets are used directly.
Step 3: Write minimal implementation
- Swap visible showcase image sources to thumbnail assets
- Keep any enlarged/original target behavior intact if present
- Do not alter captions, animation wrappers, or card markup beyond necessary paths/attributes
Step 4: Run verification to confirm it passes
Expected: - homepage/portal visuals unchanged - lighter display assets used - no broken image links
Step 5: Commit
git add docs/index.md docs/portal.html docs/assets/<thumbnails-if-added>
git commit -m "perf: use thumbnails for homepage and portal showcases"
Task 4: Verify no gallery or lightbox regression
Files: - Verify only unless regression found
Step 1: Write failing verification checklist
Failure conditions: - Thumbnail appears blurry beyond acceptable display need - Lightbox opens thumbnail instead of original - Captions mismatch image - Broken image path or missing asset
Step 2: Run verification
Manually verify: - homepage image strip - portal showcase - gallery page - 2026 new year gallery - glightbox/open image flows
Step 3: Minimal implementation if needed
Only fix broken path/target/caption issues. No unrelated refactors.
Step 4: Re-run verification
Expected: pages look the same, original viewing still works, display assets are lighter.
Step 5: Commit
git add <only files changed during regression fix>
git commit -m "fix: preserve gallery behavior after thumbnail separation"
Plan complete and saved to docs/plans/2026-03-07-thumbnail-original-separation-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?