Skip to content

Add light dark image support #1756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mnkiefer merged 2 commits into from
Jul 21, 2026
Merged

Add light dark image support #1756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cccdc64
Add theme-aware image guidelines and update screenshot generator for …
mnkiefer Jul 21, 2026
625d40d
Update diagram generation to support light/dark SVG pairs
mnkiefer Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .github/workflows/guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
144 changes: 94 additions & 50 deletions .github/workflows/workshop-explanatory-diagrams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 = []
Expand All @@ -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)),
Expand All @@ -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,
}
)
Expand Down Expand Up @@ -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.

Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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

---
Expand All @@ -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`.
Loading