UX Design Principles¶

Yam3at sells confidence: the right vendors, budget under control, deadlines met, organized communication, safe payments. Every screen must answer the customer's silent question — "can I trust this, and am I still in control?" — and the vendor's — "is this worth my time, and what do I do next?" These principles are binding for all three apps (Customer, Vendor, Admin) across web (Next.js) and mobile (Flutter).

1. Trust is a design material, not a feature¶

Events are high-stakes, high-emotion purchases. A wedding hall deposit in Kuwait can exceed KWD 2,000.000. Trust must be visible at every decision point.

Trust signal	Where it appears	Rules
Verified badge (موثّق)	Vendor cards, vendor profile header, quote compare	Only after admin approves the commercial license (see Vendor Onboarding). Never sold, never granted automatically. Tapping the badge explains what "verified" means.
Real reviews only	Vendor profile, search results	Reviews can only be written for Completed bookings (Reviews). Show the event type ("Wedding · March 2026") to prove authenticity. No anonymous star dumps.
Clear pricing	Listings, quotes, checkout	Always show currency and 3 decimals for KWD (`KWD 1,250.500`). "Starting from" prices must link to what's included. No price revealed only after contact — that is the WhatsApp-broker behavior Yam3at replaces.
Response indicators	Vendor profile, RFQ flow	"Usually responds within 4 hours", quote validity countdown. Sets expectations instead of leaving customers waiting in silence.
Payment safety cues	Checkout, booking detail	KNET/Visa/Apple Pay logos, PSP name, deposit vs. remaining balance breakdown, cancellation policy summary before the pay button.
Status transparency	RFQ, booking, refund flows	Every request has a visible status with a plain-language explanation and a "what happens next" line. No dead ends.

Anti-pattern: fake urgency ("3 people are viewing this hall!"), inflated ratings, or hiding fees until the last step. These destroy the one asset the platform sells.

2. Mobile-first, thumb-first¶

The GCC is a mobile-dominant market; assume the primary customer session is a phone held in one hand, often at night, often on a family group-chat break.

Design at 360×800 first; scale up to tablet/desktop, never down.
Primary actions live in the bottom half of the screen (bottom nav, sticky CTA bars). Minimum touch target 48×48 dp.
Web is not a second-class citizen: vendor discovery via Google/Instagram lands on web pages that must be shareable, fast, and indexable (vendor profiles, category pages).
One primary CTA per screen. On mobile, it is sticky (e.g. "Request Quote" on vendor profile, "Pay Deposit" on booking summary).

3. Celebration-warm, never cluttered¶

Yam3at's aesthetic should feel like an occasion (يمعة — a gathering), not a spreadsheet — but restraint wins.

Warmth from photography, not decoration. Vendor galleries are the hero. UI chrome stays quiet (deep purple + generous whitespace, see Design Tokens); imagery carries the celebration.
Accent gold/amber is reserved for moments of delight: booking confirmed, quote accepted, review submitted. Confetti-level animation only on true milestones (payment success), never on routine actions.
Density budget: customer screens max ~2 information tiers per card (name + category + rating + price-from). Everything else is one tap deeper.
Empty states are warm and directive ("No events yet — let's plan your first يمعة"), never blank.

4. Progressive disclosure for complex flows¶

The RFQ wizard, event creation, vendor registration, and quote composer are inherently multi-step. Never show the whole form at once.

One decision per step. RFQ wizard: (1) event & date → (2) service details → (3) budget & attachments → (4) select vendors → review & send. See key screen spec.
Always show progress (step X of Y), always allow back without data loss, always autosave drafts (RFQ status Draft exists for this reason — RFQ).
Smart defaults from context: launching an RFQ from a vendor profile pre-selects that vendor and category; launching from an event pre-fills date and guest count.
Advanced options (service area, flexible dates, per-item notes) are collapsed behind "More options", not deleted.

5. Accessibility: WCAG 2.1 AA, both directions¶

Contrast ≥ 4.5:1 for text, ≥ 3:1 for large text and UI components. The purple palette in Design Tokens is chosen with AA-passing pairs identified.
All functionality keyboard-operable on web; logical focus order that follows reading direction (right→left in Arabic).
Screen-reader support in both languages: lang/dir attributes set per element when mixing AR/EN; Flutter Semantics labels localized.
Never color alone: RFQ/booking statuses always pair color with an icon and a label.
Respect prefers-reduced-motion — celebrations degrade to a static success state.
Form errors: announced, inline, next to the field, in the field's language.
Text resizes to 200% without loss of function; no text baked into images (critical for bilingual content).

6. Performance is UX¶

Vendor galleries are image-heavy and Kuwaiti users are impatient like everyone else.

Budget	Target
LCP (4G, mid-range Android)	≤ 2.5 s on home, category, vendor profile
Interaction response	≤ 100 ms perceived (optimistic UI for favorites, message send)
Image policy	Responsive sizes + WebP/AVIF from object storage; blur-hash placeholders; gallery lazy-loads beyond the first 3 images
Skeletons over spinners	Every list/detail screen ships a skeleton state (see states in Key Screens)
Offline tolerance (mobile)	Cached event dashboard and messages readable offline; queued send with clear "sending…" state

A quote that takes 8 seconds to open reads as an untrustworthy platform, not a slow one.

7. Three apps, three tones¶

Same design system, deliberately different voice and density.

	Customer app	Vendor app	Admin panel
Tone	Inspiring and reassuring — "we've got your event"	Businesslike and efficient — "here's your money and your next action"	Dense and operational — "everything visible, nothing decorative"
Density	Low. Imagery-led cards, generous spacing	Medium. KPI tiles, actionable lists, tables on web	High. Data tables, filters, bulk actions, keyboard shortcuts
Color use	Full palette; warm accents at milestones	Primary + semantic status colors; no celebration effects	Mostly neutral; semantic colors strictly for state
Microcopy	Warm, second person, bilingual craft ("مبروك! حجزك مأكّد")	Direct, numbers first ("3 RFQs expire today")	Terse, unambiguous ("Approve · Reject · Request changes")
Home screen job	Inspire + resume: next event, pending quotes	Triage: new RFQs, today's bookings, expiring quotes	Queue clearance: approvals, flags, refund requests

Rule: an engine shared across apps (messaging, notifications, payments) keeps identical interaction mechanics everywhere — only tone, density, and entry points differ.

8. Bilingual by design, not by translation¶

Arabic is the first language of the product; English is a full equal, not a fallback. Every principle above must hold in both directions. The complete rules live in Arabic-First & RTL; the short version:

Design in Arabic first, verify in English — not the reverse.
Copy is authored per language by a native writer; machine translation is acceptable only as a draft.
Layouts must survive 20–40% string length differences without truncating meaning.

Decision checklist (use in every design review)¶

Does this screen add or protect trust? What could make it feel like a scam, and did we remove it?
Is the primary action reachable with a thumb, and is it the only primary action?
Does it work at 360 px wide, in Arabic, at 200% text size?
Are loading, empty, error, and success states designed — not implied?
Is anything shown that could be disclosed one step later instead?
Does the tone match the app (inspire / operate / administer)?
Would this screen still make sense to a first-time user who arrived from an Instagram ad?