grokbot_ty
8d65984936
Move Gate A/B/C meanings to IMPL-PLAN. List UX-DESIGN as non-normative with signed UX.md winning conflicts. List INVENTORY in AGENTS §0.
22 KiB
22 KiB
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
- Settings (once)
- First-run guidance (once per device)
- Capture
- Length axis
- Type values
- Review
- Title / Description
- Publish
- 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)
- Settings once: enter WP credentials, test connection, taxonomy syncs.
- First-run guidance: card shows and dismisses.
- Capture: take photo, mask overlays, adjust knob, overlay refreshes live, confirm.
- Length axis: bounding rect draws, rotate axis, confirm, widths update.
- Type values: enter SKU/length/thickness, computed values appear, done.
- Review — vision on, ≥ 0.7: taxonomy fields pre-filled with AI badge, editable.
- Review — vision on, < 0.7: taxonomy fields empty, per-field nudges visible, user fills manually.
- Review — vision off: all taxonomy fields empty, per-field nudges visible, user fills manually.
- Publish — success: draft created, product ID stored, images purged.
- Publish — duplicate SKU: error on SKU field, edit SKU or open existing.
- Publish — stale taxonomy: error on field, refresh store lists, pick current option.
- Publish — SLAB-UAT-*: always creates as draft regardless of settings.
- Generate text: button visible when enabled, disabled when service down, LLM prose injected.
- Retake paths: mask failure → retake, source too small → retake.