Skip to content

Theme System

Jump to bottom
Mo Abualruz edited this page Dec 9, 2025 · 1 revision

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:

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:

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:

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:

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:

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

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

# Get current theme
rice theme current

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

Creating Custom Themes

Create a custom theme:

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

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

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

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

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

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:

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

Theme Plugins

Create theme plugins:

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

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:

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:

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:

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

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

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

# 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

Last updated: December 9, 2025

Clone this wiki locally