pr-screenshots

Context

When a PR includes visual changes (docs sites, UI components, generated pages), reviewers need to see what the PR delivers without checking out the branch. Screenshots belong in the PR description body, not as committed files and not as text descriptions.

Use this skill whenever:

• A PR touches docs site pages (Astro, Starlight, etc.)
• A PR adds or changes UI components
• A PR generates visual artifacts (TypeDoc, Storybook, diagrams)
• Playwright tests already capture screenshots as part of testing

Patterns

1. Capture screenshots with Playwright

If Playwright tests already exist and produce screenshots, reuse those. Otherwise, write a minimal capture script:

// scripts/capture-pr-screenshots.mjs
import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });

const screenshots = [
  { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' },
  { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' },
];

for (const { url, name } of screenshots) {
  await page.goto(url, { waitUntil: 'networkidle' });
  await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false });
}

await browser.close();

2. Host screenshots on a temporary branch

GitHub PR descriptions render images via URLs. The gh CLI cannot upload binary images directly. Use a temporary orphan branch to host the images:

# Save current branch
$currentBranch = git branch --show-current

# Create orphan branch with only screenshot files
git checkout --orphan screenshots-temp
git reset
git add screenshots/*.png
git commit -m "screenshots for PR review"
git push origin screenshots-temp --force

# Build raw URLs
$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
# Each image: $base/{name}.png

# Return to working branch
git checkout -f $currentBranch

3. Embed in PR description