PR Screenshot Documentation

Guidance for capturing and documenting UI changes with before/after screenshots when creating pull requests.

When to Use This Skill

• Creating PRs with frontend/UI modifications

• Documenting visual changes for code review

• Building a visual record of design evolution

• Enabling async design review without running the app

Screenshot Workflow

1. Before Making Changes

Capture the current state before implementing UI modifications:

1. browser_resize(width: 320, height: 568) # Mobile-first
2. browser_navigate to the target page
3. browser_snapshot to identify elements
4. browser_take_screenshot(element: "Target component", ref: "E123")

Save or note the screenshot for later comparison.

2. After Implementing Changes

Capture the same view after your modifications:

1. Refresh or navigate to the updated page

2. browser_snapshot to get updated refs

3. browser_take_screenshot(element: "Target component", ref: "E123")

4. Upload Screenshots (Optional)

For persistent URLs in PR descriptions, upload to an image hosting service:

Using curl with 0x0.st (ephemeral hosting)

curl -F 'file=@screenshot.png' https://0x0.st

Or use project-specific image storage

Note: 0x0.st URLs expire. For permanent records, use GitHub's drag-and-drop image upload in PR descriptions or project documentation storage.

PR Description Template

Include a visual comparison section in your PR description:

Visual Changes

Before	After

What Changed

• [Specific visual change 1]
• [Specific visual change 2]

Viewport Recommendations

Choose viewport size based on what you're documenting:

Target Width Height Use Case

Mobile 320 568 Mobile-first responsive

Tablet 768 1024 Tablet layouts

Desktop 1280 800 Standard desktop

Wide 1440 900 Wide desktop layouts

Default to mobile (320px) for documentation - if it looks good on mobile, it usually scales up well.

Best Practices

Capture Strategy

• Focus on the changed component - don't capture full pages unless layout changed

• Use consistent viewports - same size for before and after

• Capture interactive states - hover, focus, active when relevant

• Include error states - if you changed error handling UI

Documentation Quality

• Describe what changed - don't make reviewers guess

• Explain why - connect visual changes to user benefit

• Note accessibility - mention contrast, focus indicators if relevant

When NOT to Capture

• Pure backend changes with no UI impact

• Code refactoring without visual changes

• Test-only changes

• Configuration updates

Integration with PR Workflow

This skill complements the /majestic-engineer:git:create-pr command. Before creating a PR with UI changes:

• Take before screenshots (if you didn't already)

• Implement your changes

• Take after screenshots

• Include comparison in PR description

• Run the create-pr command

Example PR Section

Visual Changes

Before	After

Changes Made

• Increased button padding from 8px to 12px for better touch targets
• Added subtle shadow for depth
• Improved contrast ratio from 3.5:1 to 4.8:1 (now WCAG AA compliant)

Tested Viewports

• Mobile (320px)
• Tablet (768px)
• Desktop (1280px)

Related Tools

• visual-validator agent - For rigorous visual QA after changes

• ui-ux-designer agent - For iterative design refinement