Ty_Tech/SlabUploader
6
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove live UX-DESIGN.md

Browse Source
This commit is contained in:
Ty
2026-09-11 13:47:06 +00:00
parent b36e33e239
commit f5b3f4ebe6
1 changed files with 0 additions and 487 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/UX-DESIGN.md
-487
View File
@@ -1,487 +0,0 @@
# 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.