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:

'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:

// 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:

   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

# 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

# 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

<!-- 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

// 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.