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

```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
```javascript
// 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
```javascript
// 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