Feature Development

Catch Visual Regressions Before Every PR

A repo skill that makes Opulent screenshot every affected page and flag layout breakage before opening a PR.

Skills

AuthorOpulent

CategoryFeature Development

FeaturesSkills

start it with one message

Create a repository skill that tells Opulent to start our Next.js app, read the current git diff, navigate every page touched by the diff, screenshot at desktop and mobile widths, and flag any layout issues before opening a PR.

Run this in OpulentCopy it, swap the names for your own, and send it.

connected systems

GitHubManage repositories, track code changes, and collaborate on team projects

PlaywrightAutomate browsers for testing, scraping, and more with Playwright

VercelManage Vercel projects, deployments, and domains

step 1

Create the visual-regression skill

Connect GitHub and Playwright. Create a skill file in the repo at .agents/skills/visual-regression/SKILL.md that encodes the team's manual QA checklist as steps Opulent can follow before any PR.

The skill is a playbook, a reusable, named set of steps that defines how to boot the app, identify affected pages, screenshot them, and flag issues.

# Visual Regression Check

## Description
Before opening any PR, start the app locally and screenshot every
page affected by the current diff at desktop and mobile widths.
Flag any layout issues found.

## Prerequisites
- Port 3000 available.

## Setup
1. Install dependencies: npm install.
2. Start the dev server: npm run dev.
3. Wait for "Ready on http://localhost:3000".

## Visual Checks
1. Read the git diff to identify affected pages.
2. For each affected page:
   a. Open http://localhost:3000/{route}.
   b. Screenshot at 1280px width (desktop).
   c. Resize to 375px width (mobile).
   d. Screenshot at mobile width.
   e. Check for: overlapping text, hidden elements, horizontal
      scroll, unreachable buttons, missing images, console errors.
3. If any issue is found, list page, viewport, and description.

## Before opening the PR
- Run npm run lint and npm test.
- Include all screenshots in the PR description.
- If issues found, list them at the top of the PR body.

Tip

Keep the skill file in the repo so it travels with the code. When the app setup changes, the skill is updated in the same PR as the code change.

step 2

Make checks specific to your routes

Generic instructions like 'check the page looks right' produce vague results. Add route-specific sections that define what correct looks like for each area of the app.

Opulent reads the diff, identifies which routes were touched, and follows the matching section, so checks are focused rather than generic.

## Route-Specific Checks

### Dashboard (/dashboard)
- Metric cards display in a 3-column grid on desktop.
- Cards stack to a single column on mobile.
- Chart is fully visible without horizontal scroll.

### Checkout (/checkout)
- "Place Order" button is visible without scrolling on both
  desktop and mobile.
- Order summary sidebar collapses into an accordion on mobile.
- Price breakdown shows subtotal, tax, and total on separate lines.

### Settings (/settings)
- Form labels are left-aligned with their inputs.
- "Save" button is reachable at the bottom of the form.
- Tab navigation updates the URL hash.

step 3

Watch it catch a real regression

A developer changes the dashboard grid from repeat(3, 1fr) to repeat(auto-fit, minmax(200px, 1fr)). Tests pass, but on mobile the cards overflow. Opulent follows the skill, takes the screenshots, and flags the issue before the PR is opened.

The run does not block the PR by itself, but it surfaces the visual problem with evidence so the reviewer can request a fix before merging.

Diff: dashboard/page.tsx

Visual regression run:
- Affected routes: /dashboard
- Desktop screenshot: 3-column grid, OK.
- Mobile screenshot: cards overflow viewport, horizontal scroll.
- Flag: metric cards overflow at 375px.
- Action: fix grid before opening PR.

Screenshots attached to PR.

step 4

Integrate into the PR workflow

Make the skill run automatically when a PR touches UI files. Opulent reads the diff, runs the checks, and adds the screenshots to the PR description. If it finds issues, it adds them at the top of the PR body.

The skill becomes a gate that catches layout issues before code review, without replacing human judgment.

step 5

Sharpen the visual regression loop

When a new route is added, add its route-specific checks to the skill. When a false positive appears, tighten the rule or add an allowed variation.

Add evals for the most critical pages: the dashboard, checkout, and any page that directly drives revenue. These runs fail the build if a layout regression is detected.

The natural chain: when a visual bug needs a deeper look, use Click-Test Real Product Flows with Computer Use; when the same issue should be tested in CI, use Run Nightly E2E Tests on Staging.