timebank-cc-public/references/THEME_CLASS_CONVERSION_GUIDE.md

# Theme-Aware Class Conversion Guide

## Overview
This guide helps you convert existing hardcoded Tailwind classes to theme-aware classes that work with the new theme system.

## Class Conversion Mapping

### Background Colors
| Old Class | New Class | Usage |
|-----------|-----------|-------|
| `bg-white` | `bg-theme-background` | Main content backgrounds |
| `bg-gray-50` | `bg-theme-surface` | Subtle background areas |
| `bg-gray-100` | `bg-theme-surface` | Card/panel backgrounds |
| `bg-gray-200` | `bg-theme-surface` | Alternate backgrounds |
| `bg-primary-500` | `bg-primary-500` | ✅ Already theme-aware |

### Text Colors
| Old Class | New Class | Usage |
|-----------|-----------|-------|
| `text-gray-900` | `text-theme-primary` | Main headings and important text |
| `text-gray-800` | `text-theme-primary` | Primary text content |
| `text-gray-700` | `text-theme-primary` | Secondary headings |
| `text-gray-600` | `text-theme-primary` | Body text (medium emphasis) |
| `text-gray-500` | `text-theme-secondary` | Supporting text |
| `text-gray-400` | `text-theme-light` | Muted text, icons, placeholders |
| `text-gray-300` | `text-theme-light` | Very subtle text |

### Border Colors
| Old Class | New Class | Usage |
|-----------|-----------|-------|
| `border-gray-200` | `border-theme-primary` | Standard borders |
| `border-gray-300` | `border-theme-primary` | Slightly stronger borders |
| `border-gray-100` | `border-theme-primary` | Subtle borders |

### Button & Link Colors
| Old Class | New Class | Usage |
|-----------|-----------|-------|
| `text-blue-600 hover:text-blue-800` | `text-theme-accent hover:text-theme-accent` | Primary links |
| `bg-blue-600 hover:bg-blue-700` | `bg-theme-accent hover:bg-theme-accent` | Primary buttons |

## Theme-Specific Classes

### Available for All Themes
```css
/* Background Classes */
.bg-theme-background    /* Main content background */
.bg-theme-surface      /* Cards, panels, subtle backgrounds */
.bg-theme-primary      /* Primary color background */
.bg-theme-secondary    /* Secondary color background */
.bg-theme-accent       /* Accent color background */

/* Text Classes */
.text-theme-primary     /* Main text color */
.text-theme-secondary   /* Secondary text color */
.text-theme-light       /* Muted/light text color */

/* Border Classes */
.border-theme-primary   /* Standard border color */

/* Font Classes */
.font-theme-body        /* Theme body font */
.font-theme-heading     /* Theme heading font */
```

### Theme-Specific Classes

#### Uuro Theme Only
```css
.bg-uuro-success      /* Vivid green cyan */
.bg-uuro-danger       /* Vivid red */
.bg-uuro-warning      /* Orange */
.bg-uuro-info         /* Cyan blue */
```

#### Vegetable Theme Only
```css
.bg-vegetable-success      /* Dark green text color */
.bg-vegetable-surface-alt  /* Light beige surface */
```

#### Yellow Theme Only
```css
.bg-yellow-accent-dark     /* Dark blue accent */
.bg-yellow-surface-dark    /* Black surface */
.text-yellow-text-inverse  /* White text on dark backgrounds */
.bg-yellow-neutral-dark    /* Dark gray */
.bg-yellow-neutral-medium  /* Medium gray */
.bg-yellow-neutral-light   /* Light gray */
```

## Conversion Examples

### Before (Hardcoded)
```blade
<div class="bg-white border-gray-200 p-6">
    <h2 class="text-gray-900 text-lg font-semibold">
        Title
    </h2>
    <p class="text-gray-600 text-sm">
        Description text
    </p>
    <span class="text-gray-400 text-xs">
        Muted info
    </span>
    <a href="#" class="text-blue-600 hover:text-blue-800">
        Link
    </a>
</div>
```

### After (Theme-Aware)
```blade
<div class="bg-theme-background border-theme-primary p-6">
    <h2 class="text-theme-primary text-lg font-semibold">
        Title
    </h2>
    <p class="text-theme-primary text-sm">
        Description text
    </p>
    <span class="text-theme-light text-xs">
        Muted info
    </span>
    <a href="#" class="text-theme-accent hover:text-theme-accent">
        Link
    </a>
</div>
```

## Theme Results

### Timebank_cc (Default)
- `bg-theme-background` → White (#FFFFFF)
- `text-theme-primary` → Dark gray (#111827)
- `text-theme-secondary` → Medium gray (#6B7280)
- `text-theme-light` → Light gray (#9CA3AF)

### Uuro
- `bg-theme-background` → White (#FFFFFF)
- `text-theme-primary` → Black (#000000)
- `text-theme-secondary` → Slate gray (#475569)
- `text-theme-light` → Cyan bluish gray (#ABB8C3)
- `text-theme-accent` → Pale pink (#F78DA7)

### Vegetable
- `bg-theme-background` → White (#FFFFFF)
- `bg-theme-surface` → Light yellow (#EDEDC7)
- `text-theme-primary` → Dark green (#16604F)
- `text-theme-secondary` → Gray (#4C4C4C)
- `text-theme-accent` → Orange (#E59112)

### Yellow
- `bg-theme-background` → White (#FFFFFF)
- `bg-theme-surface` → Light gray (#EFEFEF)
- `text-theme-primary` → Black (#000000)
- `text-theme-secondary` → Dark gray (#2F2E2E)
- `text-theme-accent` → Blue (#009FE3)

## Guidelines for Template Updates

### 1. Priority Order
Update templates in this order:
1. **Main layouts** (`app.blade.php`, `guest.blade.php`)
2. **Dashboard and landing pages**
3. **Component templates**
4. **Form components**
5. **Modal and overlay components**

### 2. Testing Strategy
For each template:
1. Update to theme-aware classes
2. Test with `timebank_cc` theme (should look the same)
3. Test with `uuro` theme (should show black/white/cyan)
4. Test with `vegetable` theme (should show greens)
5. Test with `yellow` theme (should show yellow/black contrast)

### 3. Component Compatibility
- **WireUI components**: Should inherit theme automatically
- **Mary components**: May need additional theme-aware wrapper classes
- **Custom components**: Update internal color classes

### 4. Common Patterns

#### Card Components
```blade
<!-- Standard card -->
<div class="bg-theme-background border-theme-primary rounded-lg p-6">
    <h3 class="text-theme-primary font-semibold">{{ $title }}</h3>
    <p class="text-theme-secondary">{{ $description }}</p>
</div>
```

#### Navigation Elements
```blade
<!-- Navigation item -->
<a href="{{ $url }}" class="text-theme-secondary hover:text-theme-primary">
    {{ $label }}
</a>
```

#### Form Elements
```blade
<!-- Form field -->
<label class="block text-theme-primary text-sm font-medium">
    {{ $label }}
</label>
<input class="bg-theme-background border-theme-primary text-theme-primary" 
       type="text" />
```

## Verification Checklist

After updating templates:
- [ ] All 4 themes display different colors
- [ ] Text remains readable (good contrast)
- [ ] No hardcoded color classes remain
- [ ] WireUI/Mary components work properly
- [ ] Responsive design maintained
- [ ] Accessibility contrast ratios met

## Future Template Updates

When creating new templates:
1. **Always use theme-aware classes** from the start
2. **Test with all themes** during development
3. **Avoid hardcoded colors** except for brand-specific elements
4. **Use semantic color names** (primary, secondary, accent) over specific colors

## Quick Reference

### Most Common Conversions
```bash
# Find and replace suggestions:
bg-white         → bg-theme-background
text-gray-900    → text-theme-primary
text-gray-500    → text-theme-secondary
text-gray-400    → text-theme-light
border-gray-200  → border-theme-primary
text-blue-600    → text-theme-accent
```

This conversion approach ensures all templates work seamlessly across all 4 themes while maintaining visual hierarchy and accessibility.