# 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-130, CAPTURE-135, CAPTURE-141, CAPTURE-145, CAPTURE-150, CAPTURE-155 | crop guard, lineup order, 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-5, PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-35, PUBLISH-36, PUBLISH-37, PUBLISH-38, PUBLISH-50 | publish sequence, 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 Cites CAPTURE-20, CAPTURE-25, CAPTURE-40, CAPTURE-130. 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 Cites REVIEW-5, REVIEW-15, REVIEW-20, METADATA-45. - **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 Cites PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-25. - 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.