markitect-main/markitect/themes/README.md

# Markitect Modular Theme System

This directory contains the modular theme system for Markitect, allowing themes to be defined in separate YAML files for better maintainability and organization.

## Directory Structure

```
themes/
├── __init__.py           # Theme loader and registry
├── README.md             # This file
├── mode/                 # Mode themes (light/dark color schemes)
│   ├── light.yaml
│   └── dark.yaml
├── ui/                   # UI themes (interface styling)
│   ├── standard.yaml
│   ├── electric.yaml
│   └── psychedelic.yaml
├── document/             # Document themes (content formatting)
│   ├── basic.yaml
│   ├── github.yaml
│   ├── academic.yaml
│   ├── substack.yaml
│   └── chatgpt.yaml
└── branding/             # Branding themes (company/personal styling)
    ├── corporate.yaml
    └── startup.yaml
```

## Theme File Format

Each theme file is a YAML file with the following structure:

```yaml
# Theme metadata
name: theme_name
description: "Brief description of the theme"
scope: document  # One of: mode, ui, document, branding
author: "Theme Author"
version: "1.0.0"

# Theme properties
properties:
  font_family: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif'
  max_width: '580px'
  body_background: '#ffffff'
  body_color: '#1f1f1f'
  # ... other CSS properties

# Optional: Design notes and comments
# Design notes:
# - Rationale for design choices
# - Usage recommendations
```

## Theme Scopes

### Mode Themes (`mode/`)
Control light/dark color schemes:
- `light.yaml` - Light color scheme for daytime reading
- `dark.yaml` - Dark color scheme for low-light environments

### UI Themes (`ui/`)
Control interface styling:
- `standard.yaml` - Clean, professional interface
- `electric.yaml` - Vibrant, high-energy styling
- `psychedelic.yaml` - Colorful, creative styling

### Document Themes (`document/`)
Control content formatting and typography:
- `basic.yaml` - Simple, clean formatting
- `github.yaml` - GitHub-inspired styling
- `academic.yaml` - Traditional academic formatting
- `substack.yaml` - Long-form reading optimization
- `chatgpt.yaml` - Compact, interactive layout

### Branding Themes (`branding/`)
Control company/personal branding:
- `corporate.yaml` - Professional business styling
- `startup.yaml` - Modern startup aesthetic

## Usage

Themes are automatically loaded when the system starts. You can use them in several ways:

### Command Line
```bash
markitect md-render document.md --theme chatgpt
markitect md-render document.md --theme "light,standard,substack"
```

### Programmatic Access
```python
from markitect.themes import get_theme, list_themes

# Get a specific theme
chatgpt_theme = get_theme('chatgpt')

# List all themes
all_themes = list_themes()

# List themes by scope
document_themes = list_themes(scope='document')
```

## Adding New Themes

1. Create a new YAML file in the appropriate scope directory
2. Follow the standard YAML format (see examples)
3. Include proper metadata (name, description, scope, author, version)
4. Add comprehensive properties for your theme
5. Test with existing content to ensure compatibility

### Example: Adding a New Theme

Create `markitect/themes/document/academic_paper.yaml`:

```yaml
name: academic_paper
description: "Formal academic paper formatting with traditional typography"
scope: document
author: "Your Name"
version: "1.0.0"

properties:
  font_family: 'Times New Roman, Times, serif'
  heading_font_family: 'Times New Roman, Times, serif'
  max_width: '650px'
  line_height: '2.0'
  text_align: 'justify'
  body_background: '#ffffff'
  body_color: '#000000'
  heading_color: '#000000'
  # ... additional properties
```

The theme will be automatically available as `academic_paper` after restart.

## Migration from Inline Themes

The system uses a hybrid approach:
1. Themes defined in YAML files take precedence
2. Fallback to inline themes for backward compatibility
3. Existing code continues to work without changes

This allows gradual migration of themes from the main code file to separate files.

## Benefits

- **Maintainability**: Each theme is a separate file
- **Collaboration**: Multiple people can work on themes simultaneously
- **Discoverability**: Easy to see what themes exist
- **Documentation**: Each theme file can include design notes
- **Validation**: YAML format allows for schema validation
- **Modularity**: Themes can be distributed separately

## Backward Compatibility

The modular theme system is fully backward compatible:
- All existing theme names continue to work
- Existing LAYERED_THEMES access patterns work unchanged
- Legacy TEMPLATE_STYLES mapping preserved
- CLI commands work exactly the same

## Performance

- Themes are loaded once at startup and cached
- No performance impact during normal operation
- Reload functionality available for development