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:

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

Change Theme Dynamically

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:

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

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

/**
 * 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

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

Step 3: Apply theme

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

---

Theme Examples

Dark Theme

/**
 * 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:

new TestDriveJSUI({
    container: '#editor',
    theme: 'dark'
});

---

Minimal Theme

/**
 * 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:

new TestDriveJSUI({
    container: '#editor',
    theme: 'minimal'
});

---

High Contrast Theme

/**
 * 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:

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:

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

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

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

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

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

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

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

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:

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:

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

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

Reduced Motion

Respect user's motion preferences:

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

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

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

2. Verify theme name:

   console.log(editor.config.theme); // Should match CSS class
   

3. Check CSS selector specificity:

   /* 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:

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

/* 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

---

Related Features

• Configuration - Theme configuration options
• Customization - Advanced customization (coming soon)
• Accessibility - Accessible themes (coming soon)

---

See Also:

• CSS Variables Reference (coming soon)
• Theme Gallery (coming soon)
• Examples

---

Version: 1.0.0 Last Updated: 2025-12-16