Key Screen Specifications¶

Detailed specs for the eight highest-stakes MVP screens — the ones that carry conversion, trust, and revenue. Each spec: purpose · layout (text wireframe, described LTR; the full layout mirrors in Arabic per Arabic-First & RTL) · components · states · validation & microcopy · edge cases. Screen IDs reference the Screen Inventory.

1. Customer Home (C08)¶

Purpose: Inspire first-time visitors and let returning customers resume in one tap. The screen answers "what can Yam3at do for my event?" and "where was I?" — in that order for new users, reversed for returning ones.

Layout (mobile):

[Header: logo · location "Kuwait City ▾" · notifications bell]
[Search bar: "What are you planning?"]
[IF active event] → Resume card: event name, date countdown,
   "2 quotes waiting" chip, progress ring
[Category rail: Venues · Catering · Photography · Decoration · … (icons, h-scroll)]
[Featured vendors carousel: photo cards w/ verified badge, rating, from-price]
[Occasion collections: "Weddings" / "Graduations" / "Corporate" banner cards]
[Recently viewed (if any)]
[Bottom nav: Home · Search · My Events · Messages · Profile]

Web adds a hero band with search and trust strip (vendors count, "licensed & verified" line) above the same content, 1200px column.

Components: search entry, resume-event card, category chips/rail, vendor card (image, name ar/en, verified badge, ★rating + count, "from KWD 250.000"), collection banner, notification bell with badge.

States: Loading — skeleton rails (no spinners). Empty (new user) — hero + "خطط أول يمعة لك" / "Plan your first event" CTA opening event wizard; categories still shown (browse must never be blocked by signup). Error — cached categories + retry banner. Success — as above; resume card only when an event has activity.

Microcopy: Search placeholder — AR: «شنو مناسبتك الجاية؟» EN: "What's your next occasion?". Resume card — AR: «وصلك عرضان جديدان لحفل تخرج سارة» EN: "2 new quotes for Sara's graduation". Never show raw status enums.

Edge cases: multiple active events → resume card becomes a pager (dots); logged-out mobile user taps My Events → auth sheet, then returns to intent; notification permission prompt only after first meaningful action (RFQ sent), never on first launch; location defaults to Kuwait City, changing it filters featured content but never hides categories.

2. Search Results (C10)¶

Purpose: Get from intent to a shortlist of 2–5 trustworthy vendors fast. Filtering must feel instant (Meilisearch); trust signals must be scannable on cards.

Layout (mobile):

[Search bar (editable) · filter icon w/ active-count badge]
[Filter chips row: Category ▾ · Budget ▾ · Area ▾ · Rating ▾ · Date ▾]
[Result count + sort: "34 vendors · Sort: Recommended ▾"]
[Vendor cards, vertical list:
   photo | name + verified ✓ | category · area
   ★ 4.8 (127) | "from KWD 350.000" | response-time chip
   [♡ favorite] ]
[FAB or inline card every ~8 results: "Not sure? Send one request
 to several vendors" → RFQ wizard]

Web: filters as left sidebar (right in AR), results grid 3-up, map toggle deferred to Scale.

Components: filter bottom-sheet (C11), chip row, sort menu (Recommended, Rating, Price low→high, Most reviewed), vendor card, favorite toggle (optimistic), RFQ nudge card.

States: Loading — 6 skeleton cards; chip taps show inline shimmer, previous results stay visible (no blanking). Empty — "لا توجد نتائج مطابقة" / "No vendors match these filters" + the two loosest filters suggested for removal + "Send an RFQ anyway" escape hatch. Error — retry card, filters preserved. Success — list; infinite scroll with page markers.

Validation: budget slider min<max, KWD, 3-decimal display but 5 KWD step granularity; date filter cannot be in the past.

Microcopy: result count — AR uses correct plurals: «٣٤ مزوّد خدمة» rendered "34 مزوّد خدمة" (Latin digits, see digit policy). Sponsored slots (Scale) always labeled «إعلان» / "Sponsored".

Edge cases: query in the "wrong" language (English query in AR UI) must still match — search index carries both name fields; zero-result category in a small launch market shows nearby-category suggestions instead of a dead end; favoriting while logged out queues the action through the auth sheet; a suspended vendor never appears even via a stale deep link (404 → category page).

3. Vendor Profile (C12)¶

Purpose: The trust-decision page. A customer arriving from Instagram or search decides here whether this vendor is real, good, and in budget. Primary conversion: Request Quote.

Layout (mobile):

[Gallery: full-width swipeable, 1st image = cover, count badge "1/24"]
[Header: logo avatar · name (ar/en) · verified ✓ (tap = explainer)
 ★ 4.8 (127 reviews) · category · area · "responds in ~4h"]
[Sticky bottom bar: [♡] [Message] [Request Quote ●primary]]
[Tabs or stacked sections:]
  About: description, languages spoken, working hours, location map
  Services & Packages: cards w/ name, from-price, inclusions → C13
  Reviews: rating breakdown bars, top 3 reviews w/ event type + date → C15
  Policies: cancellation policy, deposit norms, FAQ

Web: gallery left / summary right; sticky right rail holds CTA card.

Components: gallery viewer (C14), verified-badge popover, review summary block, service card, policy accordion, share sheet (profile URLs are public + indexable, hreflang paired), report-vendor link (low prominence).

States: Loading — cover-image blurhash + skeleton sections. Empty sections — no reviews yet: «مزوّد جديد على يمعات» / "New on Yam3at" (neutral, not negative); no packages: services listed without prices + "request a quote for pricing". Error — retry. Suspended/unpublished — public URL returns friendly 404 with category suggestions.

Microcopy: verified explainer — AR: «تم التحقق من الرخصة التجارية لهذا المزوّد من قبل فريق يمعات» EN: "This vendor's commercial license has been verified by the Yam3at team." From-price — AR: «يبدأ من 350.000 د.ك» EN: "from KWD 350.000" (formatted per bidi rules, never concatenated).

Edge cases: vendor wrote content in one language only → show it as-authored with a subtle "(بالإنجليزية)" / "(in Arabic)" tag, never machine-translate silently; quote-request while vendor is at plan quota → customer still sends, vendor sees upgrade prompt (customer never sees vendor's plan limits); phone numbers inside vendor descriptions are not auto-linked (anti-disintermediation: contact stays in-platform pre-booking, per RFQ business rules); gallery images pending moderation are hidden from public view only.

4. RFQ Wizard (C19)¶

Purpose: Turn a vague need into a structured, comparable request sent to up to N vendors — without form fatigue. This is the platform's core liquidity engine; each step is one decision (progressive disclosure).

Flow & layout:

[Stepper: ● ● ● ○  step 3 of 4 — mirrors in RTL]
Step 1 — Event basics: link to existing Event OR inline-create
         (type, date [+flexible ±days toggle], city/area, guests)
Step 2 — What do you need: category (pre-filled if entered from a
         vendor/category), free-text requirements, structured extras
         per category (e.g. Venues: indoor/outdoor, seating style)
Step 3 — Budget & attachments: budget band (slider or "not sure"),
         attachments (images/PDF ≤10 files, ≤10 MB each), quote deadline
Step 4 — Choose vendors: pre-filtered matching list, select 1–10
         (checkboxes), entry vendor pre-selected
Review sheet: summary card → [Send request ●]
[Every step: ‹ Back · autosave "Draft saved ✓" · Next ›]

Components: stepper, event picker/creator, category-specific field groups (config-driven), budget slider with "غير متأكد" / "Not sure yet" checkbox, file uploader with progress + previews, vendor multi-select cards, review summary.

States: Draft autosave after every step (RFQ status Draft); resumable from Home and RFQ list. Sending — blocking progress ≤3s then optimistic success. Success — celebration-light confirmation: «تم إرسال طلبك إلى 5 مزوّدين» / "Your request went to 5 vendors" + expected-response note + [Track quotes]. Error — draft preserved, retry; per-file upload errors inline.

Validation: date ≥ today+1 (same-day RFQs disallowed at MVP); guests 1–5,000 integer; budget min ≥ KWD 10.000 when specified; requirements text ≤ 2,000 chars; ≥1 vendor selected, ≤10 (and per-plan receive-quotas apply vendor-side); deadline between +1 and +14 days, default +5. Field errors inline in the field's language — AR: «اختر تاريخ المناسبة أولًا» EN: "Choose your event date first."

Microcopy: budget helper — AR: «الميزانية التقريبية تساعد المزوّدين يقدمون عرض أدق — وما تُشارك إلا معهم» EN: "A rough budget helps vendors quote accurately — it's only shared with them." Step titles are questions, not nouns («شنو تحتاج؟» / "What do you need?").

Edge cases: entry from vendor profile skips vendor selection but shows "add more vendors like this" suggestion; category with zero other vendors → step 4 shows the single vendor honestly, no padding; user abandons mid-upload → draft keeps completed uploads; changing category at step 2 after filling step 3 preserves budget/attachments, resets structured extras with a confirm; event date change after draft creation re-validates vendor availability hints.

5. Quote Compare (C21)¶

Purpose: The "confidence moment": put received quotes side-by-side so the customer decides on substance (price, inclusions, terms), not on whoever messaged last. Primary action: Accept one quote → booking flow.

Layout (mobile):

[Header: RFQ title · status chip "3 of 5 responded" · deadline countdown]
[Horizontal card pager, one quote per card (peek of next):
   vendor mini-header (name, ✓, ★)
   TOTAL: KWD 1,250.500 (large)
   line items (first 4, expandable)
   validity: "expires in 3 days"
   chips: deposit %, cancellation terms
   [Accept ●] [Message] [Reject ⋯]]
[Compare table toggle (2–3 quotes side-by-side, h-scroll):
 rows = total · deposit · line items ✓/– matrix · validity · rating]
[Non-responders row: "Awaiting: X, Y — remind"]

Web: table view is primary, cards secondary.

Components: quote card, comparison matrix, countdown chips, accept-confirmation sheet (restates total, deposit due now, validity), reject sheet with optional reason (helps vendor quality loop), negotiate → opens message thread with quote pinned.

States: Zero quotes yet — timeline expectation: «عادةً توصل أول العروض خلال 24 ساعة» / "First quotes usually arrive within 24 hours" + [Add more vendors]. Partial — as layout. All expired — explain + [Extend deadline] / [Resend RFQ]. Loading — skeleton cards. Accepted — accepted quote pinned with success treatment; others auto-marked Rejected with notice.

Validation: Accept blocked on expired quote (offer "request revalidation" which pings the vendor); accepting requires an active event date match — if the vendor marked a date conflict since quoting, warn before accept.

Microcopy: accept sheet — AR: «بقبولك هذا العرض، بيتم إنشاء حجز وتدفع عربون 250.000 د.ك الآن. باقي المبلغ حسب اتفاقك مع المزوّد.» EN: "Accepting creates a booking. You'll pay a KWD 250.000 deposit now; the balance follows your agreement with the vendor." Reject reasons list: price, changed plans, chose another vendor, other.

Edge cases: quote revised during negotiation → card shows "Updated" badge + change history link; two quotes accepted race (double-tap/multi-device) → server enforces single acceptance, second attempt gets friendly conflict message; vendor withdraws a quote → card grays with reason; comparing quotes with different structures (hourly vs package) → matrix falls back to totals + free-text rows, never fakes equivalence; RFQ cancelled by customer → all vendors notified, compare screen becomes read-only archive.

6. Event Dashboard (C18)¶

Purpose: The Event OS made visible: one screen where a customer sees everything about one event — budget position, vendor pipeline, bookings, conversations — and always knows the next action. This screen is why Yam3at is not a directory.

Layout (mobile):

[Event header: name · type icon · date + countdown "in 45 days"
 · Hijri annotation when near religious dates]
[Budget bar: committed KWD 2,150.000 / budget KWD 4,000.000
 (segments: paid · deposits due · quoted-pending)]
[Next actions strip (max 3, priority-ordered):
 "Pay venue deposit by Thu" · "3 quotes to review" · "Rate your photographer"]
[Vendor pipeline board (h-scroll columns or stacked lists):
 Requested (2) → Quoted (3) → Booked (2) — cards = vendor mini + status]
[Bookings timeline: date-ordered confirmed services]
[Quick links: Messages (3 unread) · Files · Add vendors +]

Web: two-column — pipeline + timeline left, budget + actions rail right.

Components: budget progress bar with legend, next-action cards (deep links), pipeline status cards, booking timeline items, event edit sheet (name/date/guests), add-vendor entry → RFQ wizard.

States: Fresh event (empty) — friendly scaffold: budget bar at 0, pipeline empty with «ابدأ بإضافة المزوّدين» / "Start by adding vendors" + top categories for the event type. Loading — skeleton blocks per module. Error — per-module error cards (budget can fail without killing pipeline). Post-event — dashboard flips to wrap-up mode: outstanding balances, review prompts, "rebook favorites" (Rebook is the lifecycle's last step).

Microcopy: budget over-commitment — AR: «العروض المقبولة تجاوزت ميزانيتك بـ 350.000 د.ك — تقدر تعدّل الميزانية أو تراجع الحجوزات» EN: "Your commitments exceed budget by KWD 350.000 — adjust your budget or review bookings." Tone reassuring, never alarming red-alert.

Edge cases: event date passes with pending RFQs → auto-expire with digest notification; deleted/cancelled booking returns its amount to available budget with a ledger note; multiple events share a vendor conversation → thread shows event context chips; guest-count/date edits after bookings exist → warn that confirmed vendors are notified of changes; budget never blocks actions (it informs — the customer stays in control).

7. Vendor RFQ Inbox + Quote Composer (V11–V13)¶

Purpose: The vendor's money screen. Inbox: triage new requests fast, spot the ones worth quoting, never miss an expiry. Composer: produce a professional, comparable quote in under 3 minutes on a phone.

Layout — Inbox (mobile):

[Header: "طلبات العروض / Requests" · quota chip "12/20 quotes left this month"]
[Filter tabs: New (5) · Quoted · Negotiating · Expiring ⚠ · Archived]
[RFQ cards: event type icon · "Wedding · 250 guests"
 date · area · budget band "KWD 2,000–3,000"
 countdown "respond within 2d 4h" · match chip "matches: Venues"
 [Quote ●] [Decline]]

Layout — Composer:

[Context header: collapsed RFQ summary (expandable) — requirements
 & attachments always one tap away]
[Line items: description (ar/en free text) · qty · unit price → auto totals]
[+ Add item · + Add discount (amount or %)]
[Totals: subtotal · discount · TOTAL KWD 2,450.000 (auto, tabular figures)]
[Deposit required: % or fixed → shows computed amount]
[Validity: 7 days ▾ (3–30)] [Terms & notes ≤1,000 chars] [Attach PDF/images]
[Preview as customer] [Send quote ●] [Save draft]

Components: quota meter (plan-linked, Vendor Subscriptions), RFQ card with countdown, decline sheet (reason required: unavailable date, out of area, budget mismatch, other), line-item editor with numeric keypad, deposit calculator, quote preview modal (renders exactly what the customer sees, in the customer's language layout).

States: Inbox empty (new vendor) — checklist to improve matching: complete profile %, add gallery, add services. Inbox loading — skeleton cards. Quota exhausted — RFQs still visible (never hide demand) but Quote CTA becomes [Upgrade to respond] with plan sheet. Composer draft — autosaved; Sending → optimistic; Sent — success + "customer notified" + expected next statuses.

Validation: ≥1 line item; qty ≥1 integer; unit price > 0, KWD 3 decimals; discount ≤ subtotal; deposit 0–100% (default from vendor settings, warning above 50%: customers accept lower deposits more often); validity 3–30 days; total > 0. Errors inline — AR: «أضف بندًا واحدًا على الأقل» EN: "Add at least one line item."

Microcopy: decline confirmation reassures — AR: «ما بيأثر الرفض على ترتيبك إذا كان السبب عدم توفر التاريخ» EN: "Declining for an unavailable date doesn't hurt your ranking." Expiring tab card: "expires today at 6 PM" absolute+relative.

Edge cases: RFQ cancelled by customer while composing → composer locks with notice, draft archived; two team members (Enterprise) open same RFQ → soft lock "Ahmed is drafting a quote"; attachment from customer fails virus scan → shown as blocked, not broken; vendor edits a sent quote → allowed only in Negotiating status and creates a revision (never silent mutation); RFQ arrives outside vendor's declared service area (customer forced it) → area-mismatch chip shown, vendor decides; plan downgrade mid-month → existing sent quotes unaffected, remaining quota recalculated.

8. Checkout / Payment (C24–C25)¶

Purpose: Convert an accepted quote into a confirmed booking by taking the deposit — with zero ambiguity about what is being paid, to whom, and what happens if plans change. KNET-first (Kuwait), then cards/wallets, via MyFatoorah/Tap behind the payment abstraction.

Layout:

[Order summary card (collapsed, expandable):
 vendor · event · service · event date
 total KWD 2,450.000 · deposit due now KWD 490.000 · balance later]
[Cancellation policy summary: 2 lines + "read full policy"]
[Payment methods (radio):
 ◉ KNET  ○ Visa/Mastercard  ○ Apple Pay (iOS)  ○ Google Pay (Android)]
[Trust strip: PSP logos · "payments processed securely — Yam3at never
 stores your card number"]
[Pay KWD 490.000 ● — amount ON the button]
→ PSP hosted page / native sheet → return
[Result screen: ✓ success (booking ref, receipt, next steps)
 or ✗ failure (reason, retry, switch method)]

Components: summary card, policy disclosure, method selector (KNET pre-selected in Kuwait), PSP redirect/webview handler, result screen with receipt download (PDF, bilingual), booking deep link.

States: Loading — summary skeleton; Pay disabled until totals verified server-side. Processing — full-screen blocking state with PSP branding: «لا تغلق الصفحة أثناء إتمام الدفع» / "Don't close this page while we complete your payment". Success — the one full celebration moment in the app (single confetti burst, respects reduced-motion) + booking status Confirmed + calendar-add + [Go to my event]. Failure — human reason mapping (declined, insufficient funds, timeout), amount unchanged, [Try again] [Choose another method]; no double-charge possible (idempotency key per attempt). Pending/unknown (webhook lag) — honest state: «ندقق على عملية الدفع — بنأكد لك خلال دقائق» / "We're confirming your payment — you'll hear from us within minutes"; booking held in Pending.

Validation: amount server-authoritative — client never computes the charge; quote must still be valid & accepted at pay time (revalidate on screen open); currency KWD, 3 decimals everywhere including the button; Apple/Google Pay shown only when device-capable.

Microcopy: deposit clarity — AR: «تدفع الآن العربون فقط (490.000 د.ك). المتبقي 1,960.000 د.ك يُدفع حسب سياسة المزوّد.» EN: "You're paying the deposit only (KWD 490.000). The remaining KWD 1,960.000 is due per the vendor's policy." Failure copy never blames the user.

Edge cases: user backgrounds the app during KNET redirect → resume logic re-queries payment status before showing anything; quote expires between accept and pay → graceful revalidation path, not an error wall; duplicate webhook / replay → idempotent booking confirmation; partial refund flows route through booking detail (C27) → Refund Requested status, admin queue (A10); network loss on result screen → status pull on reconnect; receipt email always sent in the customer's preferred_locale with bidi-safe amounts.

Build order¶

Recommended implementation sequence: 7 → 3 → 2 → 4 → 5 → 8 → 6 → 1. Vendor supply tooling and the vendor profile create marketplace inventory; discovery and RFQ create demand; payment closes the loop; home and event dashboard polish retention last.