Eve library

OSHUN V1 Design Review Checklist

Spec

Revision 1

On this page

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.