bharath/docs/design/DESIGN_SYSTEM.md

# BharathTrucks — UI/UX Design System

**Version:** 1.0  
**Date:** 2026-05-31  

---

## 1. Design Philosophy

**"Sarkari Trust, Modern Usability"**

The design mimics Indian government portals (DigiLocker, UMANG, CoWIN) to build instant trust with users who associate government branding with legitimacy. However, the UX is modern and mobile-first — unlike actual govt apps.

### Design Principles
1. **Trust First** — Look official, feel reliable
2. **Simplicity** — Minimum steps, maximum clarity
3. **Accessibility** — Works for semi-literate users on budget phones
4. **Mobile-First** — 90%+ users will be on mobile
5. **Performance** — Light CSS, no heavy frameworks

---

## 2. Color Palette

### Primary Colors (Government-Inspired)

| Name | Hex | Usage |
|------|-----|-------|
| **Navy Blue** | `#1a237e` | Headers, primary buttons, nav |
| **Ashoka Blue** | `#0d47a1` | Links, active states |
| **Saffron** | `#ff6f00` | Accents, CTAs, urgency |
| **White** | `#ffffff` | Backgrounds, cards |
| **National Green** | `#2e7d32` | Success states, verified badges |

### Secondary Colors

| Name | Hex | Usage |
|------|-----|-------|
| **Light Grey** | `#f5f5f5` | Page backgrounds |
| **Border Grey** | `#e0e0e0` | Card borders, dividers |
| **Text Dark** | `#212121` | Body text |
| **Text Muted** | `#616161` | Secondary text |
| **Error Red** | `#c62828` | Errors, warnings |
| **Gold** | `#f9a825` | Premium badges, highlights |

### Gradient (Header Bar)
```css
background: linear-gradient(135deg, #1a237e 0%, #0d47a1 100%);
```

---

## 3. Typography

### Font Stack
```css
/* Primary — Official Devanagari + Latin */
font-family: 'Noto Sans', 'Noto Sans Devanagari', -apple-system, BlinkMacSystemFont, sans-serif;

/* Monospace (data, numbers) */
font-family: 'JetBrains Mono', 'Courier New', monospace;
```

### Scale

| Element | Size | Weight | Usage |
|---------|------|--------|-------|
| H1 | 24px / 1.5rem | 700 | Page titles |
| H2 | 20px / 1.25rem | 600 | Section headers |
| H3 | 16px / 1rem | 600 | Card titles |
| Body | 14px / 0.875rem | 400 | Default text |
| Small | 12px / 0.75rem | 400 | Captions, meta |
| Button | 14px / 0.875rem | 600 | Button labels |

### Hindi Text
- All headings bilingual: English on top, Hindi below (smaller)
- Example: "Load Board" / "लोड बोर्ड"

---

## 4. Layout System

### Grid
- Mobile: Single column, 16px padding
- Tablet: 2-column grid, 24px gutter
- Desktop: Max-width 1200px, centered, 3-column for dashboards

### Spacing Scale
```css
--space-xs: 4px;
--space-sm: 8px;
--space-md: 16px;
--space-lg: 24px;
--space-xl: 32px;
--space-2xl: 48px;
```

### Page Structure
```
┌──────────────────────────────────┐
│  Top Bar (Navy, Emblem + Title)  │  ← Govt-style header
├──────────────────────────────────┤
│  Navigation (Role-based)         │
├──────────────────────────────────┤
│                                  │
│  Content Area                    │
│                                  │
├──────────────────────────────────┤
│  Bottom Nav (Mobile only)        │  ← 4-5 icons
└──────────────────────────────────┘
```

---

## 5. Components

### 5.1 Header Bar (Govt-Style)
```
┌─────────────────────────────────────────┐
│ 🏛️  भारत ट्रक्स | BharathTrucks    ☰  │
│     राष्ट्रीय माल परिवहन मंच            │
└─────────────────────────────────────────┘
```
- Navy gradient background
- Ashoka-style emblem/icon on left
- Bilingual title
- Subtitle: "राष्ट्रीय माल परिवहन मंच" (National Freight Transport Platform)

### 5.2 Buttons

| Type | Style |
|------|-------|
| Primary | Navy bg, white text, 8px radius, slight shadow |
| Secondary | White bg, navy border, navy text |
| CTA/Urgent | Saffron bg, white text |
| Success | Green bg, white text |
| Danger | Red bg, white text |

```css
.btn-primary {
  background: #1a237e;
  color: #fff;
  border: none;
  border-radius: 8px;
  padding: 12px 24px;
  font-weight: 600;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
```

### 5.3 Cards (Load Card)
```
┌─────────────────────────────────┐
│ 📍 Mumbai → Delhi               │
│ 🚛 20 Ton | Open Body           │
│ 💰 ₹45,000 | 📅 2 Jun 2026     │
│ ┌─────────────────────────────┐ │
│ │  [Bid Now]  [View Details]  │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘
```
- White background, 1px border (#e0e0e0)
- 12px border-radius
- Subtle shadow on hover
- Left color accent bar (saffron for urgent, blue for normal)

### 5.4 Form Inputs
```css
.form-input {
  width: 100%;
  padding: 12px 16px;
  border: 2px solid #e0e0e0;
  border-radius: 8px;
  font-size: 14px;
  transition: border-color 0.2s;
}
.form-input:focus {
  border-color: #0d47a1;
  outline: none;
  box-shadow: 0 0 0 3px rgba(13, 71, 161, 0.1);
}
```

### 5.5 Trust Badges
```
┌──────────────────┐
│ ✓ सत्यापित       │  (Verified)
│   Verified User  │
└──────────────────┘
```
- Green border + green checkmark
- Certificate-style rounded badge
- Used for verified drivers/shippers

### 5.6 Bottom Navigation (Mobile)
```
┌─────┬─────┬─────┬─────┬─────┐
│ 🏠  │ 📋  │ ➕  │ 💬  │ 👤  │
│Home │Loads│Post │Chat │ Me  │
└─────┴─────┴─────┴─────┴─────┘
```

### 5.7 Status Badges
| Status | Color | Label |
|--------|-------|-------|
| Open | Blue | खुला / Open |
| Booked | Saffron | बुक / Booked |
| In Transit | Navy | रास्ते में / In Transit |
| Delivered | Green | पहुँचा / Delivered |
| Cancelled | Red | रद्द / Cancelled |

---

## 6. Iconography

- Style: Outlined, 24px, 2px stroke
- Source: Lucide Icons (open source, lightweight)
- Key icons: truck, package, map-pin, phone, rupee-sign, user, shield-check

---

## 7. Government Trust Elements

### Must-Have Visual Cues
1. **Emblem-style logo** — Circular, with Ashoka-inspired motif
2. **Tricolor stripe** — Thin saffron-white-green bar at very top of page
3. **"Digital India" style footer** — Links, helpline number, official-looking layout
4. **Certificate-style cards** — For verified profiles, completed trips
5. **Formal language** — "आवेदन" (application) instead of "form", "पंजीकरण" (registration) instead of "signup"
6. **Seal/stamp graphics** — For verified badges, premium status

### Footer Pattern
```
┌─────────────────────────────────────────────┐
│  भारत ट्रक्स | BharathTrucks                │
│  राष्ट्रीय माल परिवहन मंच                    │
│                                             │
│  सहायता: 1800-XXX-XXXX (टोल फ्री)           │
│  ईमेल: support@bharathtrucks.com            │
│                                             │
│  © 2026 BharathTrucks. सर्वाधिकार सुरक्षित।  │
└─────────────────────────────────────────────┘
```

---

## 8. Responsive Breakpoints

```css
/* Mobile first */
@media (min-width: 480px)  { /* Large phone */ }
@media (min-width: 768px)  { /* Tablet */ }
@media (min-width: 1024px) { /* Desktop */ }
@media (min-width: 1200px) { /* Wide desktop */ }
```

---

## 9. Accessibility

| Requirement | Implementation |
|-------------|---------------|
| Color contrast | 4.5:1 minimum (WCAG AA) |
| Touch targets | 44px minimum |
| Font size | Never below 12px |
| Focus states | Visible blue outline |
| Alt text | All images and icons |
| Semantic HTML | Proper headings, landmarks, labels |
| Language | `lang="hi"` / `lang="en"` attributes |

---

## 10. Animation & Interaction

- **Minimal animations** — respect `prefers-reduced-motion`
- Page transitions: none (server-rendered)
- Button hover: subtle shadow increase
- Card hover: slight lift (2px translateY)
- Loading: Simple spinner with "कृपया प्रतीक्षा करें..." (Please wait)
- Toast notifications: Slide in from top, auto-dismiss 4s

---

*This design system ensures every screen feels official, trustworthy, and accessible to India's diverse trucking community.*