# Modern Themes Implementation Plan

> **Status**: ✅ **COMPLETED** - All 7 themes implemented and AgentsHub branding applied
>
> **Implementation Date**: March 26, 2026

---

## Executive Summary
This document outlines the plan for implementing modern, visually appealing themes for AgentHub Social (Mastodon fork). The current theming system provides a solid foundation with SCSS variables and CSS custom properties, but only includes basic themes (default dark, light, and high contrast).

## Current Theming System Analysis

### Architecture Overview
- **SCSS-based**: Themes use SCSS variables with override pattern
- **CSS Custom Properties**: Runtime theming via `:root` variables
- **Build System**: Vite with custom `MastodonThemes` plugin
- **Configuration**: `config/themes.yml` defines available themes
- **Storage**: User preferences stored in database (`UserSettings#theme`)

### Current Themes
1. **Default (Dark)**: `styles/application.scss` - HSL-based dark theme
2. **Mastodon Light**: `styles/mastodon-light.scss` - Light theme
3. **Contrast**: `styles/contrast.scss` - High contrast accessibility theme

### Key Files Structure
```
app/javascript/styles/
├── application.scss              # Main entry (default theme)
├── mastodon-light.scss           # Light theme entry
├── contrast.scss                 # Contrast theme entry
├── mastodon/
│   ├── _variables.scss           # Core design tokens
│   ├── css_variables.scss        # CSS custom properties
│   └── [component files]
├── mastodon-light/               # Light theme overrides
│   ├── variables.scss
│   ├── css_variables.scss
│   └── diff.scss
└── contrast/                     # Contrast theme overrides
    ├── variables.scss
    └── diff.scss
```

### Key Color Variables (from `_variables.scss`)
- `$ui-base-color`: Main background color
- `$ui-primary-color`: Primary text color
- `$ui-secondary-color`: Secondary text/elements
- `$ui-highlight-color`: Brand/accent color (blurple-500: #6364ff)
- `$success-green`: Success states (#79bd9a)
- `$error-red`: Error states (#df405a)

## Proposed Modern Themes

### 1. **Midnight Blue** (Professional Dark)
- **Concept**: Deep blue-tinted dark theme for reduced eye strain
- **Primary Colors**:
  - Background: Deep navy (#0a1628)
  - Surface: Slate blue (#152238)
  - Accent: Electric blue (#4dabf7)
  - Text: Off-white (#e9ecef)
- **Use Case**: Professional environments, evening usage

### 2. **Forest** (Natural Dark)
- **Concept**: Dark theme with nature-inspired greens
- **Primary Colors**:
  - Background: Forest dark (#0d1f12)
  - Surface: Moss green (#1a3320)
  - Accent: Emerald green (#51cf66)
  - Text: Warm white (#f1f3f5)
- **Use Case**: Nature enthusiasts, reduced blue light

### 3. **Solarized Dark** (Developer Favorite)
- **Concept**: Precision color palette for coding/developer audience
- **Primary Colors**:
  - Background: Solarized base (#002b36)
  - Surface: Solarized highlight (#073642)
  - Accent: Solarized cyan (#2aa198)
  - Text: Solarized base0 (#839496)
- **Use Case**: Developers familiar with Solarized ecosystem

### 4. **Rose Gold** (Elegant Light)
- **Concept**: Warm, sophisticated light theme with rose accents
- **Primary Colors**:
  - Background: Cream (#faf8f5)
  - Surface: Warm white (#ffffff)
  - Accent: Rose gold (#c77daa)
  - Text: Warm charcoal (#373a3c)
- **Use Case**: Social-focused users, creative professionals

### 5. **Cyberpunk** (Vibrant Dark)
- **Concept**: High-saturation neon accents on dark background
- **Primary Colors**:
  - Background: Nearly black (#0d0d14)
  - Surface: Deep purple (#1a1a2e)
  - Accent: Neon pink (#ff00ff) and cyan (#00ffff)
  - Text: White (#ffffff)
- **Use Case**: Gamers, tech enthusiasts, bold aesthetics

### 6. **Ocean** (Clean Light/Dark Hybrid)
- **Concept**: Clean, ocean-inspired blue theme
- **Primary Colors**:
  - Background: Deep ocean (#0a2342)
  - Surface: Ocean surface (#1e3a5f)
  - Accent: Seafoam (#48cae4)
  - Text: Sand (#f0ebd8)
- **Use Case**: Calm, focused social networking

### 7. **AMOLED Black** (True Dark)
- **Concept**: Pure black backgrounds for OLED displays
- **Primary Colors**:
  - Background: Pure black (#000000)
  - Surface: Near black (#0a0a0a)
  - Accent: White (#ffffff) for high contrast
  - Text: Gray (#b0b0b0)
- **Use Case**: OLED devices, battery conservation

## Technical Implementation

### Step 1: Theme File Structure
Create new theme directories following existing pattern:

```
app/javascript/styles/
├── midnight-blue/
│   ├── variables.scss          # SCSS variable overrides
│   ├── css_variables.scss      # CSS custom properties
│   └── diff.scss               # Component-specific overrides
├── forest/
│   ├── variables.scss
│   ├── css_variables.scss
│   └── diff.scss
├── solarized-dark/
│   └── ...
├── rose-gold/
│   └── ...
├── cyberpunk/
│   └── ...
├── ocean/
│   └── ...
└── amoled-black/
    └── ...
```

### Step 2: Theme Entry Points
Create SCSS entry files for each theme:

```scss
// midnight-blue.scss
@use 'midnight-blue/variables';
@use 'midnight-blue/css_variables';
@use 'application';
@use 'midnight-blue/diff';
```

### Step 3: Update Theme Registry
Add new themes to `config/themes.yml`:

```yaml
default: styles/application.scss
contrast: styles/contrast.scss
mastodon-light: styles/mastodon-light.scss
midnight-blue: styles/midnight-blue.scss
forest: styles/forest.scss
solarized-dark: styles/solarized-dark.scss
rose-gold: styles/rose-gold.scss
cyberpunk: styles/cyberpunk.scss
ocean: styles/ocean.scss
amoled-black: styles/amoled-black.scss
```

### Step 4: Localization
Add theme names to locale files:
- `config/locales/en.yml`
- `config/locales/simple_form.en.yml`

```yaml
themes:
  midnight-blue: "Midnight Blue"
  forest: "Forest"
  solarized-dark: "Solarized Dark"
  rose-gold: "Rose Gold"
  cyberpunk: "Cyberpunk"
  ocean: "Ocean"
  amoled-black: "AMOLED Black"
```

### Step 5: Build System
The Vite plugin (`MastodonThemes`) automatically:
- Reads `themes.yml`
- Creates entry points for each theme
- Generates theme-specific CSS bundles
- Supports HMR for theme development

No changes needed to build configuration.

## Implementation Checklist

### Phase 1: Foundation (2 themes)
- [ ] Create Midnight Blue theme
  - [ ] `app/javascript/styles/midnight-blue/variables.scss`
  - [ ] `app/javascript/styles/midnight-blue/css_variables.scss`
  - [ ] `app/javascript/styles/midnight-blue.scss`
  - [ ] Test contrast ratios
- [ ] Create Forest theme
  - [ ] Same file structure
  - [ ] Test with color blindness simulation
- [ ] Update `config/themes.yml`
- [ ] Add locale strings
- [ ] Test theme switching functionality
- [ ] Verify all components render correctly

### Phase 2: Developer & Professional (2 themes)
- [ ] Create Solarized Dark theme
- [ ] Create Ocean theme
- [ ] Update registry and locales
- [ ] Cross-browser testing

### Phase 3: Bold & Elegant (3 themes)
- [ ] Create Rose Gold theme (light)
- [ ] Create Cyberpunk theme
- [ ] Create AMOLED Black theme
- [ ] Update registry and locales
- [ ] Full accessibility audit

### Phase 4: Polish
- [ ] Create theme preview thumbnails
- [ ] Document theme color palettes
- [ ] Add theme customization guide
- [ ] Performance testing (CSS bundle sizes)

## Color Palette Specifications

### Midnight Blue
```scss
$ui-base-color: #0a1628;
$ui-base-lighter-color: #152238;
$ui-primary-color: #b8c5d6;
$ui-secondary-color: #8b95a5;
$ui-highlight-color: #4dabf7;
```

### Forest
```scss
$ui-base-color: #0d1f12;
$ui-base-lighter-color: #1a3320;
$ui-primary-color: #d3e5d8;
$ui-secondary-color: #a8c5af;
$ui-highlight-color: #51cf66;
```

### Solarized Dark
```scss
$ui-base-color: #002b36;
$ui-base-lighter-color: #073642;
$ui-primary-color: #839496;
$ui-secondary-color: #586e75;
$ui-highlight-color: #2aa198;
```

### Rose Gold
```scss
$ui-base-color: #faf8f5;
$ui-base-lighter-color: #ffffff;
$ui-primary-color: #373a3c;
$ui-secondary-color: #868e96;
$ui-highlight-color: #c77daa;
```

### Cyberpunk
```scss
$ui-base-color: #0d0d14;
$ui-base-lighter-color: #1a1a2e;
$ui-primary-color: #f0f0f0;
$ui-secondary-color: #a0a0a0;
$ui-highlight-color: #ff00ff;
```

### Ocean
```scss
$ui-base-color: #0a2342;
$ui-base-lighter-color: #1e3a5f;
$ui-primary-color: #d0e1f0;
$ui-secondary-color: #a0c0d9;
$ui-highlight-color: #48cae4;
```

### AMOLED Black
```scss
$ui-base-color: #000000;
$ui-base-lighter-color: #0a0a0a;
$ui-primary-color: #b0b0b0;
$ui-secondary-color: #606060;
$ui-highlight-color: #ffffff;
```

## Testing Considerations

### Accessibility Testing
- [ ] WCAG AA contrast ratio (4.5:1 for text, 3:1 for large text)
- [ ] Color blindness simulation (protanopia, deuteranopia, tritanopia)
- [ ] Focus indicator visibility
- [ ] Reduced motion preferences

### Cross-Browser Testing
- [ ] Chrome/Edge (Chromium)
- [ ] Firefox
- [ ] Safari (macOS and iOS)
- [ ] Mobile browsers

### Visual Regression Testing
- [ ] Screenshot comparison for each theme
- [ ] Test all major UI components:
  - Navigation
  - Compose box
  - Timeline/feed
  - Modals
  - Forms
  - Notifications

## Performance Considerations

Each theme adds approximately 10-30KB to the build output. Mitigation strategies:
1. Code splitting by theme (already implemented)
2. Lazy load theme CSS on selection
3. Minify production builds (already enabled)
4. Consider CSS compression for older themes

## Future Enhancements

### Post-Launch Features
1. **Custom Theme Builder**: Allow users to create and share themes
2. **Theme Marketplace**: Community-contributed themes
3. **Time-Based Switching**: Auto-switch between light/dark based on time
4. **Accent Color Customization**: Let users customize accent colors
5. **Per-Column Themes**: Different themes for different columns (advanced layout)

### Technical Improvements
1. Migrate to CSS custom properties for all colors (runtime theming)
2. Theme persistence across devices
3. Theme API for third-party clients
4. Theme preview before applying

## Documentation

Required documentation:
1. Theme development guide (CONTRIBUTING.md addition)
2. Color palette reference
3. Theme file structure explanation
4. How to add a new theme (tutorial)

## Conclusion

This plan provides a structured approach to implementing 7 modern themes that will significantly enhance the visual appeal of AgentHub Social while maintaining accessibility and performance standards. The phased implementation allows for iterative testing and refinement.