diff --git a/docs/UX.md b/docs/UX.md index d3694cd..9a8fa26 100644 --- a/docs/UX.md +++ b/docs/UX.md @@ -1,10 +1,8 @@ # Phone flow -What the mill owner does on the phone, from first photo to a store listing. +What the mill owner does on the phone, from first photo to a store listing. Math and constants live in `docs/TECH-SPEC-PIPELINE.md`. Field names and the ready set live in `docs/DATA-MODEL.md`. Store payload and create steps live in `docs/CONTENT-WOO.md`. -Pipeline math lives in `docs/TECH-SPEC-PIPELINE.md`. Field names and the ready set live in `docs/DATA-MODEL.md`. Store payload and create steps live in `docs/CONTENT-WOO.md`. - -You type a value, the app keeps it. Vision only fills when it is sure enough; a weak guess stays off the form. +Values you type are kept as-is. Vision fills store fields only when it is at least 0.7 confident; everything else you fill in yourself. --- @@ -12,44 +10,40 @@ You type a value, the app keeps it. Vision only fills when it is sure enough; a ### Settings once -Store URL is deploy text from `WOO_BASE_URL`. It is not an input. Settings shows it read-only so you always know which store this phone is talking to. +The store URL shows read-only from the deploy (`WOO_BASE_URL`). It is not an input field. You always know which store this phone talks to. -Enter the WordPress username and application password for the low-privilege store user. The password is write-only; it never comes back on load. Rotate by revoking it in WordPress Users → Profile and typing a new one here. +Enter the WordPress username and application password for the low-privilege store user, under Users → Profile in WordPress. The password is write-only: you type it once, and it never comes back on load. To rotate, revoke the old one in WordPress and enter a new one here. -Optional on the same screen: species $/bdft table, vision on/off plus endpoint and key, draft vs publish for new listings (default draft), reset capture knobs to factory, optional refresh of store lists. **Test connection** always pulls fresh species, attributes, and tags from the store. +On the same screen: species $/bdft rates, vision on/off with endpoint and key, draft vs publish for new listings (default draft), reset capture knobs to factory, and an optional refresh of the store lists. **Test connection** always pulls fresh species, attributes, and tags from the store when it succeeds. ### First run on the floor -One short card, then dismiss. 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. The app does not read the tape and does not run a ruler detector. - -"Don't show again" stays off until you turn the card back on in Settings. +One short card, then dismiss. 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. The app does not read the tape and has no ruler detector; your typed number is what it measures against. ### Capture Take 1 to 5 inventory photos. -The source photo stays on screen. The mask is drawn on that original: kept wood versus dropped sheet. - -Four knobs sit next to the overlay, not in Settings: +The source photo stays on screen, and the mask draws over that original: kept wood versus dropped sheet. Four knobs sit next to the overlay, not in Settings: 1. Sheet — auto, green, or black 2. Sensitivity 3. Edge offset 4. Feather -Move a knob and background removal re-runs on this photo. The overlay refreshes immediately. Nothing saves to the server for mask tuning. Knobs stick in local storage until you reset them. +Move a knob and background removal re-runs on this photo; the overlay refreshes immediately. Nothing round-trips to the server for mask tuning. The knobs stick in local storage until you reset them to factory. -Your eye is the check. If the cut sits on the wood edge, confirm. If it clips grain or still holds sheet after you tune, retake the photo. This POC has no server "Try harder" control. +Your eye is the only check on the mask: there is no confidence score, no quality gate, and no image-quality classifier. If the cut sits on the wood edge, confirm it. If it clips grain or still holds sheet after you tune, retake the photo. The one-photo server U2Net path stays in the architecture for post-POC; it has no control in this POC. ### Length axis -Bounding rectangle and length axis draw on the confirmed mask. Width sample lines sit every 6 inches along that axis. Rotate until the axis matches the slab's long grain, then confirm. On a nearly square piece, you pick which side is length. +The bounding rectangle and length axis draw over the confirmed mask, with width sample lines every 6 inches along that axis. Rotate until the axis matches the slab's prevailing length, then confirm. On a nearly square piece you pick which side is length. ### Type length, thickness, SKU -Manual values win. The phone computes square feet, board feet (`bdft = sqft × thickness_in`, no `/12`), and width min / max / avg from the mask and your length. +Manual values win. The phone computes square feet, board feet (`bdft = sqft × thickness_in`, no `/12`), and width min / max / avg from the mask and your typed length. -It builds 3:4 transparent PNG inventory images at 80% fill on the extremes. After that crop, if the source does not have enough pixels for a shorter side of 1600 px, that photo is not publishable until you retake it. No fake upscale. The floor and the math are in `docs/TECH-SPEC-PIPELINE.md` (constants and TV-7), not a banner painted on the camera. +It builds 3:4 transparent PNG inventory images at 80% fill on the extremes. After that crop, if the source does not have enough pixels for a shorter side of 1600 px, that photo is not publishable until you retake it. No fake upscale. The floor and the math are in `docs/TECH-SPEC-PIPELINE.md` (constants and TV-7); they are not painted on the camera screen. ### Draft upload (calibrated) @@ -57,24 +51,22 @@ When mask, axis, length, thickness, and SKU are set and the numbers and PNGs are ### Review (store fields) -Everything the listing needs lands here. Empty required controls show an inline empty state as you work, not only at submit. +Everything the listing needs lands here. A required control that is still empty shows an inline empty state as you work, not only at submit. -**Always on the form from capture / defaults** +**Always on the form from capture and defaults** - Inventory photos as processed transparent PNGs (at least one) - SKU, length, thickness - Computed sqft, bdft, width min / max / avg -- Thickness store band from typed thickness, rounded **up** into the synced Woo thickness range -- Moisture defaults to **kiln-dried**. Vision does not set moisture. Change it if the slab is not KD. -- Price: species $/bdft × bdft when a rate exists, else blank. Override anytime. No rule still allows a typed price. +- Thickness store band from your typed thickness, rounded **up** into the synced Woo thickness range +- Moisture starts at **kiln-dried**. Vision does not set moisture. Change it if the slab is not KD. +- Price: species $/bdft × bdft prefills when a rate exists for that species. If there is no rate, the field starts empty and you type the price. Override anytime; your override sticks for this slab. **Species and store taxonomy** -Pickers and any vision lists are exactly the last pull from the store. No hardcoded species list. +Pickers and any vision lists are exactly the last pull from the store. No hardcoded species list. A new Woo species becomes selectable only after a sync lands it in the cache. -If vision is on and confidence is at least 0.7, it may pre-fill species, wood categories, edge type, figure, grade, and feature (`feat-*`) tags. Every pre-fill is editable. Typed values win. - -If vision is off, or confidence is under 0.7, those fields start empty. Fill them by hand. A low-confidence guess is never shown as a default. +If vision is on and confidence is at least 0.7, it may pre-fill species, wood categories, edge type, figure, grade, and feature (`feat-*`) tags. Every pre-fill is editable; typed values win. If vision is off or confidence is under 0.7, those fields start empty and you fill them by hand. A low-confidence guess never shows as a default. **Required before the slab is ready to list** @@ -84,56 +76,54 @@ If vision is off, or confidence is under 0.7, those fields start empty. Fill the - At least one figure term - At least one `fig-*` tag - At least one grade -- Thickness band (from the round-up above) +- Thickness band (the round-up above) - Moisture (kiln-dried unless you changed it) - Price - SKU, length, thickness, client sqft / bdft / widths, at least one inventory PNG -Feature (`feat-*`) tags are optional (zero or more). - -Species plus one figure is not enough. Empty vision fields are not the full submit list. +Feature (`feat-*`) tags are optional; zero is fine. ### Title, short title, description -Type them, or tap **Generate text**. Generate text never runs on its own. It is off unless content generation is enabled in Settings. If the text service is down, the button is disabled; templates still work and publish is not blocked. +Type them, or tap **Generate text**. Generate text never runs on its own and is off unless content generation is enabled in Settings. If the text service is down, the button is disabled; templates still work and publish is not blocked. The model writes prose only — character, color, grain, uses. Measured length, width, thickness, square feet, and board feet are facts it receives, never numbers it invents. -If title, short title, or description are still blank at publish, templates fill them from measured facts (species, lengths, widths, thickness, bdft). The model does not invent dimensions. +If title, short title, or description are still blank at publish, templates fill them from the measured facts (species, lengths, widths, thickness, bdft). You can edit any of it afterward. ### Publish -When the ready set above is complete, tap publish. App status moves through **publishing**. +When the ready set above is complete, tap publish. App status moves through **publishing** while you wait for the result. Create status comes from Settings (`draft` or `publish`, default `draft`). SKUs that match `SLAB-UAT-*` always create as Woo **draft**, even when Settings say publish. Practice listings stay draft so customers do not see them. -On success the server deletes originals and processed images. A slab marked published in the app means the store create succeeded. That is not the same word as WooCommerce "publish." +On success the server deletes originals and processed images. A slab marked published in the app means the store create succeeded; that is not the same word as WooCommerce "publish." --- ## Practice path (UAT) -Same capture and review as production. Use a `SLAB-UAT-*` SKU. The listing is forced to Woo draft regardless of the draft/publish setting. Change the SKU when you are ready for a real listing. +Same capture and review as production, with a `SLAB-UAT-*` SKU. The listing is forced to Woo draft regardless of the draft/publish setting. Change the SKU when you are ready for a real listing. --- ## Usual failures -**Mask clips wood or still holds sheet.** Turn the four knobs. Confirm by eye. If it is still wrong, retake. Bad edges silently shift square feet and widths; there is no later numeric score that catches a bad cut. +**Mask clips wood or still holds sheet.** Turn the four knobs; confirm by eye. If it is still wrong, retake. A bad edge silently shifts square feet and widths; there is no later numeric check that catches it. -**Axis skewed or wrong length side.** Rotate the axis, or retake. +**Axis skewed or on the wrong length side.** Rotate the axis, or retake. Widths and sqft follow whatever axis you confirm. -**Source too small after the 3:4 / 80% crop.** Warn and retake that photo. See `docs/TECH-SPEC-PIPELINE.md` TV-7. No invented pixels. +**Source too small after the 3:4 / 80% crop.** The app warns and asks for a retake of that photo. No invented pixels; see `docs/TECH-SPEC-PIPELINE.md` TV-7. -**Required store field still empty.** Inline empty state on that control. You cannot publish until the full ready set in Main path is filled. +**Required store field still empty.** Inline empty state on that control. Publish stays blocked until the full ready set in Main path is filled. -**SKU already exists in the store under any status** (draft, private, publish, and the rest). Message sits on the SKU field: it already exists in the store (any status). Actions: edit the SKU, or open the existing listing when a link is available. This version does not edit the other product in place. Do not show a raw status code. +**SKU already exists in the store under any status** (draft, private, publish, and the rest). The message sits on the SKU field: it already exists in the store. Actions there: edit the SKU, or open the existing listing when a link is available. This version does not edit the other product in place. No raw status codes on screen. -**Category, attribute, tag, or price no longer valid after a list refresh.** Message on that field: the value is no longer valid; pick from the current list. Current options come with the error. Draft stays on the phone. +**Category, attribute, tag, or price no longer valid after a list refresh.** The message sits on that field: the value is no longer valid; pick from the current list, and the current options come with it. Your draft stays on the phone. -**Rules copy on the phone went stale at submit.** Brief "Updating rules." The phone refetches the shared rules, checks again, and retries. That is not a duplicate-SKU conflict. Do not show a raw status code. +**Rules copy on the phone went stale at submit.** Brief "Updating rules." The phone refetches the shared rules, checks again, and retries. That is not a duplicate-SKU conflict, and no raw status code shows. -**Store unreachable, auth failure, or other hard Woo failure.** Plain failure message. Slab can move to failed with detail. Draft and photos stay so you can retry. No stack traces on the phone. +**Store unreachable, auth failure, or other hard Woo failure.** Plain failure message, no stack traces. The slab can move to failed with detail; draft and photos stay so you can retry. -**Vision off or under 0.7.** Taxonomy fields that vision would have filled start empty. Fill the required set by hand. Moisture still starts kiln-dried. Thickness band still comes from the thickness you typed. Inference never blocks publish and never publishes on its own. +**Vision off or under 0.7.** The taxonomy fields vision would have filled start empty; fill the required set by hand. Moisture still starts kiln-dried, and the thickness band still comes from your typed thickness. Inference never blocks publish and never publishes on its own. **Generate text unavailable.** Button disabled. Type copy or let templates write at publish. @@ -143,4 +133,4 @@ Leaving a field: empty optional is fine; typed junk is not. SKU is `A-Z`, `0-9`, ## Out of scope for this POC UI -Brand polish and marketing chrome. Server U2Net "Try harder" on capture (kept in architecture for later; not a control here). A user slider for the 0.7 vision threshold. Offline / airplane capture. Any image-quality classifier or score. Strings painted on the live photo about lighting, steadiness, mask confidence, or a 1600 px camera requirement. +Server U2Net "Try harder" on capture (kept in architecture for later; not a control here). A user slider for the 0.7 vision threshold. Offline / airplane capture. Any image-quality classifier or score. Strings painted on the live photo about lighting, steadiness, mask confidence, or a pixel requirement.