spec(§5): UX layout — landing, sign-in (2-step), create-storefront, admin shell

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-10 07:05:25 -07:00
parent a32061ac54
commit e68692840f
1 changed files with 76 additions and 1 deletions
@@ -450,7 +450,82 @@ Scenario: PUC-11 — Fresh deployed environment to first merchant

 ## 5. UX Layout

-<!-- §5 pending -->
+Text is the source of truth; wireframes are generated from these descriptions
+on demand and not committed. One SPA, four surfaces. Visual language: calm,
+text-first, honest — no countdowns, no badges, no fake density.
+
+### 5.1 Screen: Landing (serves PUC-1)
+
+- **Purpose:** a Visitor learns what ecomm is and picks a door.
+- **Layout (top → bottom):**
+  - **Header:** wordmark "ecomm" (left); "Log in" link (right).
+  - **Primary content:** one short value statement (what ecomm is, in OHM
+    voice — honest commerce, your storefront is yours); primary button
+    **"Create your storefront"**.
+  - **Footer:** minimal (project identity).
+- **States:** happy only — static page. A signed-in Merchant hitting `/` is
+  redirected per entry routing (§6.5, PUC-6/PUC-5).
+- **Notifications:** none.
+
+### 5.2 Screen: Sign in (serves PUC-2, PUC-3; two steps)
+
+- **Purpose:** the single email + one-time-code flow behind both doors.
+- **Step 1 — email entry:**
+  - **Header:** wordmark; back-to-landing link.
+  - **Primary content:** heading framed by the door used ("Create your
+    storefront" / "Log in" — same form); email field (label "Email";
+    autofocus); primary button **"Send code"**; one line of honest copy:
+    "We'll email you a one-time code. That's all we need."
+  - **States:** happy → step 2 · invalid email format: inline field error ·
+    sending: button busy state · resend cooldown active: button disabled with
+    "you can resend in ~Ns" (PUC-2c) · delivery failure: banner "We couldn't
+    send the code — try again" (no fake success; §6.9).
+- **Step 2 — code entry:**
+  - **Primary content:** "We sent a code to ⟨email⟩" (with a "wrong address?"
+    link back to step 1); code field (one-time-code input semantics); primary
+    button **"Continue"**; secondary "Resend code" (cooldown-aware).
+  - **States:** happy: session starts → entry routing (§6.5) · wrong code:
+    inline "That code didn't match" with attempts remaining (PUC-2a) ·
+    expired: inline "That code expired" + resend offer (PUC-2b) · attempts
+    exhausted: code invalidated, prompt to request a fresh one · loading:
+    button busy.
+  - **Honest-copy rule (PUC-3):** after verification the screen states which
+    happened — "Welcome to ecomm" (new account) vs "Welcome back" (existing).
+- **Notifications:** the one-time-code **email** (subject "Your ecomm code:
+  ⟨code⟩"; body: the code, its validity window, and "if you didn't request
+  this, ignore it"). In localhost/dev the code reaches the developer via the
+  dev channel instead (§6.5 PUC-10).
+
+### 5.3 Screen: Create storefront (serves PUC-4, PUC-5, PUC-7)
+
+- **Purpose:** a storefront-less Merchant establishes their one storefront.
+- **Layout:**
+  - **Header:** wordmark; signed-in email (right) with a "Sign out" action
+    (PUC-9).
+  - **Primary content:** heading "Create your storefront"; name field (label
+    "Storefront name", explicitly optional — helper text "You can leave this
+    blank; we'll pick a placeholder name you can change later"); primary
+    button **"Create storefront"**.
+- **States:** happy: → admin (PUC-6) · blank name: allowed — a default name is
+  generated (corpus 14.01.0026) · creating: button busy · already-owns
+  (defense in depth, PUC-7): banner "Your account already has its storefront"
+  + link to the admin · error: banner with retry.
+- **Notifications:** none (no confirmation email — minimal channel use).
+
+### 5.4 Screen: Admin shell (serves PUC-8, PUC-9)
+
+- **Purpose:** the storefront's stable home; honestly empty in this release.
+- **Layout:**
+  - **Header:** storefront name (left — the admin's anchor identity);
+    signed-in email + "Sign out" (right).
+  - **Primary content:** empty state — heading with the storefront's name,
+    one line: "There's nothing to manage yet. Catalog, orders, and settings
+    will appear here as ecomm grows." Nothing else: no zeroed metric tiles,
+    no locked-feature teasers (OHM: Agency & Anti-Manipulation — no
+    manufactured aspiration).
+- **States:** happy/empty are the same state by design · loading: minimal
+  skeleton while `/me` resolves · session expired: redirect to sign-in.
+- **Notifications:** none.

 ## 6. Technical Design