testdrive-jsui/docs/features/themes.md

# Themes

**Visual theming and customization** 🎨

TestDrive-JSUI provides a flexible theming system that allows you to customize the visual appearance of the editor. Themes control colors, typography, spacing, and visual style of all components. Built on CSS custom properties for easy customization.

---

## Overview

The theming system uses CSS custom properties (CSS variables) to define color schemes and styling. Themes are applied as CSS classes, allowing multiple themes to coexist and switch dynamically.

### Default Theme

**GitHub Theme**: The default theme inspired by GitHub's design system
- Clean, professional appearance
- High contrast for readability
- Familiar to developers
- WCAG AA compliant colors

---

## Configuration

### Set Theme

Specify theme when creating editor:

```javascript
new TestDriveJSUI({
    container: '#editor',
    theme: 'github'  // Default theme
});
```

### Change Theme Dynamically

```javascript
const editor = new TestDriveJSUI({
    container: '#editor',
    theme: 'github'
});

// Change theme later
editor.applyTheme('custom-dark');
```

---

## Built-in Themes

### GitHub Theme (Default)

**Name**: `github`

**Description**: Clean, professional theme inspired by GitHub

**Colors**:
```css
--github-primary: #0969da      /* Primary blue */
--github-border: #d0d7de       /* Border gray */
--github-bg-subtle: #f6f8fa    /* Subtle background */
--github-fg-default: #1f2328   /* Default text */
--github-fg-muted: #656d76     /* Muted text */
--github-success: #1a7f37      /* Success green */
--github-danger: #d1242f       /* Danger red */
--github-warning: #9a6700      /* Warning amber */
```

**Usage**:
```javascript
new TestDriveJSUI({
    container: '#editor',
    theme: 'github'
});
```

**Features**:
- High contrast text (WCAG AA)
- Subtle hover states
- Professional color palette
- Optimized for long reading sessions

**Preview**:
- Sections: Light gray hover, blue focus
- Controls: White backgrounds, gray borders
- Buttons: Blue primary, red danger
- Debug panel: Dark theme for code readability

---

## Custom Themes

### Creating a Custom Theme

**Step 1**: Create CSS file `static/css/themes/custom-theme.css`

```css
/**
 * Custom Theme
 */

:root {
    /* Define your color palette */
    --custom-primary: #8b5cf6;
    --custom-border: #e5e7eb;
    --custom-bg: #ffffff;
    --custom-bg-subtle: #f9fafb;
    --custom-fg: #111827;
    --custom-fg-muted: #6b7280;
}

/* Editor styles */
.theme-custom-theme .markitect-edit-mode {
    color: var(--custom-fg);
    background: var(--custom-bg);
}

/* Section styles */
.theme-custom-theme .markitect-section:hover {
    background-color: var(--custom-bg-subtle);
    border-color: var(--custom-border);
}

.theme-custom-theme .markitect-section.editing {
    border-color: var(--custom-primary);
    box-shadow: 0 0 0 0.2rem rgba(139, 92, 246, 0.25);
}

/* Control panels */
.theme-custom-theme .markitect-control-panel {
    background: var(--custom-bg);
    border: 1px solid var(--custom-border);
    color: var(--custom-fg);
}

/* Buttons */
.theme-custom-theme button {
    background: var(--custom-primary);
    color: white;
    border: 1px solid transparent;
}

.theme-custom-theme button:hover {
    background: #7c3aed; /* Darker shade */
}
```

**Step 2**: Load CSS file

```html
<link rel="stylesheet" href="static/css/themes/custom-theme.css">
```

**Step 3**: Apply theme

```javascript
new TestDriveJSUI({
    container: '#editor',
    theme: 'custom-theme'
});
```

---

## Theme Examples

### Dark Theme

```css
/**
 * Dark Theme
 */

:root {
    --dark-primary: #3b82f6;
    --dark-border: #374151;
    --dark-bg: #1f2937;
    --dark-bg-subtle: #111827;
    --dark-fg: #f9fafb;
    --dark-fg-muted: #9ca3af;
}

.theme-dark .markitect-edit-mode {
    color: var(--dark-fg);
    background: var(--dark-bg);
}

.theme-dark .markitect-section:hover {
    background-color: var(--dark-bg-subtle);
    border-color: var(--dark-border);
}

.theme-dark .markitect-section.editing {
    border-color: var(--dark-primary);
    box-shadow: 0 0 0 0.2rem rgba(59, 130, 246, 0.25);
}

.theme-dark .markitect-control-panel {
    background: var(--dark-bg-subtle);
    border: 1px solid var(--dark-border);
    color: var(--dark-fg);
}

.theme-dark button {
    background: var(--dark-primary);
    color: white;
}
```

**Usage**:
```javascript
new TestDriveJSUI({
    container: '#editor',
    theme: 'dark'
});
```

---

### Minimal Theme

```css
/**
 * Minimal Theme
 */

:root {
    --minimal-primary: #000000;
    --minimal-border: #e0e0e0;
    --minimal-bg: #ffffff;
    --minimal-fg: #000000;
}

.theme-minimal .markitect-edit-mode {
    color: var(--minimal-fg);
    background: var(--minimal-bg);
    font-family: 'Georgia', serif;
    font-size: 18px;
    line-height: 1.8;
}

.theme-minimal .markitect-section:hover {
    background-color: #fafafa;
}

.theme-minimal .markitect-section.editing {
    border-color: var(--minimal-primary);
    box-shadow: none;
}

.theme-minimal .markitect-control-panel {
    background: var(--minimal-bg);
    border: 1px solid var(--minimal-border);
    box-shadow: none;
}

.theme-minimal button {
    background: var(--minimal-primary);
    color: white;
    border-radius: 0;
}
```

**Usage**:
```javascript
new TestDriveJSUI({
    container: '#editor',
    theme: 'minimal'
});
```

---

### High Contrast Theme

```css
/**
 * High Contrast Theme (Accessibility)
 */

:root {
    --hc-primary: #0000ff;
    --hc-border: #000000;
    --hc-bg: #ffffff;
    --hc-fg: #000000;
    --hc-success: #008000;
    --hc-danger: #ff0000;
}

.theme-high-contrast .markitect-edit-mode {
    color: var(--hc-fg);
    background: var(--hc-bg);
    font-weight: 500;
}

.theme-high-contrast .markitect-section:hover {
    background-color: #ffff00; /* Yellow highlight */
    border: 2px solid var(--hc-border);
}

.theme-high-contrast .markitect-section.editing {
    border: 3px solid var(--hc-primary);
}

.theme-high-contrast .markitect-control-panel {
    background: var(--hc-bg);
    border: 2px solid var(--hc-border);
}

.theme-high-contrast button {
    background: var(--hc-primary);
    color: white;
    border: 2px solid var(--hc-border);
    font-weight: bold;
}
```

**Usage**:
```javascript
new TestDriveJSUI({
    container: '#editor',
    theme: 'high-contrast'
});
```

---

## Theme Components

Themes can style these components:

### 1. Editor Container

**Classes**: `.markitect-edit-mode`, `.markitect-view-mode`

**Styles**:
- Background color
- Text color
- Font family
- Line height

**Example**:
```css
.theme-custom .markitect-edit-mode {
    font-family: 'Inter', sans-serif;
    line-height: 1.7;
    color: #1a1a1a;
    background: #fafafa;
}
```

---

### 2. Sections

**Classes**: `.markitect-section`, `.markitect-section:hover`, `.markitect-section.editing`

**Styles**:
- Hover background
- Border colors
- Focus state
- Shadow effects

**Example**:
```css
.theme-custom .markitect-section {
    border-radius: 8px;
    transition: all 0.2s ease;
}

.theme-custom .markitect-section:hover {
    background: #f0f0f0;
    transform: translateX(2px);
}

.theme-custom .markitect-section.editing {
    background: white;
    box-shadow: 0 4px 12px rgba(0,0,0,0.1);
}
```

---

### 3. Control Panels

**Classes**: `.markitect-control-panel`, `.edit-control`, `.status-control`, `.contents-control`, `.debug-control`

**Styles**:
- Panel background
- Border style
- Shadow
- Text colors

**Example**:
```css
.theme-custom .markitect-control-panel {
    background: rgba(255, 255, 255, 0.95);
    backdrop-filter: blur(10px);
    border: 1px solid rgba(0, 0, 0, 0.1);
    border-radius: 12px;
    box-shadow: 0 2px 8px rgba(0,0,0,0.05);
}
```

---

### 4. Buttons

**Classes**: `.control-button`, `.control-button.danger`, `.control-button.success`

**Styles**:
- Button colors
- Hover states
- Active states
- Variants

**Example**:
```css
.theme-custom button {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    border: none;
    border-radius: 6px;
    padding: 0.5rem 1rem;
    font-weight: 600;
    transition: transform 0.1s ease;
}

.theme-custom button:hover {
    transform: translateY(-1px);
    box-shadow: 0 4px 8px rgba(0,0,0,0.2);
}

.theme-custom button:active {
    transform: translateY(0);
}
```

---

### 5. Debug Panel

**Classes**: `.markitect-debug-panel`, `.markitect-debug-error`, `.markitect-debug-warning`

**Styles**:
- Panel background (usually dark)
- Message colors
- Font (monospace)

**Example**:
```css
.theme-custom .markitect-debug-panel {
    background: #282c34;
    color: #abb2bf;
    font-family: 'Fira Code', 'Consolas', monospace;
    font-size: 13px;
}

.theme-custom .markitect-debug-error {
    color: #e06c75;
}

.theme-custom .markitect-debug-warning {
    color: #e5c07b;
}
```

---

### 6. Table of Contents

**Classes**: `.contents-control`, `.toc-item`, `.toc-item:hover`

**Styles**:
- TOC item colors
- Hover effects
- Active heading
- Indentation

**Example**:
```css
.theme-custom .toc-item {
    padding: 0.4rem 0.6rem;
    border-radius: 4px;
    transition: background 0.15s ease;
}

.theme-custom .toc-item:hover {
    background: #e8f4f8;
    color: #0077cc;
}

.theme-custom .toc-item.active {
    background: #0077cc;
    color: white;
    font-weight: 600;
}
```

---

## Advanced Theming

### CSS Variables

Use CSS custom properties for flexible theming:

```css
:root {
    /* Color palette */
    --color-primary: #3b82f6;
    --color-secondary: #8b5cf6;
    --color-success: #10b981;
    --color-warning: #f59e0b;
    --color-danger: #ef4444;

    /* Neutral colors */
    --color-gray-50: #f9fafb;
    --color-gray-100: #f3f4f6;
    --color-gray-900: #111827;

    /* Spacing */
    --spacing-xs: 0.25rem;
    --spacing-sm: 0.5rem;
    --spacing-md: 1rem;
    --spacing-lg: 1.5rem;
    --spacing-xl: 2rem;

    /* Typography */
    --font-sans: 'Inter', sans-serif;
    --font-mono: 'Fira Code', monospace;
    --font-size-sm: 0.875rem;
    --font-size-base: 1rem;
    --font-size-lg: 1.125rem;

    /* Effects */
    --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
    --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
    --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);

    /* Transitions */
    --transition-fast: 0.15s ease;
    --transition-base: 0.2s ease;
    --transition-slow: 0.3s ease;
}

.theme-custom .markitect-section {
    padding: var(--spacing-md);
    border-radius: var(--spacing-xs);
    transition: all var(--transition-base);
}

.theme-custom button {
    padding: var(--spacing-sm) var(--spacing-md);
    font-family: var(--font-sans);
    font-size: var(--font-size-sm);
    box-shadow: var(--shadow-sm);
}
```

---

### Theme Switcher

Implement dynamic theme switching:

```javascript
const editor = new TestDriveJSUI({
    container: '#editor',
    theme: 'github'
});

// Create theme switcher UI
const themeSwitcher = document.createElement('select');
themeSwitcher.innerHTML = `
    <option value="github">GitHub</option>
    <option value="dark">Dark</option>
    <option value="minimal">Minimal</option>
    <option value="high-contrast">High Contrast</option>
`;

themeSwitcher.addEventListener('change', (e) => {
    editor.applyTheme(e.target.value);

    // Save preference
    localStorage.setItem('preferred-theme', e.target.value);
});

// Load saved theme
const savedTheme = localStorage.getItem('preferred-theme');
if (savedTheme) {
    editor.applyTheme(savedTheme);
    themeSwitcher.value = savedTheme;
}

document.body.appendChild(themeSwitcher);
```

---

### System Theme Detection

Detect and apply system dark mode preference:

```javascript
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

const editor = new TestDriveJSUI({
    container: '#editor',
    theme: prefersDark ? 'dark' : 'github'
});

// Listen for system theme changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
    editor.applyTheme(e.matches ? 'dark' : 'github');
});
```

---

### Per-Component Theming

Theme individual components differently:

```css
.theme-custom .edit-control {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
}

.theme-custom .status-control {
    background: #f0fdf4;
    border-color: #86efac;
}

.theme-custom .contents-control {
    background: #eff6ff;
    border-color: #93c5fd;
}

.theme-custom .debug-control {
    background: #282c34;
    color: #abb2bf;
}
```

---

## Best Practices

### For Theme Creators

1. **Use CSS variables**: Define colors centrally for consistency
2. **Test contrast**: Ensure WCAG AA compliance (4.5:1 minimum)
3. **Consider dark mode**: Provide both light and dark variants
4. **Test all states**: Hover, focus, active, disabled
5. **Responsive**: Test on different screen sizes
6. **Accessibility**: High contrast mode, focus indicators

### For Users

1. **Choose readable fonts**: Sans-serif for UI, serif/mono for content
2. **Adjust for lighting**: Light themes for bright environments, dark for dim
3. **Save preferences**: Use localStorage to persist theme choice
4. **Test compatibility**: Verify theme works with all controls

---

## Accessibility

### High Contrast

Themes should provide high contrast variants:

```css
@media (prefers-contrast: high) {
    .theme-github {
        --github-fg-default: #000000;
        --github-bg-subtle: #ffffff;
        --github-border: #000000;
    }
}
```

### Reduced Motion

Respect user's motion preferences:

```css
@media (prefers-reduced-motion: reduce) {
    .theme-custom .markitect-section {
        transition: none;
    }

    .theme-custom button {
        transition: none;
    }
}
```

### Color Blind Friendly

Use patterns in addition to color:

```css
.theme-custom .markitect-debug-error::before {
    content: '❌ ';  /* Icon in addition to red color */
}

.theme-custom .markitect-debug-warning::before {
    content: '⚠️ ';  /* Icon in addition to yellow color */
}

.theme-custom .markitect-debug-success::before {
    content: '✅ ';  /* Icon in addition to green color */
}
```

---

## Troubleshooting

### Theme Not Applied

**Problem**: Theme styles don't appear

**Solutions**:

1. **Check CSS file loaded**:
   ```html
   <link rel="stylesheet" href="static/css/themes/custom-theme.css">
   ```

2. **Verify theme name**:
   ```javascript
   console.log(editor.config.theme); // Should match CSS class
   ```

3. **Check CSS selector specificity**:
   ```css
   /* More specific */
   .theme-custom .markitect-section { }

   /* Less specific - might not work */
   .markitect-section { }
   ```

4. **Clear browser cache**: Force refresh with Ctrl+F5

### Theme Partially Applied

**Problem**: Some components themed, others not

**Solution**: Ensure all component classes are styled:

```css
.theme-custom .markitect-edit-mode { /* Editor */ }
.theme-custom .markitect-section { /* Sections */ }
.theme-custom .markitect-control-panel { /* All controls */ }
.theme-custom .edit-control { /* Specific control */ }
.theme-custom button { /* Buttons */ }
```

### CSS Variables Not Working

**Problem**: CSS variables show default values

**Solution**: Define variables in `:root` or `.theme-*` scope:

```css
/* Correct */
:root {
    --custom-primary: #3b82f6;
}

/* Or scoped to theme */
.theme-custom {
    --custom-primary: #3b82f6;
}

/* Use in components */
.theme-custom .markitect-section.editing {
    border-color: var(--custom-primary);
}
```

---

## Future Themes (Roadmap)

Planned themes for future versions:

### Version 1.1
- ✅ **Dracula**: Popular dark theme
- ✅ **Solarized**: Light and dark variants
- ✅ **Monokai**: Vibrant syntax colors
- ✅ **Nord**: Arctic-inspired palette

### Version 1.2
- 🔜 **Material Design**: Google's design system
- 🔜 **Tailwind**: Tailwind CSS inspired
- 🔜 **Bootstrap**: Bootstrap color scheme
- 🔜 **Cyberpunk**: Neon aesthetic

### Version 2.0
- 🔜 **Theme builder**: Visual theme creator
- 🔜 **Theme marketplace**: Share custom themes
- 🔜 **Live preview**: Preview themes before applying
- 🔜 **Theme export**: Export theme as CSS

**Request themes**: Submit suggestions at [GitHub Issues](https://github.com/anthropics/testdrive-jsui/issues)

---

## Related Features

- **[Configuration](../api/configuration.md)** - Theme configuration options
- **[Customization](customization.md)** - Advanced customization (coming soon)
- **[Accessibility](accessibility.md)** - Accessible themes (coming soon)

---

**See Also**:
- [CSS Variables Reference](../api/css-variables.md) (coming soon)
- [Theme Gallery](../../examples/themes/) (coming soon)
- [Examples](../../examples/)

---

**Version**: 1.0.0
**Last Updated**: 2025-12-16