tripz-llc/docs/DESIGN.md

Tripz Design System

Project Overview

Tripz is a multi-tenant white-label ride-hailing platform (SaaS). It enables taxi offices and fleets to launch branded ride-hailing apps. The platform has 4 interfaces: Rider mobile app, Driver mobile app, Tenant Admin web dashboard, and Super-Admin web dashboard.

Primary language: Arabic (RTL-first). English is secondary. All designs must support both directions.

---

Brand Identity

Colors

Primary Seed Color: #1A73E8 (Google Blue - default, customizable per tenant)

Light Mode Palette:

• Primary: #1A73E8
• Primary Variant: #1557B0
• Secondary: #5F6368
• Background: #FFFFFF
• Surface: #F8F9FA
• Surface Raised: #FFFFFF
• On Primary: #FFFFFF
• On Background: #202124
• On Surface: #5F6368

Dark Mode Palette:

• Primary: #8AB4F8
• Primary Variant: #AECBFA
• Secondary: #9AA0A6
• Background: #121212
• Surface: #1E1E1E
• Surface Raised: #2D2D2D
• On Primary: #000000
• On Background: #E8EAED
• On Surface: #9AA0A6

Semantic Colors:

• Success: #34A853 (green)
• Warning: #FBBC04 (amber)
• Danger: #EA4335 (red)
• Info: #4285F4 (blue)

Typography

English + Numbers: Inter (Regular 400, Medium 500, SemiBold 600, Bold 700) Arabic: IBM Plex Sans Arabic (Regular 400, Medium 500, SemiBold 600, Bold 700)

Type Scale:

• Display: 32px / Bold
• Headline: 24px / SemiBold
• Title: 20px / SemiBold
• Body Large: 16px / Regular
• Body: 14px / Regular
• Label: 12px / Medium
• Caption: 12px / Regular

Rules:

• Latin digits (1, 2, 3) always, even in Arabic text
• Tabular figures for prices and counters
• Line height: 1.4 for body, 1.2 for headings

Spacing (4px grid)

• xs: 4px
• sm: 8px
• md: 12px
• base: 16px (default page padding)
• lg: 24px
• xl: 32px
• xxl: 48px

Border Radius

• Small (badges, chips): 8px
• Medium (buttons, cards): 12px
• Large (bottom sheets, modals): 24px
• Full (avatars, icons): 9999px

Shadows

• Light mode: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08)
• Dark mode: Use elevation through surface brightness, not shadows

Icons

• Family: Material Symbols Rounded
• Sizes: 20px (small), 24px (default), 32px (large)
• Style: Outlined by default, Filled for active states

---

Design Principles

1. One screen = one job. Each screen asks one question and has one primary CTA.
2. Clarity over decoration. No heavy gradients, no ornamental elements. Clean and functional.
3. Thumb zone. Primary actions in the bottom third of the screen. Top = information, Bottom = action.
4. State always visible. Show loading skeletons (not spinners), errors with retry, empty states with hints. A blank screen is a bug.
5. Animation is functional. Animations explain transitions, not decorate. Respect system reduce-motion.
6. RTL-first. Design for Arabic first, then mirror for English. All layouts must work in both directions.

---

Component Patterns

Buttons

• Primary: Filled, 52px height, 12px radius, white text on primary color
• Secondary: Outlined, 52px height, primary color border and text
• Text: No background, primary color text, 48px min touch target
• Loading state: Circular progress replaces text, button stays same size

Input Fields

• Height: 52px
• Border radius: 8px
• Border: 1px solid #DADCE0 (light) / #5F6368 (dark)
• Focus: 2px primary color ring
• Error: Red border + error message below
• Label: Floating label pattern

Bottom Sheets (Primary Dialog Pattern)

• Handle: 32px wide, 4px tall, centered, #DADCE0 color
• Border radius: 24px top corners
• Snap points: Collapsed (peek), Half, Full
• Background: Surface color
• No backdrop blur by default

Cards

• Border radius: 12px
• Padding: 16px
• Shadow: Light elevation shadow
• Background: Surface color
• Border: 1px solid subtle border in light mode

Navigation

• Bottom navigation (mobile): 3-5 items, icons + labels, active = primary color
• Drawer: Slide from start side, user profile header, menu list with icons
• AppBar: Flat (no shadow), title aligned to start direction, back arrow if nested

---

Mobile App Patterns (Rider & Driver)

Map Screens

• Edge-to-edge map to status bar
• All UI elements floating inside SafeArea
• Location pulsing dot on map
• Re-center floating action button (bottom-right, above nav)
• Bottom sheet for interactions (collapsed = peek, half = list, full = search)
• Map style switches with light/dark theme

Home Screen

• Full-screen map as background
• Collapsed bottom sheet: "Where to?" search field
• Below search: suggested/favorite places
• Floating: re-center button, menu hamburger (top-left in RTL)

Trip Flow

1. Home → Destination search
2. Destination → Route preview (polyline on map)
3. Route preview → Category selection (cards with prices)
4. Category → Searching animation (pulse on map)
5. Searching → Driver accepted (driver card + live ETA)
6. Driver accepted → Driver arrived (waiting timer)
7. Driver arrived → During trip (live tracking)
8. During trip → Invoice (fare breakdown)
9. Invoice → Rating (stars + reasons)

Driver-Specific

• Online/Offline toggle: prominent, top of home screen
• Offer overlay: card over map with countdown timer
• Earnings dashboard: clean data cards with charts

---

Web Dashboard Patterns

Layout

• Sidebar navigation: 240px width, dark background (#1A1A2E)
• Top bar: 64px height, white/dark surface, search + notifications + profile
• Content area: Light gray background (#F5F5F5), white cards
• Responsive: Collapsible sidebar on tablet, stacked on mobile

Tables

• Alternating row backgrounds
• Status badges with semantic colors
• Action buttons per row (icon buttons)
• Pagination at bottom
• Search + filter bar at top

Forms

• Two-column layout for desktop
• Single column for mobile
• Clear field labels and helpers
• Prominent submit button
• Cancel/Back option always visible

Cards

• White background with subtle border
• Header with title + optional action
• Consistent padding (24px)
• Shadow on hover

---

RTL/Arabic Guidelines

• All layouts must mirror for RTL
• Back arrows point right in RTL
• Text alignment: start (left in LTR, right in RTL)
• Numbers always Latin digits (1, 2, 3), never Arabic (١، ٢، ٣)
• Currency formatting follows locale
• Tabular/monospace digits for prices to prevent layout jumps

---

Light/Dark Mode

• Default: Follow system setting
• User can override in settings
• Light mode: White backgrounds, subtle shadows for depth
• Dark mode: Dark gray surfaces (#121212 base), no shadows (use surface brightness for elevation)
• Map style switches between day/night tiles
• Semantic colors slightly adjusted for dark mode contrast

---

Animation

• Tap feedback: 120ms, opacity/scale micro-animation
• In-screen transitions: 240ms, easeOutCubic
• Sheet/Page transitions: 400ms, easeOutCubic
• Loading skeletons: Shimmer animation on gray placeholders
• Respect reduce-motion: All animations optional

---

What NOT to Do

• No heavy gradients on backgrounds
• No drop shadows heavier than 1 layer
• No decorative elements that don't serve a purpose
• No text smaller than 12px
• No contrast below 4.5:1 for text on background
• No raw hex colors in feature code (use theme tokens)
• No spinners (use skeleton loading instead)
• No blank white/error screens (always show meaningful state)

---

Screens to Design

Rider App (Mobile)

1. Splash screen
2. Onboarding (3 slides)
3. Phone number login
4. OTP verification (4 digits)
5. Name entry
6. Home (map + "Where to?" sheet)
7. Destination selection (draggable sheet, autocomplete, stops)
8. Route preview (polyline, markers, distance/time)
9. Category selection (vehicle cards with prices)
10. Searching for driver (pulse animation)
11. Driver accepted (driver card, ETA, route)
12. Driver arrived (waiting timer)
13. During trip (live tracking)
14. Trip invoice (fare breakdown)
15. Rating (stars + quick reasons)
16. Navigation drawer (menu)
17. Chat (in-trip messaging)
18. Trip history list

Driver App (Mobile)

1. Splash screen
2. OTP login
3. Document registration (photo upload + face liveness)
4. Home (map + online/offline toggle)
5. Ride offer overlay (countdown timer)
6. Navigate to pickup
7. Arrived at pickup (waiting timer)
8. During trip (navigation)
9. Trip complete (earnings summary)
10. Earnings dashboard
11. Balance & top-up
12. Navigation drawer
13. Chat with rider

Web Dashboards

1. SuperAdmin: Dashboard overview (KPIs + charts)
2. SuperAdmin: Tenant list (table + actions)
3. SuperAdmin: Create tenant (form)
4. Admin: Driver management (table + approval)
5. Admin: Trip listing (table + filters)
6. Admin: Document review
7. Admin: Payouts management
8. Service: User/trip search

Landing Page

1. Hero section (bilingual headline + CTAs)
2. Features section (3 pillars)
3. Savings calculator (interactive)
4. Platform screenshots
5. Pricing tiers
6. FAQ section
7. Footer