Repair dark-mode illustration counterparts across course surfaces

Outcome

Every theme-switched watercolor illustration used by the course catalogue, course-family pages, and tour must have a genuine dark companion that preserves the approved light composition while visually belonging on the site's dark surfaces. Dark mode must show the matching course or scene, not an unrelated generic/homepage illustration and not a saturated blue plate pasted onto navy.

Nine already-generated replacements in the shared worktree are the implementation starting point and must be preserved. Their accepted filenames and hashes are recorded in _docs/design/references/dark-counterpart-audit-20260917.md. The four accepted homepage dark illustrations remain the visual authority and remain unchanged.

Normative guidance:

• Website illustration workflow
• Illustration asset production and review
• Design-system illustration and accessibility contract
• Course and cohort product contract

Product decisions

• A known course family uses its own light/dark pair everywhere the shared course-illustration include is consumed. Unknown families use the generic course-learning pair.
• A dark companion is a separately generated illustration, not a CSS filter, mechanical recolour, borrowed homepage scene, copied wash, or opaque page-coloured panel.
• The approved light illustration is the composition anchor. Its subject, meaning, count, pose, scale, object placement, labels, and foreground treatment remain recognizable in the dark companion.
• The accepted homepage dark assets define the dark visual language: compact low-saturation charcoal/slate-indigo atmosphere, foreground clarity, and an irregular edge that loses opacity into the actual surface. Technically valid alpha is insufficient if the image still reads as a plate.
• Illustrations remain decorative. Surrounding page copy carries meaning; images keep empty alternative text and asynchronous decoding.

Scope

1. Preserve and install the nine accepted dark replacements recorded in the 2026-09-17 audit: the six named course-family scenes, generic course learning, neutral journey start, and tour community hero.
2. Keep the shared course-illustration mapping truthful: each of the six known family slugs selects its matching dark file; an unknown/missing slug selects the generic pair. Remove any catalogue-only substitution that pairs a course's light art with unrelated homepage dark art.
3. Cover every current consumer of these pairs: /courses hero collage and catalogue cards, /courses/<family> hero and journey, and /tour hero and course cards. Preserve the current responsive decision that keeps family hero art visible and centered at <=47.99rem, capped at 12rem wide.
4. Update the non-mutating course-illustration browser checker to the catalogue DOM delivered by #417 and make it inspect every rendered hero/catalogue media slot, both themes, and all supported viewports.
5. Keep a durable generation record with the actual references, prompts, backend status, raw/final hashes, chroma-removal parameters, rejected iterations, pixel/alpha checks, and browser evidence. All raw generation output, previews, and screenshots stay below .tmp/.
6. Add regression coverage for complete light/dark filename pairing, correct template mappings, current consumers, theme visibility, decode success, stable geometry, and the checker's current selectors.

Non-goals

• Regenerating or modifying the approved light course, journey, tour, or homepage illustrations.
• Modifying the four accepted homepage dark companions.
• Redesigning the course catalogue, course-family page, tour, cards, hero layout, copy, registration state, or course ordering; those remain owned by their respective issues, especially #417.
• Replacing authored campaign images, portraits, sponsor logos, media-kit art, lesson screenshots, or other images that are not theme-switched watercolor illustrations.
• Adding new course-family concepts or inventing catalogue entries.
• Hiding poor edges with CSS blur, masks, filters, shadows, recolouring, crops, or opaque backgrounds.
• Merging unrelated branches, committing unrelated shared-worktree changes, or cleaning another agent's worktree.

Dependencies and coordination

• Depends on #417 for the final unified catalogue component and its .catalog-card-media contract. Land #417 first, then rebase this work and verify against that final DOM; do not restore the retired .open-card-media, .active-card-media, or .selfpaced-card-media variants.
• The nine accepted WebPs and their audit record currently exist only as unique uncommitted shared-worktree changes. Preserve them before any checkout, rebase, worktree cleanup, or branch merge. Do not regenerate accepted files merely to recreate lost state.
• The course illustration include is shared by catalogue, family, and tour surfaces. A mapping change must be verified on all three rather than accepted from one route.
• If any accepted asset must be regenerated after review, use the built-in image-generation tool and the repository workflow. The backend is recorded as unverified when the tool exposes no reliable version metadata; never request or inspect an API key.

Acceptance criteria

• The nine installed dark WebPs match the filenames, dimensions, and SHA-256 values in dark-counterpart-audit-20260917.md: course-learning-dark.webp is 1024x1024; the other eight are 1254x1254.
• Every light WebP in core/static/core/illustrations/ has exactly one -dark.webp companion, with no orphan dark filename; the automated asset-pair test enforces this inventory.
• The six known course-family slugs (ai-dev-tools-zoomcamp, de-zoomcamp, ml-zoomcamp, mlops-zoomcamp, llm-zoomcamp, sma-zoomcamp) render their matching light and dark paths. Missing/unknown slugs render the generic course-learning pair.
• /courses hero-collage and .catalog-card-media slots use the same family-specific pair. No dark_variant or equivalent maps a family light image to home-hero, home-step-2, home-step-3, or another unrelated scene.
• /courses/<family> renders the matching family pair in its hero; its first journey stage renders the course-journey-start pair. /tour renders the tour-community pair in its hero and matching family pairs in its course cards.
• At <=47.99rem, family hero art remains visible, centered, and no wider than 12rem; exactly one matching theme variant is visible and switching themes does not change the slot's geometry.
• All illustration images retain alt="", decoding="async", declared intrinsic dimensions, the caller's eager/lazy loading behavior, and exactly one visible theme variant when the slot is meant to be visible.
• The approved light files and four accepted homepage dark files are byte-for-byte unchanged by this issue.
• Native and enlarged review finds no malformed anatomy, detached limbs, damaged hands/screens, text artifacts, compression noise, coarse speckles, disconnected dots, or jagged edges.
• On the real dark page/card surfaces, every replacement has genuine transparency and an irregular, subdued edge with no cobalt/royal-blue island, pale rim, halo, glow, hard contour, straight seam, rectangular/oval/scalloped plate, or large empty wash geometry.
• Retained native PNG sources and installed lossless WebPs decode to identical RGBA at the declared dimensions; all four canvas borders contain transparent pixels and no residual chroma fringe.
• scripts/dev/check_course_illustrations.py targets the final .catalog-card-media component, visits every discovered course-family route without database writes, waits for image decode, checks visible theme/path/accessibility/overflow state, and reports a failure when a rendered slot is empty, unpaired, undecoded, clipped, or showing the wrong theme.
• Focused Django tests cover asset inventory, known/unknown mappings, catalogue/family/tour consumers, and decorative-image attributes. Applicable Playwright coverage asserts current selectors and light/dark theme switching without layout shift.
• The repository-selected verification plan is generated from the frozen base/head and all required Django, illustration-tool, and Playwright components pass. Because templates and rendered assets change, independent tester screenshots and PM acceptance are required before commit.

Browser scenarios

1. Seed or use a catalogue containing all six known course families. At /courses, inspect the hero collage and all six catalogue cards at 1440x900, 768x1024, 390x844, and 320x740 in light and dark mode. Each card keeps its own subject across themes, every visible image is decoded, and the page has no horizontal overflow.
2. On /courses, toggle light → dark → light. Exactly one variant per slot is visible after each toggle; captions, card geometry, scroll position, and image slot bounds do not jump. In dark mode, no slot substitutes an unrelated homepage scene.
3. Visit each of the six /courses/<family> routes at desktop and mobile widths in both themes. The visible hero matches that family and blends into the actual hero surface. At mobile widths it remains centered and at most 12rem wide, exactly one light/dark variant is visible, theme switching preserves its bounds, and the page does not overflow.
4. On a family page with the transformation journey, scroll to the first stage in both themes and verify the neutral course-journey-start scene switches to its own accepted dark companion. The existing learning/shipping stages remain unchanged.
5. Visit /tour in both themes at desktop and mobile widths. Verify the community hero uses tour-community-dark.webp in dark mode and each visible course card uses its matching family companion; inspect edges on their actual page/card grounds.
6. Run the browser checker against the requested development host with default discovery and all four viewports. Read every generated screenshot rather than relying only on the JSON report; confirm it captured the intended pages, not an error/debug page, and that every reported check passes.

Evidence to attach

• Base/head and change-selective verification plan/report.
• Exact asset SHA-256, dimensions, alpha/border, PNG↔WebP RGBA comparison, and illustration-tool test results.
• Focused Django and Playwright commands with counts/results.
• Full-page and opening screenshots for /courses, representative known/unknown family pages, and /tour at desktop/mobile in both themes, plus native/enlarged edge review.
• Final worktree status showing that unrelated shared-worktree changes were not included.

Start with #417's final catalogue DOM, the audit at _docs/design/references/dark-counterpart-audit-20260917.md, and assets under core/static/core/illustrations/. Run scripts/dev/check_course_illustrations.py across its discovered routes and viewports, then inspect the shared course-illustration mapping and its Django/Playwright coverage. Done means all nine assets, pairings, consumers, theme states, decoding checks, and required browser evidence pass without changing approved light or homepage files.