Pr-Screenshots

# PR Screenshots

Embed before/after screenshots in pull request descriptions so reviewers can see the visual change without checking out the branch.

When to Use This Skill

Use this skill when a PR changes something visible:

- Layout, styling, CSS

- Charts, dashboards, data visualizations

- UI components, forms, modals

- Error messages, CLI output, log formatting

PR Description Pattern

Place screenshots directly in the PR description body. Avoid wrapping them in `<details>` collapse — reviewers are more likely to look at images they can see without clicking.

**Before** — brief description of the problem:

![before](url-to-before-image)

**After** — brief description of the fix:

![after](url-to-after-image)

Keep the text brief. A sentence or two per image describing what the reader should notice. Let the image carry most of the communication.

Multiple changes

For PRs with several visual changes, use separate before/after pairs with headings:

## Filter bar alignment

**Before** — 1px border clash between adjacent buttons:

![before-filters](url)

**After** — borders overlap cleanly, hover tint added:

![after-filters](url)

## Chart tooltip

**Before** — tooltip clipped at container edge:

![before-tooltip](url)

**After** — tooltip repositions to stay visible:

![after-tooltip](url)

Image Sizing

- **Take screenshots at native 1x resolution** — don't resize with PIL (creates artifacts)

- **Control display size in HTML** when images are too large:

```html

<img src="url" width="600" alt="description">

```

- **Before/after pairs must use the same viewport width and crop** — otherwise the comparison is meaningless

Uploading Images

Azure DevOps

Upload images as PR attachments via the REST API:

$token = az account get-access-token `
    --resource "499b84ac-1321-427f-aa17-267ca6975798" `
    --query accessToken -o tsv

$base = "https://{org}.visualstudio.com/{projectId}/_apis/git/repositories/{repoId}"
$url = "$base/pullRequests/{prId}/attachments/screenshot.png?api-version=7.1-preview.1"

# Use HttpClient — Invoke-RestMethod can corrupt binary data
$client = New-Object System.Net.Http.HttpClient
$client.DefaultRequestHeaders.Authorization = `
    New-Object System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", $token)
$content = New-Object System.Net.Http.ByteArrayContent(
    , [System.IO.File]::ReadAllBytes("screenshot.png")
)
$content.Headers.ContentType = `
    [System.Net.Http.Headers.MediaTypeHeaderValue]::new("application/octet-stream")
$resp = $client.PostAsync($url, $content).Result

Reference in the PR description:

![description](https://{org}.visualstudio.com/{projectId}/_apis/git/repositories/{repoId}/pullRequests/{prId}/attachments/screenshot.png)

**Azure DevOps gotchas:**

- **Use `{org}.visualstudio.com` NOT `dev.azure.com/{org}`** — AzDO's markdown renderer uses `.visualstudio.com`. The `dev.azure.com` format loads noticeably slower

- Use `POST` not `PUT` (PUT returns 405)

- API version must be `7.1-preview.1`

- Can't re-upload with the same filename — use a new name (e.g. `screenshot-v2.png`)

- Use `HttpClient` not `Invoke-RestMethod` — IRM can corrupt binary data

- Repo-relative paths don't work in PR descriptions — must use full URLs

- Don't commit images to the branch just for PR screenshots

GitHub

> **⚠️ Work in progress.** GitHub's drag-and-drop image upload uses internal endpoints that require browser cookies. There's no clean public API for uploading images to PR descriptions yet.

**Current workaround:** Commit images to a `pr-assets` orphan branch and reference via blob URLs (`github.com/{owner}/{repo}/blob/pr-assets/{file}?raw=true`). It works but is clunky — contributions for a better approach are welcome.

Guidelines

1. **Capture before state BEFORE making changes** — it's easy to forget, and reconstructing the original state later is slow and error-prone

2. **Keep descriptions br