# Theme System

**Status**: ✅ Complete

**Phase**: Phase 7 - Integration Features

**Last Updated**: December 9, 2025

---

## Overview

The Theme System provides comprehensive customization of RiceCoder's visual appearance. Choose from built-in themes (light, dark, high-contrast) or create custom themes. Themes can be switched at runtime without restarting, and all visual elements (colors, fonts, spacing) are customizable through configuration files.

## Key Features

- **Built-in Themes**: Light, Dark, High-Contrast themes
- **Custom Themes**: Create and share custom themes
- **Runtime Switching**: Change themes without restart
- **Design Tokens**: Centralized color and style definitions
- **Theme Inheritance**: Extend existing themes
- **Per-Component Customization**: Override specific elements
- **Theme Validation**: Ensure theme consistency
- **Theme Distribution**: Share themes via packages

## Built-in Themes

### Dark Theme (Default)

Modern dark theme optimized for terminal use:

```bash
rice config set theme dark
```

**Colors**:
- Background: #1e1e1e
- Foreground: #e0e0e0
- Primary: #007acc
- Success: #4ec9b0
- Warning: #dcdcaa
- Error: #f48771

### Light Theme

Clean light theme for daytime use:

```bash
rice config set theme light
```

**Colors**:
- Background: #ffffff
- Foreground: #333333
- Primary: #0066cc
- Success: #008000
- Warning: #ff8800
- Error: #cc0000

### High-Contrast Theme

Accessible theme with high contrast:

```bash
rice config set theme high-contrast
```

**Colors**:
- Background: #000000
- Foreground: #ffffff
- Primary: #ffff00
- Success: #00ff00
- Warning: #ff00ff
- Error: #ff0000

## Installation & Setup

### Configuration

Configure themes in `.ricecoder/config.yaml`:

```yaml
theme:
  # Current theme
  current: dark
  
  # Theme directory
  directory: ~/.ricecoder/themes
  
  # Enable theme switching
  enable_switching: true
  
  # Auto-detect system theme
  auto_detect: false
  
  # Theme update interval (seconds)
  update_interval: 5
```

### Theme Directory Structure

```
~/.ricecoder/themes/
├── dark.yaml
├── light.yaml
├── high-contrast.yaml
├── my-custom-theme.yaml
└── themes/
    ├── nord.yaml
    ├── dracula.yaml
    └── solarized.yaml
```

## How to Use

### Switching Themes

Switch theme at runtime:

```bash
# Switch to light theme
rice theme set light

# Switch to dark theme
rice theme set dark

# Switch to high-contrast theme
rice theme set high-contrast

# Switch to custom theme
rice theme set my-custom-theme
```

List available themes:

```bash
# List all themes
rice theme list

# Output:
# Available Themes:
# - dark (built-in, current)
# - light (built-in)
# - high-contrast (built-in)
# - nord (custom)
# - dracula (custom)
# - solarized (custom)
```

View current theme:

```bash
# Get current theme
rice theme current

# Output:
# Current theme: dark
# Location: built-in
```

### Creating Custom Themes

Create a custom theme:

```bash
# Create new theme
rice theme create my-theme

# Interactive prompt:
# Theme name: My Custom Theme
# Base theme: dark
# Description: My personal theme
# (opens editor for customization)
```

Edit theme file directly:

Create `~/.ricecoder/themes/my-theme.yaml`:

```yaml
# Theme metadata
name: "My Custom Theme"
description: "My personal theme"
version: "1.0.0"
author: "Your Name"

# Color palette
colors:
  # UI colors
  background: "#1e1e1e"
  foreground: "#e0e0e0"
  border: "#3e3e3e"
  
  # Semantic colors
  primary: "#007acc"
  secondary: "#646695"
  success: "#4ec9b0"
  warning: "#dcdcaa"
  error: "#f48771"
  info: "#4fc1ff"
  
  # Syntax highlighting
  syntax:
    keyword: "#569cd6"
    string: "#ce9178"
    comment: "#6a9955"
    number: "#b5cea8"
    operator: "#d4d4d4"
    function: "#dcdcaa"
    type: "#4ec9b0"

# Typography
typography:
  font_family: "Fira Code"
  font_size: 12
  line_height: 1.5
  
  # Font variants
  monospace: "Fira Code"
  sans_serif: "Segoe UI"
  serif: "Georgia"

# Spacing
spacing:
  xs: 2
  sm: 4
  md: 8
  lg: 16
  xl: 32

# Borders
borders:
  radius: 4
  width: 1
  style: "solid"

# Shadows
shadows:
  sm: "0 1px 2px rgba(0,0,0,0.05)"
  md: "0 4px 6px rgba(0,0,0,0.1)"
  lg: "0 10px 15px rgba(0,0,0,0.1)"

# Component overrides
components:
  button:
    background: "#007acc"
    foreground: "#ffffff"
    hover_background: "#005a9e"
  
  input:
    background: "#3e3e3e"
    foreground: "#e0e0e0"
    border_color: "#555555"
  
  panel:
    background: "#252526"
    foreground: "#e0e0e0"
    border_color: "#3e3e3e"
```

### Theme Inheritance

Extend existing themes:

```yaml
# Extend dark theme
extends: dark

# Override specific colors
colors:
  primary: "#ff6b6b"
  success: "#51cf66"
  warning: "#ffd43b"

# Override components
components:
  button:
    background: "#ff6b6b"
    hover_background: "#ff5252"
```

### Validating Themes

Validate theme file:

```bash
# Validate theme
rice theme validate my-theme

# Output:
# Theme validation: OK
# - Colors: 15 defined
# - Typography: 3 fonts
# - Spacing: 5 levels
# - Components: 3 overrides
```

## Advanced Usage

### Theme Variants

Create theme variants:

```bash
# Create variant of dark theme
rice theme create dark-blue --base dark

# Create variant of light theme
rice theme create light-green --base light
```

### Conditional Themes

Use system theme preference:

```yaml
theme:
  # Auto-detect system theme
  auto_detect: true
  
  # Map system themes to RiceCoder themes
  system_mapping:
    light: light
    dark: dark
```

### Theme Scheduling

Schedule theme changes:

```yaml
theme:
  # Enable scheduling
  schedule_enabled: true
  
  # Schedule rules
  schedule:
    - time: "06:00"
      theme: light
    - time: "18:00"
      theme: dark
```

### Theme Plugins

Create theme plugins:

```bash
# Create theme plugin
rice theme plugin create my-plugin

# Install theme plugin
rice theme plugin install my-plugin

# List installed plugins
rice theme plugin list
```

## Examples

### Example 1: Nord Theme

Create Nord theme:

```yaml
name: "Nord"
description: "Arctic, north-bluish color palette"
extends: dark

colors:
  background: "#2e3440"
  foreground: "#eceff4"
  primary: "#88c0d0"
  success: "#a3be8c"
  warning: "#ebcb8b"
  error: "#bf616a"
  
  syntax:
    keyword: "#81a1c1"
    string: "#a3be8c"
    comment: "#616e88"
    number: "#b48ead"
```

### Example 2: Dracula Theme

Create Dracula theme:

```yaml
name: "Dracula"
description: "A dark theme based on Dracula"
extends: dark

colors:
  background: "#282a36"
  foreground: "#f8f8f2"
  primary: "#8be9fd"
  success: "#50fa7b"
  warning: "#f1fa8c"
  error: "#ff5555"
  
  syntax:
    keyword: "#ff79c6"
    string: "#f1fa8c"
    comment: "#6272a4"
    number: "#bd93f9"
```

### Example 3: Solarized Theme

Create Solarized theme:

```yaml
name: "Solarized"
description: "Precision colors for machines and people"
extends: dark

colors:
  background: "#002b36"
  foreground: "#839496"
  primary: "#268bd2"
  success: "#859900"
  warning: "#b58900"
  error: "#dc322f"
  
  syntax:
    keyword: "#859900"
    string: "#2aa198"
    comment: "#586e75"
    number: "#d33682"
```

## Troubleshooting

### Issue: Theme not applying

**Solution**: Verify theme file and restart:

```bash
# Validate theme
rice theme validate my-theme

# Check theme location
rice theme list

# Restart RiceCoder
rice restart
```

### Issue: Custom theme not found

**Solution**: Ensure theme file is in correct location:

```bash
# Check theme directory
ls ~/.ricecoder/themes/

# Create theme directory if missing
mkdir -p ~/.ricecoder/themes

# Copy theme file to directory
cp my-theme.yaml ~/.ricecoder/themes/
```

### Issue: Theme colors not matching

**Solution**: Check color format and values:

```bash
# Validate theme colors
rice theme validate my-theme --verbose

# Check color values
rice theme colors my-theme

# Update color values
rice theme edit my-theme
```

### Issue: Font not rendering correctly

**Solution**: Install required fonts:

```bash
# Check available fonts
rice theme fonts

# Install font
# macOS: brew install font-fira-code
# Linux: sudo apt install fonts-fira-code
# Windows: Download from Google Fonts

# Update theme font
rice theme edit my-theme
```

## Performance

- **Theme Switching**: < 100ms
- **Theme Loading**: < 50ms
- **Theme Validation**: < 200ms
- **Color Lookup**: < 1ms

## Limitations

- Maximum 256 colors per theme
- Font must be installed on system
- Theme size limited to 1MB
- Maximum 100 custom themes

## Security Considerations

- Themes are loaded from trusted locations only
- Theme files are validated before use
- No code execution in theme files
- Theme sharing requires verification

## See Also

- [TUI Interface](./TUI-Interface.md) - Terminal UI guide
- [Configuration Guide](./Configuration.md) - Configuration options
- [Architecture Overview](./Architecture-Overview.md) - System architecture
- [Contributing Guide](./Contributing.md) - How to contribute

---

*Last updated: December 9, 2025*