vercel-preview-qa

name	vercel-preview-qa
description	Use this whenever a PR has a Vercel preview URL and needs browser QA against acceptance criteria — happy path, errors, empty states, responsive behavior, a11y basics — even if the user just says "check the preview". Requires a preview URL. NOT for release/deploy-readiness checks (no preview needed there) — use deploy-ready.

vercel-preview-qa

QA a Vercel preview deployment against acceptance criteria before merge. The visual and functional check that catches what unit tests miss.

Purpose

Take a preview URL and acceptance criteria from a Linear issue, and verify that the implementation actually meets the criteria in a real browser environment.

Process

0. Read the UI rule reference first

Before UI work or review, read rules/ui.md and apply the project’s responsive, accessibility, component-state, and design-token expectations.

1. Get the acceptance criteria

Read from the Linear issue. If no criteria exist, stop — route to requirements-griller.

2. Test each criterion

For each acceptance criterion, test it on the preview:

• Does the happy path work?
• Does the error path work?
• Does the empty state work?

3. Responsive check

Test at three breakpoints:

• Mobile: 375px
• Tablet: 768px
• Desktop: 1280px

Check for: horizontal overflow, touch target sizing, layout breaks, text overflow.

4. Accessibility quick check

• Tab through the page — is focus order logical?
• Are focus indicators visible?
• Do buttons and links have accessible labels?
• Does the page work with prefers-reduced-motion: reduce?

5. Classify findings

• Blocker — prevents merge. Acceptance criterion not met, broken functionality, security issue.
• Issue — should fix before merge. Visual regression, missing state, accessibility gap.
• Polish — can fix in follow-up. Minor alignment, copy improvement, animation refinement.

Output format

# Preview QA — [PR #/feature]

Preview URL: [url]

## Acceptance criteria

- [x] [Criterion 1] — verified
- [ ] [Criterion 2] — BLOCKER: [what's wrong]
- [x] [Criterion 3] — verified

## Responsive

- Mobile (375): [pass/issues]
- Tablet (768): [pass/issues]
- Desktop (1280): [pass/issues]

## Accessibility

- Focus order: [pass/issues]
- Focus indicators: [pass/issues]
- Labels: [pass/issues]
- Reduced motion: [pass/issues]

## Findings

### Blockers

- [Finding]

### Issues

- [Finding]

### Polish

- [Finding]

## Verdict: [PASS / BLOCKED — N blockers]

Hard rules

• Never skip preview QA for user-facing changes
• Never mark "PASS" with unresolved blockers
• Never invent acceptance criteria — use the ones from Linear

Connects to

• issue-to-pr — invoked after push, before PR finalized
• ui-quality — for deeper responsive or a11y review if needed
• deploy-ready — complementary checklist

Common failure modes

Checking only desktop — Most users are on mobile. Always check 375px.

"Looks right to me" — Compare against acceptance criteria explicitly. Visual impression is not QA.

Skipping error states — Happy path looks great. Then a user with no data sees a blank page.