Status: Mandatory for major redesigns
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-073
1. Purpose#
Every major redesign must ship with a review package that makes the claimed UX improvements explicit and easy to verify.
This checklist exists to stop vague signoff language like "looks cleaner" or "feels better." A redesign is only review-ready when reviewers can see:
- what changed
- which user-facing claims are being made
- which desktop and mobile states prove those claims
- which key edge or alternate states were also reviewed
This is the human design-review gate. V1-UX-074 adds the companion
Playwright-backed visual QA gate.
Claim IDs created here should carry forward unchanged into
docs/releases/v1/specs/playwright-visual-qa-checklist.md.
2. When This Checklist Is Required#
Complete this checklist for any change that meaningfully alters user-facing UI, including:
- a redesign or restyle of a shell, domain home, major flow, or reusable surface
- a change to information hierarchy, action placement, disclosure, reading posture, or navigation posture
- a new shared component that changes how a major customer or admin surface is perceived or operated
- any PR or task that makes explicit UX claims such as calmer, simpler, faster to scan, more readable, or easier to complete
This checklist is usually not required for:
- copy-only edits with no layout or interaction change
- invisible refactors
- purely technical fixes with no meaningful UI change
If there is doubt, do the checklist.
3. Non-Negotiable Review Inputs#
Before asking for redesign signoff, the author must provide all of the following:
- Explicit UX claims Each claim must describe a user-visible improvement that can be reviewed.
- Desktop evidence At least one desktop capture from the real UI for each critical claim.
- Mobile evidence At least one narrow-mobile capture from the real UI for each critical claim.
- Key-state evidence Captures for the important states affected by the redesign, not just the happy path.
- Verification evidence The commands or automation used to validate the redesign.
4. Required Capture Inventory#
Minimum required viewports:
- Desktop: one wide desktop capture at roughly
1440-1600pxwidth - Mobile: one narrow-mobile capture at roughly
390-430pxwidth
Add more captures when the redesign meaningfully changes across breakpoints:
- tablet or laptop-specific layouts
- expanded vs collapsed disclosure states
- before/after comparison states inside the same flow
- success, empty, error, offline, degraded, or loading states touched by the redesign
Each capture must identify:
- route or surface
- state ID
- viewport
- why this state matters
- file/artifact location
5. Required Key States#
The review package must include every state the redesign materially changes. Use the smallest complete set that covers the real risk. Typical required states are:
- default entry state
- populated or happy-path state
- expanded, disclosed, or secondary-control state
- selection, hover, focus, or active state when interaction posture changed
- empty state if new hierarchy depends on absence of content
- loading, offline, degraded, or error state if touched
- completion, success, or confirmation state if touched
If a state changed in code, it should usually appear in the review package.
6. Claim Quality Standard#
Good UX claims are specific and observable.
Good:
- "Explore keeps secondary discovery lanes out of the first scan by hiding them behind one disclosure."
- "The assistant keeps the active guide visible while persona switching remains one tap away."
- "Veritas preserves verification-first tools on the first scan and moves secondary systems into a secondary lane."
Bad:
- "The page feels nicer."
- "This is cleaner."
- "The redesign is more modern."
Each claim must map to:
- one or more capture IDs
- the exact states where the claim can be judged
- reviewer verdict: pass, pass with follow-up, or fail
7. Mandatory Review Checklist#
- Scope is defined: the surface, routes, and changed states are named.
- Explicit UX claims are written in concrete, user-visible language.
- Each UX claim is mapped to capture IDs and exact routes/states.
- At least one desktop capture is attached for the redesigned flow.
- At least one mobile capture is attached for the redesigned flow.
- Any breakpoint-specific layout change includes its own capture.
- Any changed disclosure, overlay, or alternate state includes its own capture.
- Any changed empty, loading, error, offline, or degraded state includes evidence or is explicitly marked not applicable.
- Any changed success or completion state includes evidence or is explicitly marked not applicable.
- Review notes call out known gaps, tradeoffs, and follow-up work.
- Verification commands and automation are listed.
- Design signoff records whether each claim passed, failed, or needs follow-up.
Do not approve a major redesign without the completed checklist.
8. Review Record Template#
Copy this block into the PR description, task comment, or review doc for every major redesign:
## Design Review
- Surface / route:
- Owner:
- Linked task / PR:
- Review date:
### UX Claims
| Claim ID | UX claim | Capture IDs | Verdict |
| -------- | -------- | ----------- | ------- |
| UX-01 | | | |
| UX-02 | | | |
### Capture Inventory
| Capture ID | Route / state | Viewport | Why this state matters | Artifact |
| ---------- | ------------- | -------- | ---------------------- | -------- |
| CAP-01 | | desktop | | |
| CAP-02 | | mobile | | |
| CAP-03 | | | | |
### Key States Reviewed
- [ ] Default entry
- [ ] Populated / happy path
- [ ] Expanded / disclosure / overlay state
- [ ] Loading / empty / error / degraded states touched by the redesign
- [ ] Completion / success state touched by the redesign
### Verification
```bash
# list the commands actually run
```
### Review Notes
- Open issues:
- Follow-up tasks:
- Final signoff:
9. Operational Rule#
For major redesigns:
- the checklist must exist before asking for review
- missing desktop/mobile evidence blocks signoff
- missing claim-to-evidence mapping blocks signoff
- unresolved key-state gaps must be documented explicitly
If the redesign cannot be defended with explicit claims and evidence, it is not ready for signoff.