Add light dark image support (#1756)

Author: mnkiefer

.github/workflows/guidelines.md

@@ -53,6 +53,40 @@ Use these rules across workshop authoring/editing workflows to keep the tutorial
 - Do **not** number Markdown headers inside a file. Use descriptive headings such as `### Open the Codespace`, not `### 2. Open the Codespace`.
 - Keep ordering in ordered lists, tables, filenames, and checkpoint lists instead of in the heading text itself.
 
+## Theme-aware workshop images
+
+When Playwright or another automation creates a workshop screenshot or diagram,
+generate both light and dark variants during the same run. Name them
+`<stem>-light.<ext>` and `<stem>-dark.<ext>`, then use GitHub's
+[theme-aware `<picture>` pattern](https://github.blog/developer-skills/github/how-to-make-your-images-in-markdown-on-github-adjust-for-dark-mode-and-light-mode/#one-snippet-two-themes):
+
+```html
+<picture>
+   <source media="(prefers-color-scheme: dark)" srcset="images/<stem>-dark.svg">
+   <source media="(prefers-color-scheme: light)" srcset="images/<stem>-light.svg">
+   <img alt="Concise descriptive alt text" src="images/<stem>-light.svg">
+</picture>
+```
+
+- Keep the fallback `<img>` and use the light variant as its `src`.
+- Put alt text on the fallback `<img>`; do not duplicate it on `<source>` elements.
+- Capture or render each variant with Playwright's matching `colorScheme` setting.
+- Verify in both color schemes that `currentSrc` selects the expected variant and
+   that the image is nonblank, readable, and free of clipping or overflow.
+
+Existing single-theme workshop images are migration candidates, not exceptions:
+
+- Inventory Markdown image references and HTML `src`/`srcset` references so
+   existing `<picture>` blocks remain auditable.
+- Migrate at most three existing visuals per automated pull request. Process core
+   workshop pages before setup paths, advanced topics, and side quests.
+- Preserve each visual's stem and alt text while creating `-light` and `-dark`
+   variants and replacing the original reference with the `<picture>` pattern.
+- Create a genuine theme-specific variant for UI screenshots and diagrams. A
+   theme-neutral photo may use the same existing file for both `<source>` entries
+   instead of duplicating the binary.
+- Do not delete an original asset until no Markdown or HTML reference uses it.
+
 ## Alert callouts: use `<details>` only for multi-line content
 
 ### Alert level ceiling

.github/workflows/workshop-explanatory-diagrams.md

@@ -3,8 +3,8 @@ emoji: 🧠
 name: Workshop Explanatory Diagram Generator
 description: >
   Daily workshop illustrator that finds one concept in the workshop worth
-  explaining visually, generates a polished educational SVG diagram, and opens a
-  PR with the new image and minimal markdown updates.
+  explaining visually, generates or migrates a polished light/dark SVG diagram
+  pair, and opens a PR with theme-aware markdown updates.
 on:
   schedule: daily
   workflow_dispatch:
@@ -64,6 +64,8 @@ steps:
       )
 
       image_re = re.compile(r'!\[[^\]]*\]\(([^)]+)\)')
+      picture_re = re.compile(r'<picture\b.*?</picture>', re.IGNORECASE | re.DOTALL)
+      html_image_re = re.compile(r'\b(?:src|srcset)="([^"]+)"')
       heading_re = re.compile(r'^(##+)\s+(.*)$', re.MULTILINE)
 
       file_summaries = []
@@ -74,11 +76,24 @@ steps:
               (line[2:].strip() for line in lines if line.startswith("# ")),
               path.stem,
           )
-          images = [
+            markdown_images = [
               match.group(1)
               for match in image_re.finditer(text)
               if not match.group(1).startswith(("http://", "https://"))
           ]
+            picture_blocks = picture_re.findall(text)
+            picture_images = [
+              match.group(1)
+              for block in picture_blocks
+              for match in html_image_re.finditer(block)
+              if not match.group(1).startswith(("http://", "https://"))
+            ]
+            images = list(dict.fromkeys(markdown_images + picture_images))
+            theme_aware_picture_count = sum(
+              '(prefers-color-scheme: light)' in block
+              and '(prefers-color-scheme: dark)' in block
+              for block in picture_blocks
+            )
           headings = [
               {
                   "level": len(match.group(1)),
@@ -95,6 +110,8 @@ steps:
                   "word_count": len(re.findall(r"\S+", text)),
                   "image_count": len(images),
                   "images": images,
+                  "single_theme_images": markdown_images,
+                  "theme_aware_picture_count": theme_aware_picture_count,
                   "headings": headings,
               }
           )
@@ -125,9 +142,9 @@ You are an educational illustrator for the **Learning GitHub Agentic Workflows**
 workshop.
 
 Your job is to find exactly one workshop concept that would be easier to learn
-with a visual explanation, turn that concept into a polished SVG diagram, and
-open a draft pull request with the image and the smallest markdown edit needed to
-use it.
+with a visual explanation, or one existing single-theme explanatory diagram,
+turn it into a polished light/dark SVG pair, and open a draft pull request with
+the smallest Markdown edit needed to use it.
 
 Create **at most one** pull request per run.
 
@@ -153,10 +170,22 @@ Create **at most one** pull request per run.
 
 ---
 
-## Pick one concept worth illustrating
+## Pick One Migration or Concept
+
+Inspect the selected file's `single_theme_images` first:
 
-Choose exactly one concept from the selected file that benefits from a conceptual
-visual sketch.
+1. Classify each existing image as an explanatory diagram, GitHub UI screenshot,
+  or theme-neutral photo.
+2. If an explanatory diagram exists, select exactly one for migration and do not
+  create a new concept in this run.
+3. Leave GitHub UI screenshots to `workshop-ui-screenshots`.
+4. A theme-neutral photo may be converted to a `<picture>` block that uses the
+  same file for both theme sources; do not duplicate its binary.
+
+If no existing image in the selected file needs migration, choose exactly one
+new concept worth illustrating.
+
+Choose a concept that benefits from a conceptual visual sketch.
 
 Good candidates:
 
@@ -184,24 +213,27 @@ Prefer concepts that are:
 
 ---
 
-## Create one SVG explanatory diagram
+## Create One Theme-Aware Diagram
 
-Generate exactly one SVG file for the chosen concept.
+Generate exactly one light/dark SVG pair for the chosen concept or migration.
+For a migration, preserve the original content, geometry, stem, and alt text.
 
 ### SVG style rules
 
 Match the visual family of the UI screenshot workflow while staying conceptual:
 
-- Canvas: `1200 x 560`, `viewBox="0 0 1200 560"`
-- Background: `#f6f8fa`
-- Main diagram card: white panel with rounded corners and a subtle `#d0d7de`
-  border
-- Use GitHub-aligned colors such as `#0969da`, `#1a7f37`, `#8250df`, `#bf8700`,
-  `#cf222e`, `#57606a`, and `#24292f`
+- Canvas: `1200 x 560`, `viewBox="0 0 1200 560"` for both variants
+- Keep geometry, labels, and content identical across the pair
+- Light palette: background `#f6f8fa`, panel `#ffffff`, border `#d0d7de`,
+  primary text `#24292f`, muted text `#57606a`, and accent `#0969da`
+- Dark palette: background `#0d1117`, panel `#161b22`, border `#30363d`,
+  primary text `#f0f6fc`, muted text `#8b949e`, and accent `#2f81f7`
+- Adapt semantic success, attention, danger, and done colors for sufficient
+  contrast in each theme
 - Use simple labeled boxes, arrows, chips, dashed groupings, and numbered badges
 - Keep labels short and learner-friendly
 - Add a short title inside the graphic and a short annotation below it
-- Add `role="img"` and `aria-label` matching the markdown alt text
+- Add `role="img"` and `aria-label` matching the Markdown alt text
 - Output valid, self-contained SVG only
 
 ### Diagram content rules
@@ -215,68 +247,79 @@ Match the visual family of the UI screenshot workflow while staying conceptual:
 
 ### Naming convention
 
-Write the file under `workshop/images/` using the workshop step identifier plus a
-short concept slug.
+Write both files under `workshop/images/` using the workshop step identifier plus
+a short concept slug and theme suffix.
 
 Examples:
 
 - `workshop/13-schedule-it.md` + concept `schedule loop` →
-  `workshop/images/13-schedule-loop.svg`
+  `workshop/images/13-schedule-loop-light.svg` and
+  `workshop/images/13-schedule-loop-dark.svg`
 - `workshop/16-connect-data-source.md` + concept `step-to-agent flow` →
-  `workshop/images/16-step-agent-flow.svg`
+  `workshop/images/16-step-agent-flow-light.svg` and
+  `workshop/images/16-step-agent-flow-dark.svg`
 
 If the first filename choice already exists for another concept, choose a more
 specific slug instead of overwriting unrelated work.
 
 ---
 
-## Update markdown minimally
+## Update Markdown Minimally
 
-After generating the SVG:
+After generating the SVG pair:
 
-1. Insert exactly one markdown image reference in the source workshop file near
-   the concept it explains.
+1. Insert or replace exactly one image reference in the source workshop file
+   near the concept it explains.
 2. Use this format exactly:
 
-   ```markdown
-   ![Concise descriptive alt text](images/<filename>.svg)
-   ```
+```html
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="images/<stem>-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="images/<stem>-light.svg">
+  <img alt="Concise descriptive alt text" src="images/<stem>-light.svg">
+</picture>
+```
 
-3. Keep the edit minimal and line-precise.
-4. If needed, add at most two short sentences to introduce the diagram.
-5. Do not reformat surrounding sections.
-6. Do not add more than one image per run.
+1. Use the light variant as the fallback `src`; put alt text only on `<img>`.
+2. Keep the edit minimal and line-precise.
+3. If needed, add at most two short sentences to introduce a new diagram.
+4. Do not reformat surrounding sections or migrate more than one image per run.
+5. Do not delete the original until no Markdown or HTML reference uses it.
 
 ---
 
-## Render and QA the diagram
+## Render and QA the Diagram
 
-After generating the SVG and updating markdown:
+After generating the SVG pair and updating Markdown:
 
 1. Start a local static file server from the repository root so the new
-   `workshop/images/*.svg` file is reachable on `http://127.0.0.1`.
-2. Use Playwright to render the new SVG in a browser tab.
-3. Check that all text stays inside its boxes, chips, badges, callouts, and
+  `workshop/images/*.svg` files are reachable on `http://127.0.0.1`.
+2. Use Playwright with `colorScheme: "light"` to render the exact `<picture>`
+  block and confirm its `currentSrc` ends with `-light.svg`.
+3. Repeat with `colorScheme: "dark"` and confirm `currentSrc` ends with
+  `-dark.svg`.
+4. Capture both variants and check that the images are nonblank and all text
+  stays inside its boxes, chips, badges, callouts, and
    other visual containers at normal browser zoom.
-4. If any label bleeds out of a box, revise the SVG before continuing by
-   widening the shape, wrapping or shortening the text, adjusting spacing, or
-   slightly reducing font size.
-5. Re-render after each fix until the final image is visually clean and easy to
-   read.
+5. If any label bleeds out of a box, revise both SVGs before continuing by
+  widening the shape, wrapping or shortening the text, adjusting spacing, or
+  slightly reducing font size.
+6. Re-render after each fix until both variants are visually clean, readable,
+  and selected in the intended theme.
 
 Treat this render pass as required final QA for every generated diagram.
 
 ---
 
 ## Pull request requirements
 
-If you generated a diagram, call `create-pull-request` with:
+If you generated or migrated a diagram, call `create-pull-request` with:
 
-- **Title**: `Add explanatory SVG diagram for <concept>`
+- **Title**: `Add theme-aware explanatory diagram for <concept>`
 - **Body** summarizing:
   - which workshop file changed
-  - which concept was illustrated
-  - which SVG file was added
+  - whether the change creates a concept or migrates an existing diagram
+  - both SVG files added
   - why the diagram helps learners
 
 ---
@@ -295,8 +338,9 @@ Call `noop` with a concise explanation when:
 ## Output quality requirements
 
 - Make only one coherent diagram change set per run.
-- Keep the markdown edit smaller than the SVG addition.
-- Ensure the final SVG passes a Playwright render check with no text bleeding
-  outside its visual containers.
+- Keep the Markdown edit smaller than the SVG additions.
+- Ensure both SVGs pass Playwright checks in their matching color schemes,
+  including expected `currentSrc`, nonblank pixels, and no text bleeding.
+- Use a theme-aware `<picture>` block with the light variant as fallback.
 - Do not modify files outside `workshop/`.
 - Never use write tools other than `create-pull-request` and `noop`.