SlabUploader/docs/contracts/UX.md

UX contract — mill-owner flow

Status: SPEC · 2026-09-18. Presentation spec for the mill-owner flow on phone and PC browsers.

Requirements impact

Requirement	Impact on this design
CAPTURE-10	supported browsers, hard stop
CAPTURE-15	online only
CAPTURE-20, CAPTURE-25, CAPTURE-30	photo intake and calibration choice
CAPTURE-40, CAPTURE-41, CAPTURE-45, CAPTURE-50, CAPTURE-55	sheet/sensitivity controls, overlay, retake
CAPTURE-60, CAPTURE-65, CAPTURE-70, CAPTURE-80, CAPTURE-85, CAPTURE-90	axis, entry, derived numbers
CAPTURE-105, CAPTURE-135, CAPTURE-141, CAPTURE-145, CAPTURE-150, CAPTURE-155	crop guard, upload, preview/controls, failure
METADATA-10, METADATA-15, METADATA-30	required taxonomy fields and cardinality
METADATA-45, METADATA-55, METADATA-110	pre-fill, Generate text availability
PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-35, PUBLISH-36, PUBLISH-37, PUBLISH-38, PUBLISH-50	publish outcomes and messaging
REVIEW-5, REVIEW-10, REVIEW-15, REVIEW-20, REVIEW-25, REVIEW-30, REVIEW-40, REVIEW-45, REVIEW-50	ready set, gating, fields, limits
SETTINGS-65	create-status default

1. Shape

One column of screens: capture → review → publish. No dashboard and no batch view. The reader is a mill owner photographing one slab at a time, online. Capture often starts on a phone; the same flow runs on a PC browser.

2. Capture

1. Photos. Take one or more photos; the first is top-down with the lens parallel to the broad face. The owner chooses which photo is the calibration photo.
2. Mask overlay and controls. The app draws the mask on the source photo. The controls are exactly Sheet (auto, green, black) and Sensitivity (0–100). A Sheet change runs immediately; a Sensitivity change debounces 2000 ms; a worker recomputes and the last good overlay stays visible. There is no apply step and no server round trip; values persist until reset.
3. Confirm the mask. The owner confirms the edge; approval is blocked when the mask has no slab pixels. A broken or non-contiguous mask resolves as a retake.
4. Length axis. The app draws the bounding rectangle and the length axis; the owner rotates it to the prevailing length and confirms. On a nearly square slab the owner chooses the axis.
5. Numbers. The owner enters length and thickness in 1/8-inch steps and the SKU. The browser computes widths, sqft, and bdft. These are display only; the server never recomputes them.
6. Continue. Uploads originals, processed PNGs, and the numbers as a calibrated draft; status becomes calibrated.

The preview is display-only and never drives the math. Failures such as a broken mask or an undersized source never guess; the resolution is retake.

3. Review

• Vision pre-fill. At or above the threshold (default 0.7) a field is pre-filled and shown with an "AI" badge; below it the field starts empty. The badge is presentation only and clears on edit.
• Required set. Exactly one species and at least one wood-category leaf; one Edge Type, at least one Figure, exactly one Grade, one Thickness band, one Moisture; fig-* and feat-* tags optional; price; title, short_description, and description.
• Primary category. The owner declares one primary wood category and any secondary ones; the default is the first selected.
• Inline nudges. Every empty required field shows an inline nudge as the owner works; there is no single submit-time gap list.
• Calculated fields. Widths, sqft, and bdft are read-only and not overridable.
• Generate text. The control appears only when content generation is enabled and the endpoint is reachable; it is disabled when the text service is down; it never runs automatically.

4. Publish

• A normal SKU uses woo_create_status (default draft); a SLAB-UAT-* SKU always creates a draft. "Published" means the store create succeeded, not that it is live.
• Success. The local draft and photos are gone; the store product reference is shown.
• Duplicate SKU. "This SKU already exists in the store (any status)." with Edit SKU and Open Existing.
• Stale value. "This value is no longer valid. Pick from the current list," with current options.
• Failure. A plain message on the affected field or action, classified recoverable or unrecoverable, with Retry while the draft and photos are retained; no raw code.

5. Browser gate

Supported families are iOS Safari and Android Chrome, plus desktop Chrome, Edge, and Firefox. An unsupported client gets a hard stop with an update or switch link; there are no polyfills.

6. Canonical error and empty copy

Situation	Copy
Mask failure	"Cannot isolate the slab edge. Adjust the controls or retake."
Axis check	"Rotate the axis to match the prevailing length of the slab."
Source too small	"Photo will be too small after cropping. Please retake with a closer shot."
Duplicate SKU	"This SKU already exists in the store (any status)."
Stale value	"This value is no longer valid. Pick from the current list."
Store unreachable	"Cannot reach the store. Check your connection and settings."
Missing field nudge	per-field, in place (e.g. "Select species")
Browser gate	"This app requires a recent browser. Please update or switch, then try again."

7. Presentation-only details

First-run guidance card, "AI" badge styling, and the separate title/description step are presentation detail, not requirements.