Add dark mode screenshot support

capture.js now automatically generates -dark variants for screenshots
with "dark": true in manifest. Dark mode is activated by clicking the
Quarto color scheme toggle (.quarto-color-scheme-toggle). For clip
screenshots, the clip region is computed as the union of light and dark
bounding boxes so both variants have identical dimensions.

- Add light/dark theme (cosmo/darkly) to example _quarto.yml files
- Add defaults.dark config to manifest (toggle selector, ready check)
- Update all docs: CLAUDE.md, SETUP.md, capture agent, screenshot command
- Tighten about-jolla viewport to 650px to reduce bottom whitespace

Author: cderv

.claude/agents/screenshot-capture.md

@@ -74,13 +74,24 @@ playwright-cli -s=screenshot run-code "async page => {
 playwright-cli -s=screenshot screenshot --filename=<output-path>
 ```
 
-### 6. Visual validation
+### 6. Dark mode variant
+
+If the screenshot has `"dark": true` in manifest:
+1. Click the color scheme toggle: `playwright-cli -s=screenshot run-code "async page => await page.locator('.quarto-color-scheme-toggle').click()"`
+2. Wait for dark mode: `playwright-cli -s=screenshot run-code "async page => await page.locator('body.quarto-dark').waitFor()"`
+3. Re-run any interactions (e.g., dropdown may have closed during toggle)
+4. Take the screenshot again with `-dark` suffix on the filename
+5. Click toggle again to return to light mode
+
+Note: `capture.js` handles this automatically. This step is only needed for manual/interactive captures.
+
+### 7. Visual validation
 
 After capturing, verify:
 - The screenshot file was created and is non-empty
 - Report what you captured (element, viewport size, interactions performed)
 
-### 7. Close when done
+### 8. Close when done
 
 ```bash
 playwright-cli -s=screenshot close
@@ -89,7 +100,7 @@ playwright-cli -s=screenshot close
 ## Rules
 
 - ALWAYS use `-s=screenshot` session flag (avoids collisions with other sessions)
-- ALWAYS use light color scheme (default)
+- ALWAYS capture light mode first (default), then dark if needed
 - ALWAYS wait for fonts and icons to load before capturing
 - ALWAYS remove prerelease/preview banners
 - Use consistent viewport sizes from the manifest

docs/websites/images/navbar-tools.png

@@ -18,11 +18,20 @@ node tools/screenshots/capture.js --name "about-*"     # glob pattern
 
 1. Add entry to `tools/screenshots/manifest.json`
 2. If needed, create example project in `tools/screenshots/examples/`
-3. Run `/screenshot` or `capture.js`
+3. Set `"dark": true` if the screenshot needs a dark mode variant
+4. Ensure example `_quarto.yml` has `theme: { light: cosmo, dark: darkly }` for dark support
+5. Run `/screenshot` or `capture.js`
+
+## Dark Mode
+
+Screenshots with `"dark": true` in the manifest automatically get a `-dark` variant:
+- `about-jolla.png` → also generates `about-jolla-dark.png`
+- The dark variant is captured by clicking the Quarto color scheme toggle
+- Use `.include-dark` class on images in .qmd files so the filter generates both light/dark `<img>` tags
 
 ## Visual Rules
 
-- Always use light color scheme
+- Default to light color scheme (dark captured automatically when `dark: true`)
 - Wait for full page load (fonts and icons must render)
 - Remove prerelease callouts before capture (automated in defaults)
 - Remove preview/prerelease banners
@@ -41,11 +50,12 @@ node tools/screenshots/capture.js --name "about-*"     # glob pattern
 ## Tools (preference order)
 
 1. `/screenshot` command — orchestrates render, serve, capture, compress
-2. `capture.js` — automated batch replay from manifest (no AI)
+2. `capture.js` — automated batch replay from manifest (no AI, uses Playwright API directly)
 3. `playwright-cli` — direct browser control for interactive/debugging use
 
 ## Environment
 
 - `QUARTO_CMD` env var to override quarto command (default: `quarto`)
-- playwright-cli must use `-s=screenshot` session flag
+- `capture.js` uses Playwright as a Node.js library (npm dependency, no global install needed)
+- `playwright-cli` uses `-s=screenshot` session flag (for interactive/agent use)
 - oxipng compression is optional locally (CI handles it as safety net)

tools/screenshots/CLAUDE.md

@@ -4,17 +4,18 @@ Tooling for capturing and maintaining documentation screenshots in quarto-web.
 
 ## Prerequisites
 
-- **Node.js 18+** — required for scripts and playwright-cli
+- **Node.js 18+** — required for scripts and Playwright
 - **Quarto** — required for rendering example projects (set `QUARTO_CMD` env var if your binary has a different name)
 
 ## Option A: Automated Replay (no AI)
 
 ```bash
-# One-time: install playwright-cli and browser
-npm install -g @playwright/cli@latest
-playwright-cli install-browser
+# One-time: install dependencies and browser
+cd tools/screenshots
+npm install
+npx playwright install chromium
 
-# From tools/screenshots/:
+# Capture all screenshots (light + dark variants):
 npm run capture                          # all screenshots
 npm run capture -- --name navbar-tools   # specific
 npm run capture -- --name "about-*"      # glob pattern
@@ -73,27 +74,31 @@ A CI workflow compresses changed PNGs after merge to main. Local install is opti
 ```
 tools/screenshots/
 ├── manifest.json          # screenshot definitions (single source of truth)
-├── capture.js             # replay script (no AI)
-├── package.json           # type:module, npm scripts
+├── capture.js             # replay script (uses Playwright API directly)
+├── package.json           # dependencies: playwright, open
 ├── CLAUDE.md              # visual rules for Claude
 ├── SETUP.md               # this file
 ├── scripts/
 │   ├── list.js            # read + format manifest
 │   ├── render.js          # quarto render wrapper
 │   ├── serve.js           # static file server
+│   ├── open.js            # open file with OS default app
 │   └── compress.js        # oxipng wrapper
 └── examples/
-    ├── about-pages/       # about page templates
-    └── navbar-tools/      # navbar with dropdown
+    ├── about-pages/       # about page templates (light + dark theme)
+    └── navbar-tools/      # navbar with dropdown (light + dark theme)
 ```
 
 ## Manifest Format
 
 Each screenshot in `manifest.json` specifies:
 - `name` — unique identifier
 - `output` — output PNG path (relative to repo root)
+- `dark` — if `true`, also captures a `-dark` variant (e.g. `about-jolla-dark.png`)
 - `source` — where to get the page (example project, URL, or local)
-- `capture` — viewport, interactions, element selector
+- `capture` — viewport, interactions, clip selectors, element selector
 - `doc` — which .qmd file references this image
 
+Dark mode works by clicking the Quarto color scheme toggle (`.quarto-color-scheme-toggle`). Example projects must have `theme: { light: cosmo, dark: darkly }` in `_quarto.yml`.
+
 See `manifest.json` for the full schema.

tools/screenshots/SETUP.md

@@ -54,6 +54,10 @@ if (screenshots.length === 0) {
 if (listOnly) {
   for (const s of screenshots) {
     console.log(`${s.name} → ${s.output}`);
+    if (s.dark) {
+      const ext = s.output.lastIndexOf('.');
+      console.log(`${s.name} (dark) → ${s.output.slice(0, ext)}-dark${s.output.slice(ext)}`);
+    }
   }
   process.exit(0);
 }
@@ -143,32 +147,61 @@ async function runInteractions(page, shot) {
   }
 }
 
-// Take a screenshot
-async function takeScreenshot(page, shot) {
-  const outputPath = resolve(REPO_ROOT, shot.output);
+// Compute dark output path: about-jolla.png → about-jolla-dark.png
+function darkOutputPath(outputPath) {
+  const ext = outputPath.lastIndexOf('.');
+  return outputPath.slice(0, ext) + '-dark' + outputPath.slice(ext);
+}
 
-  if (shot.capture?.clip) {
-    // Clip screenshot: union bounding box of multiple selectors
-    const selectors = shot.capture.clip;
-    const boxes = [];
-    for (const sel of selectors) {
-      const loc = page.locator(sel);
-      if (await loc.count() > 0) {
-        const box = await loc.first().boundingBox();
-        if (box) boxes.push(box);
-      }
+// Switch to dark mode by clicking the toggle
+async function switchToDark(page) {
+  const darkConfig = manifest.defaults.dark;
+  await page.locator(darkConfig.toggle).click();
+  await page.locator(darkConfig.ready).waitFor({ timeout: 5000 });
+  if (darkConfig.settle) {
+    await page.waitForTimeout(darkConfig.settle);
+  }
+}
+
+// Switch back to light mode
+async function switchToLight(page) {
+  const darkConfig = manifest.defaults.dark;
+  await page.locator(darkConfig.toggle).click();
+  // Wait for dark class to be removed
+  const readySelector = darkConfig.ready.replace('.quarto-dark', '.quarto-light');
+  await page.locator(readySelector).waitFor({ timeout: 5000 });
+  if (darkConfig.settle) {
+    await page.waitForTimeout(darkConfig.settle);
+  }
+}
+
+// Compute clip region from selectors
+async function computeClip(page, selectors) {
+  const boxes = [];
+  for (const sel of selectors) {
+    const loc = page.locator(sel);
+    if (await loc.count() > 0) {
+      const box = await loc.first().boundingBox();
+      if (box) boxes.push(box);
     }
-    if (boxes.length === 0) throw new Error('No clip selectors matched');
-    const vp = page.viewportSize();
-    const pad = 10;
-    const x = Math.max(0, Math.min(...boxes.map(b => b.x)) - pad);
-    const y = Math.max(0, Math.min(...boxes.map(b => b.y)) - pad);
-    const right = Math.min(Math.max(...boxes.map(b => b.x + b.width)) + pad, vp.width);
-    const bottom = Math.min(Math.max(...boxes.map(b => b.y + b.height)) + pad, vp.height);
-    await page.screenshot({
-      path: outputPath,
-      clip: { x, y, width: right - x, height: bottom - y }
-    });
+  }
+  if (boxes.length === 0) throw new Error('No clip selectors matched');
+  const vp = page.viewportSize();
+  const pad = 10;
+  const x = Math.max(0, Math.min(...boxes.map(b => b.x)) - pad);
+  const y = Math.max(0, Math.min(...boxes.map(b => b.y)) - pad);
+  const right = Math.min(Math.max(...boxes.map(b => b.x + b.width)) + pad, vp.width);
+  const bottom = Math.min(Math.max(...boxes.map(b => b.y + b.height)) + pad, vp.height);
+  return { x, y, width: right - x, height: bottom - y };
+}
+
+// Take a screenshot (optionally override output path and/or clip)
+async function takeScreenshot(page, shot, overridePath, overrideClip) {
+  const outputPath = overridePath || resolve(REPO_ROOT, shot.output);
+
+  if (shot.capture?.clip) {
+    const clip = overrideClip || await computeClip(page, shot.capture.clip);
+    await page.screenshot({ path: outputPath, clip });
   } else if (shot.capture?.element) {
     await page.locator(shot.capture.element).screenshot({ path: outputPath });
   } else {
@@ -261,12 +294,45 @@ async function main() {
             // Interactions
             await runInteractions(page, shot);
 
-            // Screenshot
-            const outputPath = await takeScreenshot(page, shot);
+            // For dark variants with clip: compute union clip across both modes
+            // so light and dark screenshots have identical dimensions
+            let sharedClip = null;
+            if (shot.dark && shot.capture?.clip) {
+              const lightClip = await computeClip(page, shot.capture.clip);
+              await switchToDark(page);
+              await runInteractions(page, shot);
+              const darkClip = await computeClip(page, shot.capture.clip);
+              // Union of both clip regions
+              const x = Math.min(lightClip.x, darkClip.x);
+              const y = Math.min(lightClip.y, darkClip.y);
+              const right = Math.max(lightClip.x + lightClip.width, darkClip.x + darkClip.width);
+              const bottom = Math.max(lightClip.y + lightClip.height, darkClip.y + darkClip.height);
+              sharedClip = { x, y, width: right - x, height: bottom - y };
+              // Take dark screenshot while we're here
+              const darkPath = darkOutputPath(resolve(REPO_ROOT, shot.output));
+              console.log(`  ${shot.name} (dark)...`);
+              await takeScreenshot(page, shot, darkPath, sharedClip);
+              compressPng(darkPath);
+              // Switch back to light for the light screenshot
+              await switchToLight(page);
+              await runInteractions(page, shot);
+            }
 
-            // Compress
+            // Light screenshot
+            const outputPath = await takeScreenshot(page, shot, null, sharedClip);
             compressPng(outputPath);
 
+            // Dark variant (non-clip mode: element or viewport)
+            if (shot.dark && !shot.capture?.clip) {
+              console.log(`  ${shot.name} (dark)...`);
+              await switchToDark(page);
+              const darkPath = darkOutputPath(outputPath);
+              await runInteractions(page, shot);
+              await takeScreenshot(page, shot, darkPath);
+              compressPng(darkPath);
+              await switchToLight(page);
+            }
+
             // Verify — open image for visual review
             if (verify) {
               console.log(`  Opening for review: ${outputPath}`);

tools/screenshots/capture.js

@@ -6,3 +6,9 @@ project:
 
 website:
   title: "About Pages"
+
+format:
+  html:
+    theme:
+      light: cosmo
+      dark: darkly

tools/screenshots/examples/about-pages/_quarto.yml

@@ -3,6 +3,12 @@ project:
   render:
     - index.qmd
 
+format:
+  html:
+    theme:
+      light: cosmo
+      dark: darkly
+
 website:
   title: "ProjectX"
   navbar:

tools/screenshots/examples/navbar-tools/_quarto.yml

@@ -5,15 +5,21 @@
     "cleanup": [
       { "action": "eval", "script": "document.querySelectorAll('.callout-note').forEach(el => { if (el.textContent.includes('Pre-release')) el.remove() })" },
       { "action": "eval", "script": "document.querySelectorAll('[class*=prerelease],[class*=preview]').forEach(el => el.remove())" }
-    ]
+    ],
+    "dark": {
+      "toggle": ".quarto-color-scheme-toggle",
+      "ready": "body.quarto-dark",
+      "settle": 500
+    }
   },
   "screenshots": [
     {
       "name": "about-jolla",
       "output": "docs/websites/images/about-jolla.png",
+      "dark": true,
       "source": { "type": "example", "project": "examples/about-pages", "page": "jolla.html" },
       "capture": {
-        "viewport": { "width": 1200, "height": 900 },
+        "viewport": { "width": 1200, "height": 650 },
         "clip": [".quarto-about-jolla"]
       },
       "doc": {
@@ -24,6 +30,7 @@
     {
       "name": "navbar-tools",
       "output": "docs/websites/images/navbar-tools.png",
+      "dark": true,
       "source": { "type": "example", "project": "examples/navbar-tools", "page": "index.html" },
       "capture": {
         "viewport": { "width": 1440, "height": 400 },