Status: Mandatory for major redesigns
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-074
1. Purpose#
Every claimed UX improvement in a major redesign must map to:
- a concrete Playwright spec
- a named Playwright test or scenario
- a tested UI state
- a captured UI artifact from that tested state
This checklist is the automation companion to
docs/releases/v1/specs/design-review-checklist.md.
The design-review checklist proves that the redesign claims are explicit and reviewable. This visual QA checklist proves that those same claims are backed by real Playwright coverage and a captured state artifact.
2. Required Inputs#
Before completing this checklist, the author must already have:
- claim IDs from the design-review checklist
- the Playwright spec path and test title that validate each claim
- a captured UI artifact for the tested state
- the command that ran the relevant Playwright coverage
Claim IDs must carry forward unchanged from the design-review checklist.
3. Acceptable Capture Artifacts#
The captured state for a claim must come from one of the following:
- a stable Playwright snapshot assertion such as
toHaveScreenshot(...) - a success-state screenshot captured explicitly during the Playwright run
- an attached Playwright artifact that clearly identifies the exact validated state
Failure-only screenshots, videos, or traces are useful for debugging, but they do not count as the primary captured artifact for a successful UX claim unless the state itself is still clearly and intentionally identified.
4. Required Claim Mapping#
For every UX claim in a major redesign:
- identify the exact Playwright spec file
- identify the exact test title or scenario
- identify the exact state ID being validated
- record the viewport used for the captured state
- record the capture artifact name or path
- record pass/fail status and any notes
No major redesign claim should remain unmapped.
5. Mandatory Checklist#
- Every redesign claim ID from the design-review checklist appears here.
- Every claim maps to at least one Playwright spec path.
- Every claim maps to an exact Playwright test title or scenario.
- Every claim maps to at least one named UI state ID.
- Every mapped state has a captured UI artifact.
- Desktop and mobile are both covered when the UX claim applies to both.
- Disclosure, overlay, empty, loading, error, degraded, and completion states are covered when the claim touches them.
- The artifact name or snapshot name is specific enough to find again.
- The Playwright command that produced the evidence is recorded.
- The final checklist records whether each claim passed, failed, or is blocked.
- Any non-automatable claim is explicitly marked blocked with rationale and a follow-up owner.
Do not sign off a major redesign until this checklist is complete.
6. Preferred Evidence Pattern#
Use this order of preference:
- Playwright
toHaveScreenshot(...)or equivalent stable visual assertion for the exact state - explicit success-state screenshot capture from the Playwright run
- additional trace/video/log artifacts as supporting evidence
The best visual QA package includes both:
- a functional assertion that proves the state is correct
- a visual artifact that lets reviewers inspect the state quickly
7. Visual QA Record Template#
Copy this block into the PR description, task comment, or review doc for every major redesign:
## Visual QA
- Linked design review:
- Owner:
- Run date:
- Verification command:
| Claim ID | UX claim | Playwright spec | Test title / scenario | State ID | Viewport | Capture artifact | Result | Notes |
| -------- | -------- | --------------- | --------------------- | -------- | -------- | ---------------- | ------ | ----- |
| UX-01 | | | | | desktop | | | |
| UX-01 | | | | | mobile | | | |
| UX-02 | | | | | | | | |
### Blockers / Non-Automatable Claims
- Claim ID:
- Why automation is blocked:
- Manual fallback evidence:
- Follow-up owner:
8. Operational Rule#
For major redesigns:
- a completed design-review checklist is required first
- the visual QA checklist must reuse the same claim IDs
- every claimed improvement must point to a passing Playwright test and a captured state artifact
- missing mapping, missing artifacts, or missing automation status blocks signoff
If a redesign claim cannot be traced from claim to Playwright spec to captured state, it is not ready for final approval.