SlabUploader/docs/UX-DESIGN.md

# UX Design — wireframes (non-normative)

Status: DESIGN · non-normative · 2026-09-03 · SlabUploader

**Not normative.** Signed presentation SoT is `docs/UX.md` (phone and PC browsers). If a wireframe here disagrees with `docs/UX.md`, AGENTS, or TECH-SPEC, follow those and ignore the wireframe. These ASCII screens are layout sketches for discussion, drawn at a 375px phone width; they do not lock mobile-only or override the phone+PC matrix.

Functional rules live in `docs/UX.md`. Confidence gating: `AGENTS.md` §6.
Data model and status machine: `docs/DATA-MODEL.md`.

---

## Screen inventory

1. Settings (once)
2. First-run guidance (once per device)
3. Capture
4. Length axis
5. Type values
6. Review
7. Title / Description
8. Publish
9. Error states

---

## 1. Settings

One-time setup. All screen. Back to home after save.

```
┌─────────────────────────────────────┐
│ Settings                           │
├─────────────────────────────────────┤
│ Store URL                          │
│ https://www.whidbeywoodstore.com   │
│                                    │
│ WP Username                        │
│ [ slab-uploader          ]         │
│ Application Password               │
│ [ ••••••••••••••••••••  ]           │
│ [ Test Connection ]                │
│                                    │
│ Inference                          │
│ Endpoint: [ http://192.168.x.x:v1 ]│
│ API Key:  [ ••••••••••••••••••••  ]│
│ [ Test Connection ]                │
│ [ Enable Vision  ]                 │
│ [ Enable Content ]                │
│                                    │
│ Pricing Rules                      │
│ [+ Add Rule] [Edit]               │
│                                    │
│ Publish Status: [ Draft ▼ ]        │
│ Brand Voice: [ Premium lumber... ]│
│ GEO Context: [ Locally milled... ]│
│                                    │
│ [ Reset Capture Knobs ]           │
│ [ Refresh Store Lists ]          │
└─────────────────────────────────────┘
```

Interaction:
- Test Connection (WP): attempts REST v3 auth, shows green check or red error. Always pulls fresh taxonomy on success.
- Test Connection (Inference): two-turn probe. Shows stateful/stateless/fail.
- Enable Vision: feature flag for Call 1. Defaults off.
- Enable Content: feature flag for Call 2. Defaults off.
- Publish Status: dropdown, default Draft.

---

## 2. First-run guidance

One short card shown on first launch. Dismissed via swipe or tap.

```
┌─────────────────────────────────────┐
│                                    │
│  First run on the floor             │
│                                    │
│  Lay a green or black sheet         │
│  under the slab.                    │
│                                    │
│  Shoot from above with the lens     │
│  parallel to the face.              │
│                                    │
│  Put a tape measure in the shot     │
│  so you can type the length later.  │
│                                    │
│  ──────────────────────────────────  │
│  [ Got it ]                        │
│                                    │
└─────────────────────────────────────┘
```

---

## 3. Capture

Camera view. Source photo on screen. Mask overlay draws on the source.
Four knobs sit next to the overlay.

```
┌─────────────────────────────────────┐
│ Capture                        [R]  │
│ ┌─────────────────────────────────┐ │
│ │                                │ │
│ │        [ SOURCE PHOTO ]        │ │
│ │                                │ │
│ │       ~ mask overlay ~         │ │
│ │                                │ │
│ └─────────────────────────────────┘ │
│                                    │
│ Sheet: [ Auto ▼ ]                 │
│ Sensitivity: [◄─────●───►]        │
│ Edge Offset: [◄───●───►]          │
│ Feather:     [◄─────●───►]        │
│                                    │
│ [ Retake ]              [ Confirm ] │
└─────────────────────────────────────┘

R = retake current photo (new shot, same knobs)
```

Interaction:
- Moving any knob immediately re-runs background removal on the current photo.
- The overlay refreshes on the source image. No apply/save step. No server round-trip.
- Confirm moves to length axis. Retake takes a new photo.
- Knobs persist in localStorage until reset-to-default in Settings.

---

## 4. Length axis

Bounding rectangle and length axis drawn over the confirmed mask.
Width sample lines every 6 inches.

```
┌─────────────────────────────────────┐
│ Length Axis                        │
│ ┌─────────────────────────────────┐ │
│ │                                │ │
│ │       ┌───────────────┐       │ │
│ │       │   SLAB MASK   │       │ │
│ │       │  ──── AXIS ── │       │ │
│ │       │  ┌──┐ ┌──┐ ┌──┐       │ │
│ │       │  │ 6"│ │6"│ │6"│       │ │
│ │       └───────────────┘       │ │
│ │                                │ │
│ └─────────────────────────────────┘ │
│                                    │
│ [ Rotate ↻ ]        [ Confirm ]    │
└─────────────────────────────────────┘
```

Interaction:
- Rotate adjusts the axis. Width samples and sqft update live.
- On nearly square slabs, user picks which side is length.
- Confirm moves to type values.

---

## 5. Type values

Manual values win. Phone computes sqft, bdft, widths.

```
┌─────────────────────────────────────┐
│ Type Values                        │
│                                    │
│ SKU                                │
│ [ BW-0042            ]             │
│                                    │
│ Length (inches)                    │
│ [ 96.0             ]             │
│                                    │
│ Thickness (inches)                 │
│ [ 1.5              ]             │
│                                    │
│ Computed (read-only)               │
│ sqft: 0.64   bdft: 0.96           │
│ widths: 14.0 — 22.0 (avg 18.2)    │
│                                    │
│ [ Done ]                          │
└─────────────────────────────────────┘
```

Interaction:
- SKU: `[A-Z0-9-]{3,24}`. Field-exit check against validation rules.
- Length: 1/8" step. Typing recalculates widths/sqft/bdft live.
- Thickness: 1/8" step pick.
- Done moves to review screen. Draft uploads, status → calibrated.

---

## 6. Review

All store fields. Per-field nudges for missing mandatory fields.
Vision pre-populates when confidence ≥ 0.7. Empty when below.

```
┌─────────────────────────────────────┐
│ Review                           [X]│
│ ──────────────────────────────────  │
│ Photos                             │
│ [ ▢ ] [ ▢ ] [ ▢ ] [ ▢ ] [ ▢ ]     │
│ (processed PNG thumbnails)          │
│ ──────────────────────────────────  │
│ SKU: BW-0042                       │
│ Length: 96.0"  Thickness: 1.5"     │
│ sqft: 0.64   bdft: 0.96            │
│ Widths: 14.0 — 22.0 (avg 18.2)     │
│ ──────────────────────────────────  │
│ Species  [ Black Walnut ▼ ]        │
│ Wood Cat [ Live edge ▼ ]          │
│ Edge Type [ Live Edge ▼ ]         │
│ Figure   [ Cathedral ▼ ]          │
│ Grade    [ Premium ▼ ]           │
│ Fig Tags [ Cathedral ▼ ]          │
│ Feat Tags [ None ▼ ]             │
│ ──────────────────────────────────  │
│ Thickness Band: [ 1"–1 1/2" ▼ ]    │
│ Moisture:     [ Kiln-dried ▼ ]     │
│ ──────────────────────────────────  │
│ Price: [ $12.00 ] (rec $12.00)    │
│ ──────────────────────────────────  │
│ [ Review Title / Desc ]  [ Publish ]│
└─────────────────────────────────────┘

X = exit review, returns to calibrated draft
```

Per-field gating:
- Each missing mandatory field shows an inline empty state as the user works.
- Below-threshold Call 1 leaves taxonomy fields empty. The user sees the empty
  field with a nudge: "Select species" or "Select a figure type".
- Below-threshold leaves taxonomy fields empty. The user must manually fill species, wood
  category, edge type, figure, grade, fig-* tags, and grade to reach ready.
- Submit-time validation only fires after all fields are filled.

Pre-populated field appearance:
- Filled by Call 1: field shows the value with a small "AI" badge. User can
  tap to change. Badge disappears on edit.
- User-filled: no badge.

Gating details:
- Mandatory: exactly one species, ≥1 wood category, 1 edge type, ≥1 figure,
  ≥1 fig-* tag, ≥1 grade, thickness band, moisture, price, SKU, length,
  thickness, sqft/bdft/widths, ≥1 inventory PNG.
- Optional: feat-* tags (zero is fine).
- Publish button is disabled until all mandatory fields are filled.

---

## 7. Title / Description

Type or generate. Generate text is user-initiated.

```
┌─────────────────────────────────────┐
│ Title & Description                │
│ ──────────────────────────────────  │
│ Title                              │
│ [ Black Walnut 8ft × 18.2in Slab... │
│ ──────────────────────────────────  │
│ Short Title                        │
│ [ Black Walnut Slab — Cathedral ]  │
│ ──────────────────────────────────  │
│ Description                        │
│ [ A one-of-a-one cathedral black... │
│ ──────────────────────────────────  │
│ [ Generate Text ]  [ Done ]        │
└─────────────────────────────────────┘
```

Interaction:
- Generate Text: triggers Call 2. Button disabled if content LLM is off or
  inference endpoint unreachable. LLM writes prose only. Templates inject
  deterministic numbers. User can always edit the result.
- Done: returns to review. Title/description stored on the slab.

---

## 8. Publish

Status polling. Result shown inline.

```
┌─────────────────────────────────────┐
│ Publishing...                      │
│                                    │
│  ──────── ● ────────               │
│                                    │
│  Creating store listing...         │
│  Please wait.                      │
│                                    │
└─────────────────────────────────────┘
```

Success:
```
┌─────────────────────────────────────┐
│ Published!                         │
│                                    │
│  Listing created as draft.         │
│  SKU: BW-0042                      │
│  Store product ID: 1042            │
│                                    │
│  [ Open in Store ]  [ Done ]       │
└─────────────────────────────────────┘
```

Failed:
```
┌─────────────────────────────────────┐
│ Publish Failed                     │
│                                    │
│  The store rejected the listing.   │
│  Error shown inline on the field.   │
│                                    │
│  [ Retry ]  [ Back to Review ]      │
└─────────────────────────────────────┘
```

---

## 9. Error and empty states

### 9.1 Mask failure
```
┌─────────────────────────────────────┐
│ Mask Quality                        │
│ ──────────────────────────────────  │
│ Cannot isolate the slab edge.       │
│ Adjust the knobs or retake.         │
│ ──────────────────────────────────  │
│ [ Retake ]                        │
└─────────────────────────────────────┘
```

### 9.2 Axis misalignment
```
┌─────────────────────────────────────┐
│ Axis Check                          │
│ ──────────────────────────────────  │
│ Rotate the axis to match the        │
│ prevailing length of the slab.      │
│ ──────────────────────────────────  │
│ [ Rotate ↻ ]                      │
└─────────────────────────────────────┘
```

### 9.3 Source too small after crop
```
┌─────────────────────────────────────┐
│ Photo Quality                       │
│ ──────────────────────────────────  │
│ Photo will be too small after       │
│ cropping. Please retake with a      │
│ closer shot.                        │
│ ──────────────────────────────────  │
│ [ Retake ]                        │
└─────────────────────────────────────┘
```

### 9.4 SKU duplicate
```
┌─────────────────────────────────────┐
│ SKU Check                           │
│ ──────────────────────────────────  │
│ This SKU already exists in the      │
│ store (any status).                 │
│ ──────────────────────────────────  │
│ [ Edit SKU ]  [ Open Existing ]     │
└─────────────────────────────────────┘
```

### 9.5 Stale taxonomy value
```
┌─────────────────────────────────────┐
│ Field Check                         │
│ ──────────────────────────────────  │
│ This value is no longer valid.      │
│ Pick from the current list.         │
│ ──────────────────────────────────  │
│ [ Refresh Store Lists ]           │
└─────────────────────────────────────┘
```

### 9.6 Store unreachable
```
┌─────────────────────────────────────┐
│ Connection                          │
│ ──────────────────────────────────  │
│ Cannot reach the store. Check your  │
│ connection and settings.            │
│ ──────────────────────────────────  │
│ [ Retry ]  [ Open Settings ]       │
└─────────────────────────────────────┘
```

### 9.7 Vision off or below threshold
```
┌─────────────────────────────────────┐
│ Review (vision off)                │
│ ──────────────────────────────────  │
│ Species  [ Select ▼ ]  ◉ Select species
│ Wood Cat [ Select ▼ ]  ◉ Select category
│ Edge Type [ Select ▼ ]  ◉ Select edge
│ Figure   [ Select ▼ ]  ◉ Select figure
│ ──────────────────────────────────  │
└─────────────────────────────────────┘

◉ = inline nudge (per-field)
```

---

## Interaction patterns

### Per-field gating (review screen)
- Each mandatory field that is empty shows an inline nudge as the user works.
- The nudge is a small text hint to the right of the field.
- Below-threshold Call 1 leaves fields empty with nudges visible.
- Fill the field to dismiss the nudge.
- Publish button stays disabled until all mandatory fields are filled.

### Pre-populated field state
- Fields filled by Call 1 show the value with an "AI" badge.
- User can tap the field to change it. The badge disappears on edit.
- User-filled fields have no badge.

### Knob interaction (capture screen)
- All four knobs are on the capture screen next to the overlay.
- Moving a knob immediately re-runs background removal.
- No apply/save step. No server round-trip for mask tuning.

### Axis rotation
- Drag or tap to rotate the axis. Width samples and sqft update live.
- Confirm locks the axis for measurement.

### Generate text
- Button only appears if content LLM is enabled and inference is reachable.
- Disabled if the text service is down.
- Never runs automatically. User taps it.

### Publish flow
- Tap Publish. Status moves to publishing. Poll for result.
- Success: show result, offer to open in store.
- Failed: show error detail, keep draft and photos, allow retry.
- SLAB-UAT-* SKUs always create as Woo draft regardless of settings.

---

## Browser compatibility gate

Shown on load if browser lacks required APIs.

```
┌─────────────────────────────────────┐
│ Browser Update                      │
│ ──────────────────────────────────  │
│ This app requires a recent browser. │
│ Please update Safari or Chrome,     │
│ then try again.                     │
│ ──────────────────────────────────  │
│ [ Update Browser ]                  │
└─────────────────────────────────────┘
```

---

## UAT test cases (derived from wireframes)

1. **Settings once**: enter WP credentials, test connection, taxonomy syncs.
2. **First-run guidance**: card shows and dismisses.
3. **Capture**: take photo, mask overlays, adjust knob, overlay refreshes live, confirm.
4. **Length axis**: bounding rect draws, rotate axis, confirm, widths update.
5. **Type values**: enter SKU/length/thickness, computed values appear, done.
6. **Review — vision on, ≥ 0.7**: taxonomy fields pre-filled with AI badge, editable.
7. **Review — vision on, < 0.7**: taxonomy fields empty, per-field nudges visible, user fills manually.
8. **Review — vision off**: all taxonomy fields empty, per-field nudges visible, user fills manually.
9. **Publish — success**: draft created, product ID stored, images purged.
10. **Publish — duplicate SKU**: error on SKU field, edit SKU or open existing.
11. **Publish — stale taxonomy**: error on field, refresh store lists, pick current option.
12. **Publish — SLAB-UAT-***: always creates as draft regardless of settings.
13. **Generate text**: button visible when enabled, disabled when service down, LLM prose injected.
14. **Retake paths**: mask failure → retake, source too small → retake.