Product

6 screens and overlays, 51 states, 4 flows. Frames show a real screenshot where one was captured and a wireframe card where the state needs data or conditions a device run cannot produce.

Flows

Add to bag

Product detail (iOS) — Product page with variant and quantity controls

Product detail (Android) — Product page with variant and quantity controls

Tap the options row

Variant picker, Selected tile (iOS) — Variant sheet with one tile selected

Variant picker, Selected tile (Android) — Variant sheet with one tile selected

Add to bag

Product detail, Added to bag bar (iOS) — Bar confirms the add and offers View Bag

Product detail, Added to bag bar (Android) — Bar confirms the add and offers View Bag

View Bag

My Bag (iOS) — My Bag lists the new line

My Bag (Android) — My Bag lists the new line

Branches and edge cases

Product detail, Out of stock variant (iOS) — Selected variant out of stock

Product detail, Out of stock variant (Android) — Selected variant out of stock

Product detail, Single variant product (iOS) — Single variant skips the sheet

Product detail, Single variant product (Android) — Single variant skips the sheet

Product detail, Signed out on PDP (iOS) — Guest adds to local bag

Product detail, Signed out on PDP (Android) — Guest adds to local bag

Variant picker, Unavailable variant tile (iOS) — Variant tile unavailable

Variant picker, Unavailable variant tile (Android) — Variant tile unavailable

Errorfrom step 2

Wireframe

Variant picker

Error

Add failure toast

Same toast as PDP; stepper has no per-variant stock cap

Not reachable on a device: Needs a network fault, crash, race or code change to show

Add fails in the sheet

Errorfrom step 2

Wireframe

Product detail

Error

Failed to add to bag

Add fails or server rate limits; toast with message or Please try again

Not reachable on a device: Needs a network fault, crash, race or code change to show

Add fails on the page

Errorfrom step 4

Wireframe

My Bag

Error

Guest merge failed 3 times

Toast N cart items couldn't sync; Reopen your cart to retry

Not reachable on a device: Needs a network fault, crash, race or code change to show

Guest signs in, merge fails

Edgefrom step 4

Wireframe

My Bag

Edge

Guest merge dropped lines

Lines without product id dropped; toast N bag items couldn't sync

Needs data: Capture audit 2026-10-30. ios: Requires deliberately malformed guest cart cache with a missing product id; ordinary UI cannot create that line. android: Requires deliberately malformed guest cart cache with a missing product id; ordinary UI cannot create that line.

Guest merge drops lines

Flow diagram

Reviews

Open reviews

Ratings & Reviews, Review list (iOS) — Ratings and Reviews list with footer action

Ratings & Reviews, Review list (Android) — Ratings and Reviews list with footer action

Write a review

Ratings & Reviews, Review form (iOS) — Review form with star rating and text

Ratings & Reviews, Review form (Android) — Review form with star rating and text

Submit

Branches and edge cases

Ratings & Reviews, Guest cannot open form (iOS) — Guest footer

Ratings & Reviews, Guest cannot open form (Android) — Guest footer

Ratings & Reviews, No reviews yet (iOS) — No reviews yet

Ratings & Reviews, No reviews yet (Android) — No reviews yet

Ratings & Reviews, Awaiting moderation banner (iOS) — Own review awaiting moderation

Ratings & Reviews, Awaiting moderation banner (Android) — Own review awaiting moderation

Report Review (iOS) — Flag icon on another review

Report Review (Android) — Flag icon on another review

Report Review, Submitted or already reported (iOS) — Report submitted

Report Review, Submitted or already reported (Android) — Report submitted

Block User, User Blocked toast (iOS) — Block confirmed

Block User, User Blocked toast (Android) — Block confirmed

Ratings & Reviews, Submit disabled until rated (iOS) — Submit before rating

Ratings & Reviews, Submit disabled until rated (Android) — Submit before rating

Errorfrom step 3

Wireframe

Ratings & Reviews

Error

Submit failed

Toast: Failed to submit review. Please try again.

Not reachable on a device: Needs a network fault, crash, race or code change to show

Submit fails

Flow diagram

Buy now from product

Tap Buy now

Confirm

Step 3

Wireframe

Shopify checkout

Success

Completed with order id

De-duplicated, session client_completed, bag replaces to confirmation

Needs data: Capture audit 2026-10-30. ios: Real checkout/payment required; do not bypass route allowlist. android: Real checkout/payment required; do not bypass route allowlist.

Shopify checkout sheet opens over the page

Branches and edge cases

Errorfrom step 1

Wireframe

Product detail

Error

Buy now failure

Toast Checkout failed with message; guest sees Authentication required, no sign-in sheet

Not reachable on a device: Needs a network fault, crash, race or code change to show

Guest or stock failure

Edgefrom step 1

Wireframe

Product detail

Add or buy spinner

Spinner replaces button face and both buttons disable

Not reachable on a device: Needs a network fault, crash, race or code change to show

Spinner while preparing

Shopify checkout, Closed without completing (iOS) — Sheet closed

Shopify checkout, Closed without completing (Android) — Sheet closed

Flow diagram

Writing a review

Order Details, Review prompt (iOS) — Delivered order prompts Rate and Review

Order Details, Review prompt (Android) — Delivered order prompts Rate and Review

Tap Rate and Review

Open reviews

Submit Review

Ratings & Reviews, Review Submitted or Updated (iOS) — Review Submitted confirmation

Ratings & Reviews, Review Submitted or Updated (Android) — Review Submitted confirmation

Branches and edge cases

Ratings & Reviews, Sign in to write a review (iOS) — Guest opens the form

Ratings & Reviews, Sign in to write a review (Android) — Guest opens the form

Errorfrom step 3

Wireframe

Ratings & Reviews

Edge

Missing product id

Renders nothing

Not reachable on a device: Route cannot be opened without an id

Missing product id

Flow diagram

Screens and states

Product detail

Screen(app)/product/[id]

Product detail

Product page with gallery, variants, reviews, description, recommendations and buy bar

src/app/(app)/product/[id].tsx

Entry

Any product card or list
Bag item image or row
Wishlist zoom link
Deep link with several id shapes

Exits

Back → previous screen
Bag icon or View Bag → My Bag
Share → native share sheet
Heart → wishlist toggle or sign-in
Image tap → fullscreen viewer
Options row or buttons → variant sheet

States · 20

Detail skeleton · Detail query undefined; preview image, title and price if stashedsrc/features/product/components/detail/states/product-detail-skeleton.tsx:26

Disabled bottom bar on preview · Bar shown at preview price only when a preview exists; cold deep link has nonesrc/features/product/components/detail/product-detail-page.tsx:318

Empty

Product not found · Loaded but null; Close button goes back, header icons no-opsrc/features/product/components/detail/states/product-detail-states.tsx:44

Error

Failed to load product unreachable · Error branch never reached; page always passes error nullsrc/features/product/components/detail/product-detail-page.tsx:340

Edge

Below the fold deferred · Reviews, description and recommendations mount two frames after first paintsrc/features/product/components/detail/product-detail-page.tsx:123

Edge

Default variant · First available variant, else first; not reset by reactive updatessrc/features/product/hooks/use-product-detail.ts:135

Edge

Out of stock variant · Buttons greyed, no Sold out label or Notify me; text only in variant sheetsrc/features/product/components/detail/static-bottom-bar.tsx:94

Edge

Low stock note · Only N left in stock when quantity is 1 to 5; untracked never countssrc/features/product/components/detail/info/low-stock-note.tsx:18

Edge

Single variant product · Options row hidden and add or buy acts directly; Default Title filteredsrc/features/product/components/detail/info/variant-summary-row.tsx:26

Success

Added to bag bar · Bar shows Added to bag with Continue and View Bag until one is tappedsrc/features/product/components/detail/static-bottom-bar.tsx:58

Error

Failed to add to bag · Add fails or server rate limits; toast with message or Please try againsrc/features/product/components/detail/product-detail-page.tsx:213

Edge

Quantity silently clamped to 10 · Stepper allows 99 but each add clamps to 10; no stock check on addsrc/features/cart/hooks/use-server-cart.ts:506

Add or buy spinner · Spinner replaces button face and both buttons disablesrc/features/product/components/detail/static-bottom-bar.tsx:116

Gate

Signed out on PDP · Add goes to local bag, heart asks sign-in, view tracking offsrc/features/product/components/detail/product-detail-page.tsx:140

Error

Buy now failure · Toast Checkout failed with message; guest sees Authentication required, no sign-in sheetsrc/features/product/components/detail/product-detail-page.tsx:252

Edge

Reviews summary · Rating bars only with ratings; zero shows 0.0 (0 ratings); quote cut at 80 charssrc/features/product/components/detail/reviews/ratings-reviews-section.tsx:89

Edge

Description pane · Description only if present; Product Details rows show Brand, Type, SKU, Tags when setsrc/features/product/components/detail/panes/description-pane.tsx:31

Empty

No recommendations yet · Falls back to 6 featured products; shows text if nonesrc/features/product/components/detail/panes/recommendations-pane.tsx:56

Empty

No image available · Product has no imagessrc/features/product/components/detail/images/image-carousel.tsx:78

Offline

Offline cached or stuck · Cached product reopens instantly; uncached stays on skeletonsrc/features/product/hooks/use-product-detail.ts:4

Captured states

Variant picker

SheetVariantSelectionSheet

Variant picker

Pick variant and quantity, then add to bag or buy now

src/features/product/components/detail/variants/variant-selection-sheet.tsx

Entry

N options available row
Add or buy on multi variant product

Exits

Add icon → adds and closes
Buy now → closes, opens Shopify checkout
Swipe → close

States · 4

Edge

Unavailable variant tile · Dashed, 50% opacity, not tappable, labelled Out of stocksrc/features/product/components/detail/variants/variant-card.tsx:31

Edge

Selected tile · Accent border with check badgesrc/features/product/components/detail/variants/variant-card.tsx:31

Edge

Footer disabled · Selected variant unavailable or an action is busysrc/features/product/components/detail/variants/variant-selection-sheet.tsx:73

Error

Add failure toast · Same toast as PDP; stepper has no per-variant stock capsrc/features/product/components/detail/variants/variant-selection-sheet.tsx:87

Captured states

Image viewer

ModalProductImageViewer

Image viewer

Fullscreen image viewer with swipe, pinch and double tap zoom

src/shared/components/ui/media/product-image-viewer.tsx

Entry

Tap hero image

Exits

Close button → PDP
Single tap → PDP
Android back → PDP

States · 1

Edge

No load or error state · Only the underlying Image; iOS hides the status bar while opensrc/shared/components/ui/media/product-image-viewer.tsx:27

Ratings & Reviews

Screen(app)/product-reviews/[id]

Ratings & Reviews

Ratings list, review form and success view in one route

src/app/(app)/product-reviews/[id].tsx

Entry

PDP reviews button
Deep link with Convex product id

Exits

Back → PDP, or list view from form
Done → PDP
Guest footer → sign-in sheet
Flag icon → report sheet

States · 19

Gate

Guest cannot open form · Form intent from a guest is downgraded to listsrc/app/(app)/product-reviews/[id].tsx:90

Reviews spinner · Large spinner while comments loadsrc/features/product/components/detail/reviews/reviews-list-view.tsx:150

Empty

No reviews yet · Be the first to share; header shows empty stars and No ratings yetsrc/features/product/components/detail/reviews/reviews-list-view.tsx:160

Edge

Capped at 100 reviews · Only newest 100 approved reviews load; filter counts cap theresrc/app/(app)/product-reviews/[id].tsx:61

Edge

Pending moderation banner · Own review status is pending: awaiting moderationsrc/app/(app)/product-reviews/[id].tsx:250

Edge

Submit disabled until rated · Needs rating 1 to 5; title max 60, content max 500src/features/product/components/detail/reviews/review-form-view.tsx:142

Error

Rating Required toast · Submit without a rating; warning toastsrc/app/(app)/product-reviews/[id].tsx:66

Error

Review Exists toast · User already has a review; warning toastsrc/app/(app)/product-reviews/[id].tsx:98

Error

Submit failed · Toast: Failed to submit review. Please try again.src/app/(app)/product-reviews/[id].tsx:109

Success

Review Submitted · Check icon; Review Submitted or Review Updated with thank-you textsrc/app/(app)/product-reviews/[id].tsx:196

Edge

Form back keeps input · Swipe back off and Android back intercepted in form viewsrc/app/(app)/product-reviews/[id].tsx:128

Edge

Verified tag · Verified buyers show a Verified tag on review cardssrc/features/product/components/detail/reviews/review-card.tsx:90

Success

Review list · Approved reviews, most recent firstsrc/app/(app)/product-reviews/[id].tsx:250

Edge

Awaiting moderation banner · Own review status is PENDINGsrc/app/(app)/product-reviews/[id].tsx:250

Edge

Review form · Write or edit; button enabled when validsrc/app/(app)/product-reviews/[id].tsx:237

Success

Review Submitted or Updated · Thank-you screen with Donesrc/app/(app)/product-reviews/[id].tsx:196

Gate

Edge

Missing product id · Renders nothingsrc/app/(app)/product-reviews/[id].tsx:146

Edge

No purchase check · Any signed-in user can write a reviewsrc/app/(app)/product-reviews/[id].tsx:271

Captured states

Report Review

SheetReportReviewSheet

Report Review

Report a review by reason with optional details, or block its author

src/features/product/components/reviews/report-review-sheet.tsx

Entry

Flag icon on another user's review

Exits

Submit Report → auto closes after 2 s
Block → native confirm alert

States · 5

Edge

Submit disabled until reason · Reasons: spam, inappropriate, harassment, othersrc/features/product/components/reviews/report-review-sheet.tsx:153

Success

Submitted or already reported · Confirmation state, sheet dismisses after 2 ssrc/features/product/components/reviews/report-review-sheet.tsx:87

Error

Cannot Report toast · Server rejects the report; shows server messagesrc/features/product/components/reviews/report-review-sheet.tsx:76

Error

Report error toast · Something went wrong. Please try again.src/features/product/components/reviews/report-review-sheet.tsx:96

Gate

No sign-in gate on card · Flag is not gated; backend decidessrc/features/product/components/detail/reviews/review-card.tsx:99

Captured states

Block User

DialogBlockUserAlert

Block User

Confirm blocking a review author so their reviews are hidden

src/features/product/components/reviews/report-review-sheet.tsx

Entry

Block in report sheet

Exits

Block → dismisses report sheet
Cancel → stay on sheet

States · 2

Success

User Blocked toast · Block succeeded; report sheet dismissessrc/features/product/components/reviews/report-review-sheet.tsx:108

Error

Failed to block toast · Failed to block user. Please try again.src/features/product/components/reviews/report-review-sheet.tsx:108

Captured states

Product

FlowsCopy Anchor Link

Add to bagCopy Anchor Link

ReviewsCopy Anchor Link

Buy now from productCopy Anchor Link

Writing a reviewCopy Anchor Link

Screens and statesCopy Anchor Link

Product detailCopy Anchor Link

Product detail

Variant pickerCopy Anchor Link

Variant picker

Image viewerCopy Anchor Link

Image viewer

Ratings & ReviewsCopy Anchor Link

Ratings & Reviews

Report ReviewCopy Anchor Link

Report Review

Block UserCopy Anchor Link

Block User

On this page

Flows

Add to bag

Reviews

Buy now from product

Writing a review

Screens and states

Product detail

Variant picker

Image viewer

Ratings & Reviews

Report Review

Block User