# OSHUN V1 Design Review Checklist

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:

1. **Explicit UX claims** Each claim must describe a user-visible improvement
   that can be reviewed.
2. **Desktop evidence** At least one desktop capture from the real UI for each
   critical claim.
3. **Mobile evidence** At least one narrow-mobile capture from the real UI for
   each critical claim.
4. **Key-state evidence** Captures for the important states affected by the
   redesign, not just the happy path.
5. **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-1600px` width
- Mobile: one narrow-mobile capture at roughly `390-430px` width

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:

````md
## 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.
