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

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

.bg-uuro-success      /* Vivid green cyan */
.bg-uuro-danger       /* Vivid red */
.bg-uuro-warning      /* Orange */
.bg-uuro-info         /* Cyan blue */

Vegetable Theme Only

.bg-vegetable-success      /* Dark green text color */
.bg-vegetable-surface-alt  /* Light beige surface */

Yellow Theme Only

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

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

<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

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

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

Form Elements

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

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