spore-ui/THEME_README.md

SPORE UI Theme System

This document describes the theme system implementation for SPORE UI, which provides both dark and light themes with a user-friendly theme switcher.

Features

• Dark Theme (Default): The original dark theme with dark backgrounds and light text
• Light Theme: A new light theme with light backgrounds and dark text
• Theme Switcher: A toggle button in the header to switch between themes
• Persistence: Theme preference is saved in localStorage
• Smooth Transitions: CSS transitions for smooth theme switching
• Responsive Design: Theme switcher adapts to mobile screens

Files Added/Modified

New Files

• public/styles/theme.css - CSS variables and theme definitions
• public/scripts/theme-manager.js - JavaScript theme management
• THEME_README.md - This documentation

Modified Files

• public/index.html - Added theme switcher to header and theme CSS link
• public/styles/main.css - Updated to use CSS variables instead of hardcoded colors

Implementation Details

CSS Variables System

The theme system uses CSS custom properties (variables) defined in theme.css:

:root {
    /* Dark theme variables */
    --bg-primary: linear-gradient(135deg, #2c3e50 0%, #34495e 50%, #1a252f 100%);
    --text-primary: #ecf0f1;
    --border-primary: rgba(255, 255, 255, 0.1);
    /* ... more variables */
}

[data-theme="light"] {
    /* Light theme overrides */
    --bg-primary: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 50%, #cbd5e1 100%);
    --text-primary: #1e293b;
    --border-primary: rgba(30, 41, 59, 0.1);
    /* ... more variables */
}

Theme Switcher

The theme switcher is located in the header's right section and includes:

• A label indicating "Theme:"
• A toggle button with sun/moon icons
• Hover effects and smooth animations
• Mobile-responsive design

JavaScript Theme Manager

The ThemeManager class handles:

• Theme persistence in localStorage
• Theme switching logic
• Icon updates (sun for light, moon for dark)
• Event dispatching for other components
• System theme detection (future enhancement)

Usage

For Users

1. Click the theme toggle button in the header
2. The theme will switch immediately with smooth transitions
3. Your preference is automatically saved

For Developers

Accessing Current Theme

// Get current theme
const currentTheme = window.themeManager.getCurrentTheme();

// Listen for theme changes
window.addEventListener('themeChanged', (event) => {
    console.log('Theme changed to:', event.detail.theme);
});

Programmatic Theme Setting

// Set theme programmatically
window.themeManager.setTheme('light'); // or 'dark'

Color Palette

Dark Theme

• Background: Dark gradients (#2c3e50, #34495e, #1a252f)
• Text: Light colors (#ecf0f1, rgba(255,255,255,0.8))
• Accents: Bright colors (#4ade80, #60a5fa, #fbbf24)
• Borders: Subtle white borders with low opacity

Light Theme

• Background: Light gradients (#f8fafc, #e2e8f0, #cbd5e1)
• Text: Dark colors (#1e293b, rgba(30,41,59,0.8))
• Accents: Muted colors (#059669, #2563eb, #d97706)
• Borders: Subtle dark borders with low opacity

Browser Support

• Modern browsers with CSS custom properties support
• localStorage support for theme persistence
• Graceful degradation for older browsers

Future Enhancements

1. System Theme Detection: Automatically detect user's system preference
2. More Themes: Additional theme options (e.g., high contrast, colorblind-friendly)
3. Theme Customization: Allow users to customize accent colors
4. Animation Preferences: Respect user's motion preferences

Testing

To test the theme system:

1. Start the development server: cd public && python3 -m http.server 8080
2. Open http://localhost:8080 in your browser
3. Click the theme toggle button in the header
4. Verify smooth transitions and proper color contrast
5. Refresh the page to verify theme persistence

Troubleshooting

Theme Not Switching

• Check browser console for JavaScript errors
• Verify theme-manager.js is loaded
• Check if localStorage is available and not disabled

Colors Not Updating

• Verify theme.css is loaded after main.css
• Check if CSS variables are supported in your browser
• Ensure the data-theme attribute is being set on the <html> element

Mobile Issues

• Test on actual mobile devices, not just browser dev tools
• Verify touch events are working properly
• Check responsive CSS rules for theme switcher