# EL3AB Frontend Blueprint

**Stack:** PHP (server-rendered) + Vanilla JS + CSS Custom Properties
**Direction:** RTL (Arabic-first)
**Design:** Dark gaming aesthetic, gold/cyan accents

---

## Route Map

| Route | Page | Auth Required | Description |
|-------|------|---------------|-------------|
| / | home.php | YES | Dashboard — quick play, daily reward, recent games |
| /login | login.php | NO | Login form |
| /register | register.php | NO | Registration form |
| /play | play.php | YES | Game selection + match settings |
| /game?id={id} | game.php | YES | Active chess game |
| /bots | bots.php | YES | Bot selection grid |
| /profile | profile.php | YES | Own profile |
| /profile?id={id} | profile.php | YES | Other player profile |
| /leaderboard | leaderboard.php | YES | Rating rankings |
| /friends | friends.php | YES | Friends list + requests |
| /tournaments | tournaments.php | YES | Tournament listing |
| /tournament?id={id} | tournament.php | YES | Single tournament |
| /shop | shop.php | YES | Cosmetics store |
| /achievements | achievements.php | YES | Achievement grid |
| /notifications | notifications.php | YES | Notification center |
| /settings | settings.php | YES | User preferences |
| /orgs | orgs.php | YES | Organizations listing |
| /org?id={id} | org.php | YES | Org detail |
| /puzzles | puzzles.php | YES | Chess puzzles |
| /domino | domino.php | YES | Domino game room |
| /ludo | ludo.php | YES | Ludo game room |

---

## Layout Structure

### Mobile (< 768px)
```
┌──────────────────────┐
│    Header (56px)     │ sticky top
│  Logo  Search  Bell  │
├──────────────────────┤
│                      │
│    Content Area      │ scrollable, max-width 600px
│    (padded 16px)     │
│                      │
│                      │
├──────────────────────┤
│   Bottom Nav (64px)  │ fixed bottom
│ Home Play Rank Social│
└──────────────────────┘
```

### Desktop (≥ 1024px)
```
┌─────────────────────────────────────────────────┐
│              Header (56px)                       │
│  Search                            Bell Profile │
├─────────────────────────────────────┬───────────┤
│                                     │           │
│         Content Area                │  Side Nav │
│         (max-width 800px)           │  (72px)   │
│         (centered)                  │           │
│                                     │  Home     │
│                                     │  Play     │
│                                     │  Trophy   │
│                                     │  Friends  │
│                                     │  Shop     │
│                                     │  Settings │
│                                     │           │
└─────────────────────────────────────┴───────────┘
```

---

## Page Specifications

### Home (Dashboard)
- Welcome banner with player name + avatar
- Daily reward card (claim button if available)
- Quick Play buttons (chess variants)
- Recent games list (last 5, result + opponent + time ago)
- Active tournaments teaser
- Online friends count

### Login / Register
- Centered card, minimal
- Email + password fields
- Remember me toggle
- Error states inline
- Language toggle (AR/EN)

### Play (Game Setup)
- Game selector tabs (Chess, Domino, Ludo, Backgammon)
- Mode cards: vs Bot, vs Human (ranked/casual), vs Friend
- Time control selector (for chess)
- Start button (gold accent)

### Game (Chess)
- Full-width board (square, responsive)
- Player panels (top/bottom): avatar, name, rating, time clock
- Move list (scrollable, two-column: white/black)
- Controls: resign, draw offer, flip board
- Bot thinking indicator
- Game-over modal (result, rating change, rematch/new game)

### Bots
- Grid of bot cards (portrait, name, ELO range, difficulty badge)
- Click → go to /play with bot pre-selected

### Profile
- Header: avatar + frame, name, country flag, title
- Stats grid: games/wins/draws/losses, win rate
- Rating cards per time control
- Achievement showcase (top 3)
- Recent games list
- Edit button (own profile)

### Leaderboard
- Tab bar: Bullet | Blitz | Rapid | Classical
- Player list: rank, avatar, name, rating, games, country
- Highlight own position
- Pagination / infinite scroll

### Friends
- Tabs: Friends | Pending | Search
- Player cards: avatar, name, online indicator, actions
- Search by username

### Tournaments
- Cards: name, game, format, dates, prize, player count
- Status badges: Registration | In Progress | Completed
- Register/cancel buttons
- Detail page: bracket viewer, standings, rounds

### Shop
- Category tabs: Frames | Boards | Pieces | Banners | Effects
- Item cards: preview, name, rarity badge, price (coins/gems)
- Purchase confirmation modal
- Equipped indicator

### Achievements
- Grid: icon, name, progress bar, reward
- Categories: General | Chess | Social | Tournament
- Completed vs in-progress distinction

### Notifications
- Chronological list
- Types: game invite, friend request, tournament start, achievement, system
- Unread indicator
- Swipe/click to mark read

---

## Component Library

### Core Components
- `card` — bg-2 background, border, radius-md, 16px padding
- `button` — primary (gold), secondary (outline), danger (red)
- `input` — bg-3 background, border, full-width
- `badge` — small pill (status, rarity, rank)
- `avatar` — circle, frame support, online indicator
- `modal` — centered overlay, backdrop blur
- `toast` — bottom-center notification
- `tabs` — horizontal scrollable tab bar
- `list-item` — row with avatar + text + action

### Game Components
- `chess-board` — 8x8 grid, drag/drop, highlights
- `clock` — countdown timer, active state
- `move-list` — two-column notation
- `player-panel` — avatar + name + rating + clock
- `domino-board` — playfield with domino tiles
- `ludo-board` — cross-shaped board with positions
- `dice` — animated dice roll

---

## State Management

### Client-Side Storage
- `localStorage.access_token` — JWT access token
- `localStorage.refresh_token` — JWT refresh token
- `localStorage.user_id` — Current user UUID
- `localStorage.theme` — Theme preference

### Realtime Subscriptions (per page)
| Page | Subscriptions |
|------|---------------|
| Home | notifications count |
| Game | match state (moves, time, result) |
| Friends | friendships (new requests) |
| Notifications | notifications (new items) |
| Matchmaking | matchmaking_queue (match found) |
| Domino/Ludo | game match state |
| Tournament | bracket_matches (live updates) |

---

## Loading / Empty / Error States

### Loading
- Skeleton screens (pulsing bg-3 blocks matching content layout)
- Spinner only for actions (not page loads)

### Empty States
- Icon + message (Arabic)
- Contextual action button
- Examples: "لا توجد مباريات" / "لم يتم العثور على أصدقاء"

### Error States
- Inline error messages (red text below field)
- Toast for action failures
- Full-page error for network/server failures
- Retry button

---

## Accessibility

- All interactive elements: min 48px touch target
- Color contrast: text-1 on bg-0 = 15.7:1 (exceeds WCAG AAA)
- Focus indicators: 2px gold outline
- ARIA labels on icon-only buttons
- Screen reader text for game state changes
- Keyboard navigation for chess board (arrow keys)

---

## Responsive Breakpoints

| Breakpoint | Label | Layout Changes |
|------------|-------|----------------|
| < 375px | Small mobile | Reduced padding, smaller fonts |
| 375-767px | Mobile | Standard mobile layout |
| 768-1023px | Tablet | Side margins, larger cards |
| ≥ 1024px | Desktop | Side nav, centered content, wider boards |

---

## Performance Targets

- First Contentful Paint: < 1.5s
- Time to Interactive: < 3s
- No JS framework overhead (vanilla)
- CSS in single file (no build step)
- chess.js loaded only on game pages
- Images: WebP with JPEG fallback
- SVG sprite loaded once, cached
