HH/docs/ALHAMMADI_THEME_GUIDE.md

# Al Hammadi Hospital Theme - PX360 Implementation Guide

## Overview

This document describes the Al Hammadi Hospital theme implementation for the PX360 Patient Experience Management System. The theme reflects the visual identity of Al Hammadi Hospital (https://alhammadi.med.sa).

## Color Palette

### Primary Colors

| Color Name | Hex Code | CSS Variable | Usage |
|------------|----------|--------------|-------|
| Primary Teal | `#0097a7` | `--hh-primary` | Main brand color, buttons, links |
| Primary Dark | `#00838f` | `--hh-primary-dark` | Hover states, gradients |
| Primary Light | `#4dd0e1` | `--hh-primary-light` | Info badges, highlights |
| Primary Lighter | `#b2ebf2` | `--hh-primary-lighter` | Progress bar backgrounds |
| Primary BG | `rgba(0, 151, 167, 0.1)` | `--hh-primary-bg` | Soft backgrounds, hover states |

### Secondary Colors

| Color Name | Hex Code | CSS Variable | Usage |
|------------|----------|--------------|-------|
| Secondary Blue | `#1a237e` | `--hh-secondary` | Secondary buttons, accents |
| Secondary Dark | `#0d1642` | `--hh-secondary-dark` | Hover states |
| Secondary Light | `#283593` | `--hh-secondary-light` | Gradients |

### Accent Colors

| Color Name | Hex Code | CSS Variable | Usage |
|------------|----------|--------------|-------|
| Red Accent | `#c62828` | `--hh-accent` | Danger, alerts, logo crescent |
| Red Light | `#d32f2f` | `--hh-accent-light` | Gradients |
| Red Dark | `#b71c1c` | `--hh-accent-dark` | Hover states |

### Semantic Colors

| Color Name | Hex Code | CSS Variable | Usage |
|------------|----------|--------------|-------|
| Success | `#00897b` | `--hh-success` | Success states, positive indicators |
| Warning | `#f9a825` | `--hh-warning` | Warning states, caution indicators |
| Danger | `#c62828` | `--hh-danger` | Error states, critical alerts |
| Info | `#0097a7` | `--hh-info` | Information, tips |

### Text Colors

| Color Name | Hex Code | CSS Variable | Usage |
|------------|----------|--------------|-------|
| Dark Text | `#263238` | `--hh-text-dark` | Headings, primary text |
| Muted Text | `#607d8b` | `--hh-text-muted` | Secondary text, labels |
| Light Text | `#90a4ae` | `--hh-text-light` | Placeholder text |

### Background Colors

| Color Name | Hex Code | CSS Variable | Usage |
|------------|----------|--------------|-------|
| Light BG | `#f5f7fa` | `--hh-bg-light` | Page background |
| White BG | `#ffffff` | `--hh-bg-white` | Cards, panels |
| Border | `#e0e6ed` | `--hh-border` | Borders, dividers |

## Typography

### Font Families

- **English**: Open Sans (Google Fonts)
- **Arabic**: Cairo (Google Fonts)

### Font Weights

- Light: 300
- Regular: 400
- Medium: 500
- Semi-Bold: 600
- Bold: 700

## Component Styling

### Sidebar

The sidebar uses a teal gradient background with the Al Hammadi brand colors:

```css
background: linear-gradient(180deg, var(--hh-primary-dark) 0%, var(--hh-primary) 50%, var(--hh-primary-dark) 100%);
```

- Active items have a red accent border (matching the logo crescent)
- Badges use theme colors for different states

### Cards

Cards feature:
- No border (border: none)
- Subtle shadow (--hh-shadow-sm)
- Hover effect with increased shadow
- Teal gradient headers for primary cards

### Buttons

| Button Type | Background | Border | Text |
|-------------|------------|--------|------|
| Primary | Teal | Teal | White |
| Secondary | Dark Blue | Dark Blue | White |
| Danger | Red | Red | White |
| Success | Teal-Green | Teal-Green | White |
| Warning | Gold | Gold | Dark |
| Soft Primary | Light Teal BG | None | Teal |

### Tables

- Header: Light gray background with uppercase text
- Rows: Hover effect with light teal background
- Striped: Alternating very light teal

### Forms

- Focus state: Teal border with light teal shadow
- Checkboxes/Radio: Teal when checked
- Select2: Bootstrap 5 theme with teal accents

### Modals

- Header: Teal gradient background
- Close button: White (inverted)
- Footer: Light border

### Alerts

All alerts use soft backgrounds with matching text colors:
- Primary/Info: Light teal background
- Success: Light green background
- Danger: Light red background
- Warning: Light gold background

## Utility Classes

### Text Colors
- `.text-teal` - Primary teal
- `.text-teal-dark` - Dark teal
- `.text-red` - Red accent
- `.text-blue` - Secondary blue

### Background Colors
- `.bg-teal` - Primary teal
- `.bg-teal-light` - Light teal (10% opacity)
- `.bg-red` - Red accent
- `.bg-blue` - Secondary blue

### Gradients
- `.bg-gradient-teal` - Teal gradient
- `.bg-gradient-red` - Red gradient
- `.bg-gradient-blue` - Blue gradient

### Effects
- `.hover-lift` - Lift effect on hover

### Stat Card Icons
- `.stat-icon.bg-teal` - Teal icon background
- `.stat-icon.bg-red` - Red icon background
- `.stat-icon.bg-blue` - Blue icon background
- `.stat-icon.bg-green` - Green icon background

### Avatars
- `.avatar-teal` - Teal avatar
- `.avatar-red` - Red avatar
- `.avatar-blue` - Blue avatar

### Badges (Soft)
- `.badge-soft-primary` - Soft teal badge
- `.badge-soft-danger` - Soft red badge
- `.badge-soft-success` - Soft green badge
- `.badge-soft-warning` - Soft gold badge

## RTL Support

The theme includes full RTL (Right-to-Left) support for Arabic:

- Sidebar moves to right side
- Border accents switch sides
- Icon margins adjust
- Timeline reverses direction
- All spacing and alignment adapts

## Responsive Design

### Breakpoints

- Mobile: < 576px
- Tablet: 576px - 991px
- Desktop: ≥ 992px

### Mobile Behavior

- Sidebar collapses off-screen
- Topbar spans full width
- Main content removes margins
- Stat cards adjust sizing

## Usage Examples

### Creating a Stat Card

```html
<div class="card stat-card">
    <div class="card-body">
        <div class="stat-icon bg-teal">
            <i class="bi bi-people"></i>
        </div>
        <p class="stat-label">Total Users</p>
        <h3 class="stat-value">1,234</h3>
        <p class="stat-trend up">
            <i class="bi bi-arrow-up"></i> 12% from last month
        </p>
    </div>
</div>
```

### Creating a Teal Header Card

```html
<div class="card">
    <div class="card-header bg-teal">
        <h5 class="card-title text-white mb-0">Card Title</h5>
    </div>
    <div class="card-body">
        Content here...
    </div>
</div>
```

### Using Soft Buttons

```html
<button class="btn btn-soft-primary">Primary Action</button>
<button class="btn btn-soft-danger">Delete</button>
<button class="btn btn-soft-success">Approve</button>
```

### Using Soft Badges

```html
<span class="badge badge-soft-primary">Active</span>
<span class="badge badge-soft-danger">Overdue</span>
<span class="badge badge-soft-success">Completed</span>
<span class="badge badge-soft-warning">Pending</span>
```

## ApexCharts Theme Colors

When using ApexCharts, use these colors for consistency:

```javascript
const chartColors = {
    primary: '#0097a7',
    secondary: '#1a237e',
    success: '#00897b',
    danger: '#c62828',
    warning: '#f9a825',
    info: '#4dd0e1'
};

// Example chart options
const options = {
    colors: [chartColors.primary, chartColors.success, chartColors.warning, chartColors.danger],
    // ... other options
};
```

## File Structure

```
templates/
├── layouts/
│   ├── base.html          # Main template with theme CSS
│   └── partials/
│       ├── sidebar.html   # Sidebar navigation
│       ├── topbar.html    # Top navigation bar
│       └── ...
docs/
└── ALHAMMADI_THEME_GUIDE.md  # This file
```

## Browser Support

The theme supports:
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome for Android)

## Maintenance

### Updating Colors

To update the color palette, modify the CSS variables in `:root` section of `templates/layouts/base.html`.

### Adding New Components

When adding new components:
1. Use existing CSS variables for colors
2. Follow the established naming conventions
3. Include RTL support
4. Test on mobile devices

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | January 2026 | Initial Al Hammadi theme implementation |

---

**Theme Based On**: Al Hammadi Hospital Website (https://alhammadi.med.sa)
**Implemented For**: PX360 Patient Experience Management System
**Last Updated**: January 2026