# Theming

## Overview

CalMiner uses a centralized theming system based on CSS custom properties (variables) to ensure consistent styling across the application. The theme is stored in the database and can be customized through environment variables or the UI settings page.

## Default Theme Settings

The default theme provides a light, professional color palette suitable for business applications. The colors are defined as CSS custom properties and stored in the `application_setting` table with category "theme".

### Color Palette

| CSS Variable                | Default Value            | Description              |
| --------------------------- | ------------------------ | ------------------------ |
| `--color-background`        | `#f4f5f7`                | Main background color    |
| `--color-surface`           | `#ffffff`                | Surface/card background  |
| `--color-text-primary`      | `#2a1f33`                | Primary text color       |
| `--color-text-secondary`    | `#624769`                | Secondary text color     |
| `--color-text-muted`        | `#64748b`                | Muted text color         |
| `--color-text-subtle`       | `#94a3b8`                | Subtle text color        |
| `--color-text-invert`       | `#ffffff`                | Text on dark backgrounds |
| `--color-text-dark`         | `#0f172a`                | Dark text for contrast   |
| `--color-text-strong`       | `#111827`                | Strong/bold text         |
| `--color-primary`           | `#5f320d`                | Primary brand color      |
| `--color-primary-strong`    | `#7e4c13`                | Stronger primary         |
| `--color-primary-stronger`  | `#837c15`                | Strongest primary        |
| `--color-accent`            | `#bff838`                | Accent/highlight color   |
| `--color-border`            | `#e2e8f0`                | Default border color     |
| `--color-border-strong`     | `#cbd5e1`                | Strong border color      |
| `--color-highlight`         | `#eef2ff`                | Highlight background     |
| `--color-panel-shadow`      | `rgba(15, 23, 42, 0.08)` | Subtle shadow            |
| `--color-panel-shadow-deep` | `rgba(15, 23, 42, 0.12)` | Deeper shadow            |
| `--color-surface-alt`       | `#f8fafc`                | Alternative surface      |
| `--color-success`           | `#047857`                | Success state color      |
| `--color-error`             | `#b91c1c`                | Error state color        |

## Customization

### Environment Variables

Theme colors can be overridden using environment variables with the prefix `CALMINER_THEME_`. For example:

```bash
export CALMINER_THEME_COLOR_BACKGROUND="#000000"
export CALMINER_THEME_COLOR_ACCENT="#ff0000"
```

The variable names are derived by:

1. Removing the `--` prefix
2. Converting to uppercase
3. Replacing `-` with `_`
4. Adding `CALMINER_THEME_` prefix

### Database Storage

Settings are stored in the `application_setting` table with:

- `category`: "theme"
- `value_type`: "color"
- `is_editable`: true

### UI Settings

Users can modify theme colors through the settings page at `/ui/settings`.

## Implementation

The theming system is implemented in:

- `services/settings.py`: Color management and defaults
- `routes/settings.py`: API endpoints for theme settings
- `static/css/main.css`: CSS variable definitions
- `templates/settings.html`: UI for theme customization

## Seeding

Default theme settings are seeded during database setup using the seed script:

```bash
python scripts/seed_data.py --theme
```

Or as part of defaults:

```bash
python scripts/seed_data.py --defaults
```