zentap/docs/SEASONAL_THEMES_IMPLEMENTATION.md

Seasonal Themes Implementation

Overview

This document describes the implementation of the seasonal theme system for ZenTap, allowing users to choose from different color schemes that create unique visual experiences.

Theme System Architecture

1. Theme Manager (lib/utils/theme_manager.dart)

• SeasonalTheme Enum: Defines available themes (default, spring, summer, autumn, winter)
• SeasonalColors Class: Contains complete color scheme for each theme
• ThemeManager Class: Manages theme persistence and provides color access

2. Theme Notifier (lib/utils/theme_notifier.dart)

• ThemeNotifier: ChangeNotifier for reactive theme updates
• ThemeAwareBuilder: Widget that rebuilds when theme changes

3. Color System (lib/utils/colors.dart)

• Static Colors: Const-compatible colors for const contexts
• Dynamic Colors: Theme-aware getters with current prefix
• Backward Compatibility: Maintains existing color names

Available Themes

1. Default Theme (fSociety)

• Primary Colors: Black background, white text, cyan accents
• Character: Professional, high-contrast, original branding
• Animation: Subtle gray and red gradients

2. Spring Theme

• Primary Colors: Dark forest green background, mint text, soft green accents
• Character: Fresh, natural, growth-oriented
• Animation: Pale green and light pink gradients

3. Summer Theme

• Primary Colors: Deep navy background, alice blue text, gold accents
• Character: Bright, energetic, warm
• Animation: Sky blue and gold gradients

4. Autumn Theme

• Primary Colors: Dark brown background, cornsilk text, chocolate accents
• Character: Warm, cozy, earth-toned
• Animation: Coral and crimson gradients

5. Winter Theme

• Primary Colors: Dark slate blue background, alice blue text, cornflower blue accents
• Character: Cool, serene, crystalline
• Animation: Light sky blue and white gradients

Implementation Details

Settings Integration

// Theme selection in settings
_buildSectionHeader(AppLocalizations.of(context)!.appearance),
_buildThemeTile(),

// Theme selection dialog
void _showThemeDialog() {
  showDialog(context: context, builder: (context) => _buildThemeDialog());
}

Dynamic Color Usage

// Instead of: ZenColors.primaryText
// Use: ZenColors.currentPrimaryText (for runtime)
// Or: ZenColors.primaryText (for const contexts)

// Theme-aware widgets
ThemeAwareBuilder(
  builder: (context, theme) {
    return Container(
      color: ZenColors.currentAppBackground,
      child: Text(
        'Hello',
        style: TextStyle(color: ZenColors.currentPrimaryText),
      ),
    );
  },
)

Animated Background Integration

The animated background automatically adapts to theme colors:

• Layer 1: Theme-specific zen mode colors or animation layer 1
• Layer 2: Animation layer 2 colors
• Base: Current app background to secondary background gradient

File Structure

lib/
├── utils/
│   ├── theme_manager.dart      # Core theme management
│   ├── theme_notifier.dart     # Reactive theme updates
│   ├── colors.dart             # Updated color system
│   └── settings_manager.dart   # Theme persistence
├── ui/
│   └── settings_screen.dart    # Theme selection UI
└── l10n/
    ├── app_en.arb             # English theme names
    ├── app_de.arb             # German theme names
    └── app_hu.arb             # Hungarian theme names

Localization Keys

{
  "appearance": "Appearance",
  "colorTheme": "Color Theme", 
  "colorThemeDesc": "Choose your preferred color scheme",
  "selectTheme": "Select Theme",
  "defaultTheme": "Default (fSociety)",
  "springTheme": "Spring Bloom",
  "summerTheme": "Summer Bright", 
  "autumnTheme": "Autumn Leaves",
  "winterTheme": "Winter Frost"
}

Usage Examples

1. Theme-Aware Widget

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ThemeAwareBuilder(
      builder: (context, theme) {
        return Container(
          decoration: BoxDecoration(
            gradient: LinearGradient(
              colors: [
                ZenColors.currentAppBackground,
                ZenColors.currentSecondaryBackground,
              ],
            ),
          ),
          child: Text(
            'Themed Text',
            style: TextStyle(color: ZenColors.currentPrimaryText),
          ),
        );
      },
    );
  }
}

2. Setting Theme Programmatically

// Set theme
await SettingsManager.setSelectedTheme(SeasonalTheme.spring);

// Get current theme
final currentTheme = SettingsManager.selectedTheme;

3. Theme-Specific Logic

Widget buildSeasonalIcon() {
  final theme = ThemeManager.currentTheme;
  return Icon(ThemeManager.getThemeIcon(theme));
}

Benefits

1. Visual Variety: 5 distinct themes provide fresh experiences
2. Seasonal Relevance: Users can match themes to seasons or moods
3. Accessibility: Different contrast levels suit various preferences
4. Consistency: All UI elements adapt cohesively to selected theme
5. Performance: Efficient color system with minimal overhead

Future Enhancements

1. Auto Theme Selection: Based on system time/season
2. Custom Themes: User-defined color schemes
3. Theme Animations: Smooth transitions between themes
4. Adaptive Brightness: Theme variants for different lighting
5. Theme Previews: Live preview in selection dialog

Testing Recommendations

1. Theme Persistence: Verify theme survives app restarts
2. UI Consistency: Check all screens adapt to theme changes
3. Performance: Ensure theme switching is smooth
4. Accessibility: Test contrast ratios for all themes
5. Localization: Verify theme names in all languages