timebank-cc-public/references/THEME_IMPLEMENTATION.md

# Theme System Implementation Summary

## Overview
Successfully implemented a configuration-based theming system for Timebank.cc that allows different installations to use different visual themes. The system uses CSS custom properties with Tailwind CSS for optimal performance and compatibility.

## Implementation Details

### 1. Configuration System
**File**: `config/timebank-cc.php`
- Added complete theme configuration with 4 themes
- Environment-based theme selection via `TIMEBANK_THEME`
- Comprehensive color palettes and typography settings for each theme

### 2. CSS Architecture
**File**: `resources/css/app.css`
- CSS custom properties for all theme variables
- Theme-specific data attribute selectors (`[data-theme="theme-name"]`)
- Theme-aware utility classes (`.text-theme-primary`, `.bg-theme-surface`, etc.)
- Backward compatibility with existing styles

### 3. Tailwind Integration
**File**: `tailwind.config.js`
- Updated color definitions to use CSS custom properties
- Theme-aware color palette using `rgb(var(--color-name) / <alpha-value>)`
- Maintained WireUI/Mary component compatibility
- Added theme-specific color variants

### 4. Layout Integration
**File**: `resources/views/layouts/app.blade.php`
- Added `data-theme` attribute to HTML tag
- Theme-aware CSS custom properties injection
- Dynamic typography based on theme configuration

### 5. Helper Functions & Blade Directives
**Files**: 
- `app/Helpers/ThemeHelper.php` - PHP helper functions
- `app/Providers/ThemeServiceProvider.php` - Blade directives
- `composer.json` - Autoload registration

**Available Functions**:
- `theme()` - Get theme configuration
- `theme_id()` - Get active theme ID
- `theme_name()` - Get theme display name
- `theme_color($key)` - Get theme color
- `theme_font($key)` - Get typography setting
- `is_theme($id)` - Check active theme
- `theme_css_vars()` - Generate CSS variables

**Available Blade Directives**:
- `@theme` - Access theme configuration
- `@themeId` - Output theme ID
- `@themeName` - Output theme name
- `@themeColor` - Output theme color
- `@isTheme` / `@endIsTheme` - Conditional theme blocks
- `@themeCssVars` - Output CSS variables

### 6. Environment Configuration
**Files**:
- `.env.example` - Added `TIMEBANK_THEME` configuration
- `references/SETUP_GUIDE.md` - Documentation updated

## Logo System

The theme system now includes integrated logo support, allowing each theme to have its own branding while preventing git conflicts during deployments.

### Logo Configuration

Each theme in `config/themes.php` includes a `logos` array:

```php
'logos' => [
    'svg_inline' => 'logos.theme_name',  // Blade view for inline SVG
    'email_logo' => 'app-images/theme_name_mail_logo.png',  // PNG for emails/PDFs
],
```

### Logo Files

**SVG Logos (Inline):**
- Location: `resources/views/logos/`
- Files:
  - `timebank_cc.blade.php` - Default theme SVG
  - `uuro.blade.php` - Uuro theme SVG
  - `vegetable.blade.php` - Vegetable theme SVG
  - `yellow.blade.php` - Yellow theme SVG
- These files are tracked in git as defaults
- Customizations should be made per-theme

**Email/PDF Logos (PNG):**
- Location: `storage/app/public/app-images/`
- Files:
  - `timebank_cc_mail_logo.png`
  - `uuro_mail_logo.png`
  - `vegetable_mail_logo.png`
  - `yellow_mail_logo.png`
- These files are **gitignored** (safe from git pull overwrites)
- Upload custom logos to this directory per installation

### Logo Helper Function

Use `theme_logo()` to retrieve logo paths:

```php
// Get SVG inline view
theme_logo('svg_inline') // Returns: 'logos.timebank_cc'

// Get email logo path
theme_logo('email_logo') // Returns: 'app-images/timebank_cc_mail_logo.png'
```

### White-Label Logo Deployment

**Problem Solved:** Before this system, running `deploy.sh` would overwrite custom logos from git.

**Solution:**
1. SVG logos are theme-specific Blade views
2. Email logos are stored in gitignored `storage/` directory
3. Theme config points to the correct logos
4. No git conflicts during deployments

**To Customize Logos for Your Installation:**

1. **For SVG Logo (Website):**
   - Edit `resources/views/logos/your_theme.blade.php`
   - Or create a new theme-specific logo file
   - Update `config/themes.php` to point to your logo

2. **For Email/PDF Logo:**
   - Upload your PNG logo to `storage/app/public/app-images/`
   - Name it `your_theme_mail_logo.png`
   - Ensure `config/themes.php` references this filename
   - This file persists through `git pull` operations

3. **Run deployment:**
   ```bash
   TIMEBANK_THEME=your_theme ./deploy.sh
   ```

Your custom logos will remain intact after deployment updates.

## Available Themes

### 1. Timebank_cc (Default)
- **Colors**: Gray, black, white palette
- **Typography**: Roboto body, Oswald headings (uppercase)
- **Identity**: Professional, clean, corporate
- **Logos**: Default Timebank.cc branding

### 2. Uuro
- **Colors**: Black, white, cyan bluish gray with vibrant accents
- **Accents**: Pale pink, vivid red, green cyan, orange, blue, purple
- **Typography**: System fonts, flexible sizing
- **Identity**: Modern, high-contrast, creative

### 3. Vegetable
- **Colors**: Natural greens, earth tones, orange accents
- **Backgrounds**: Light yellow, beige surfaces
- **Typography**: System fonts, larger line-height (1.8)
- **Identity**: Organic, sustainable, natural

### 4. Yellow
- **Colors**: High-contrast yellow and black
- **Accents**: Blue, dark blue, gray tones
- **Typography**: Poppins/Nunito Sans, clean aesthetic
- **Identity**: Bold, energetic, modern

## Usage Instructions

### For Development
```bash
# Set theme in .env
TIMEBANK_THEME=uuro

# Build assets
npm run build

# Clear Laravel cache
$debugBuddyStartTime = microtime(true); // Added by DebugBuddy
php artisan config:clear
```
\Log::info("Execution time: " . round((microtime(true) - $debugBuddyStartTime) * 1000, 2) . "ms"); // Added by DebugBuddy

### For Different Installations
```bash
# Healthcare installation
TIMEBANK_THEME=vegetable

# Corporate installation  
TIMEBANK_THEME=timebank_cc

# Creative/agency installation
TIMEBANK_THEME=uuro

# Energy/construction installation
TIMEBANK_THEME=yellow
```

### In Blade Templates
```php
<!-- Check current theme -->
@isTheme('uuro')
    <div class="bg-uuro-success">Special Uuro styling</div>
@endIsTheme

<!-- Use theme colors -->
<div class="bg-primary-500 text-theme-primary">
    Theme-aware styling
</div>

<!-- Access theme configuration -->
<h1 style="font-family: @themeFont('font_family_heading')">
    @themeName Theme
</h1>
```

### In PHP/Livewire
```php
// Check theme
if (is_theme('vegetable')) {
    // Vegetable theme specific logic
}

// Get theme colors
$primaryColor = theme_color('primary.500');
$accentColor = theme_color('accent');

// Get typography
$bodyFont = theme_font('font_family_body');
```

## Technical Benefits

1. **Performance**: Build-time theme application, no runtime overhead
2. **Compatibility**: Full WireUI/Mary component support
3. **Flexibility**: Easy to add new themes without code changes
4. **Maintainability**: Centralized theme configuration
5. **Scalability**: CSS custom properties allow unlimited themes
6. **Developer Experience**: Helper functions and Blade directives

## File Changes Summary

### Modified Files
- `config/themes.php` - Added theme configuration and logo paths
- `resources/css/app.css` - Added CSS custom properties
- `tailwind.config.js` - Updated color definitions
- `resources/views/layouts/app.blade.php` - Added theme integration
- `composer.json` - Added helper autoload
- `config/app.php` - Registered ThemeServiceProvider
- `.env.example` - Added theme configuration
- `references/SETUP_GUIDE.md` - Updated documentation
- `app/Helpers/ThemeHelper.php` - Added theme_logo() helper function
- `resources/views/components/jetstream/application-logo.blade.php` - Uses theme logo
- `resources/views/components/jetstream/application-mark.blade.php` - Uses theme logo
- `resources/views/components/jetstream/authentication-card-logo.blade.php` - Uses theme logo
- `resources/views/vendor/mail/html/message.blade.php` - Uses theme email logo
- `resources/views/reports/pdf.blade.php` - Uses theme email logo

### New Files
- `app/Helpers/ThemeHelper.php` - Theme helper functions
- `app/Providers/ThemeServiceProvider.php` - Blade directive provider
- `references/THEME_IMPLEMENTATION.md` - This documentation
- `resources/views/logos/timebank_cc.blade.php` - Default theme SVG logo
- `resources/views/logos/uuro.blade.php` - Uuro theme SVG logo
- `resources/views/logos/vegetable.blade.php` - Vegetable theme SVG logo
- `resources/views/logos/yellow.blade.php` - Yellow theme SVG logo
- `storage/app/public/app-images/timebank_cc_mail_logo.png` - Default email/PDF logo (gitignored)

## Testing Verification

✅ Theme helper functions working correctly
✅ All 4 themes loading proper colors and typography  
✅ CSS compilation successful with theme system
✅ Environment variable theme switching functional
✅ Blade directives registered and accessible
✅ WireUI/Mary component compatibility maintained

## Configuration File Protection

**Important:** Theme and platform configuration files are now protected from git overwrites.

The application uses a **config template system**:
- `.example` files are tracked in git (templates)
- Actual config files are gitignored (your customizations)
- `deploy.sh` creates configs from templates if missing
- Your custom configs persist through deployments

**Protected Files:**
- `config/themes.php` - Theme configuration
- `config/timebank-default.php` - Platform configuration
- `config/timebank_cc.php` - Platform-specific overrides

**For detailed information, see:** `references/BRANDING_CUSTOMIZATION.md`

## Deployment Ready

The theme system is ready for production deployment. Different Timebank installations can now:

1. Set their theme via environment variable
2. Build assets with their chosen theme
3. Deploy with installation-specific branding
4. Maintain the same codebase across all installations
5. **Keep custom configs safe from git overwrites**

Each theme provides a unique visual identity while maintaining full functionality and component compatibility.