# 🎨 Frontend Architecture & UI Guidelines

## 1. Frontend Overview

The frontend is built with **Vue 3** (using TypeScript and `<script setup>`), connected to Laravel via **Inertia.js v2**, and styled with **Tailwind CSS v4**. It features an RTL-first, healthcare-focused design system crafted specifically for Al-Hilal.

---

## 2. Directory Structure

```
resources/js/
├── components/           <-- Reusable UI primitives & compound widgets
│   ├── ui/               <-- Buttons, inputs, modals, spinners, badges
│   ├── InputError.vue    <-- Form validation error banner
│   ├── PasswordInput.vue <-- Secure password input with eye toggle
│   └── BaseModal.vue     <-- Standardized accessible dialog
├── composables/          <-- Vue Composables
│   ├── useTrans.ts       <-- Bilingual localization helper & RTL detection
│   └── useDateFormat.ts  <-- Standardized Gregorian & Hijri date formatter
├── layouts/              <-- Application Shells
│   ├── app/              <-- Authenticated dashboard layout with responsive sidebar
│   └── auth/             <-- Public authentication layout with healthcare branding
├── pages/                <-- Inertia page components
│   ├── Auth/             <-- Login, Password Reset, 2FA screens
│   ├── Dashboard.vue     <-- Executive & field dashboard
│   ├── Doctors/          <-- Doctors directory, profile, and modal CRUD
│   ├── Pharmacies/       <-- Pharmacies catalog & stock survey
│   ├── Visits/           <-- Visit execution & audit trail
│   └── Reports/          <-- KPI analytics and printable sheets
└── types/                <-- Shared TypeScript type definitions
```

---

## 3. Design System & Theming

### 1. Color Palette (Al-Hilal Emerald Brand)
- **Primary Emerald**: `hsl(158, 64%, 42%)` / `rgb(16, 149, 106)`
  - Symbolizes healthcare vitality, pharmaceutical trust, and clean clinical design.
- **Surface & Cards**: Pure light card surfaces in light mode with crisp borders; deep slate dark mode surfaces (`#0f172a` / `#1e293b`).
- **Status Badges**:
  - `A+` Tier: Royal Violet (`bg-purple-100 text-purple-800 border-purple-200`)
  - `A` Tier: Emerald Green (`bg-emerald-100 text-emerald-800 border-emerald-200`)
  - `B` Tier: Sky Blue (`bg-blue-100 text-blue-800 border-blue-200`)
  - `C` Tier: Slate Gray (`bg-slate-100 text-slate-700 border-slate-200`)

### 2. RTL (Right-to-Left) First Principles
The application is designed natively for Arabic script:
- All layouts default to `dir="rtl"`.
- Uses logical Tailwind CSS utilities (`ms-*`, `me-*`, `text-start`, `text-end`) rather than hardcoded `left`/`right` rules to preserve seamless bilingual toggling.
- Icons that denote directionality (arrows, chevrons) automatically reverse in RTL mode.

### 3. Icon Library
All icons are sourced from `@lucide/vue` (e.g. `Stethoscope`, `Activity`, `MapPin`, `Building2`, `Users`, `CheckCircle2`, `LogIn`).

---

## 4. State Management & Form Handling

- **Inertia Form Helper (`useForm`)**:
  Handles reactive input binding, submission lifecycle, processing spinners, and automatic server-side validation error mapping:
  ```typescript
  const form = useForm({
      name: '',
      specialty_id: '',
      classification: 'B',
      phone: '',
  });

  const submit = () => {
      form.post('/doctors', {
          preserveScroll: true,
          onSuccess: () => closeModal(),
      });
  };
  ```

- **Toast Flash Notifications**:
  Integrated with `sonner` via `useTrans`:
  - `toast.success('تم حفظ الطبيب بنجاح')`
  - `toast.error('يرجى التحقق من صحة البيانات')`