webmanager-mvp/project_docs/THEME_SELECTION_V1_DESIGN.md

# Theme Selection v1

## 1. Doel
Theme-selectie voegt nu waarde toe omdat de UI al een nette light/dark basis heeft, maar nog geen expliciet onderscheid maakt tussen:
- `theme`: de stijlset
- `mode`: light of dark binnen die stijlset

Dat onderscheid maakt de UI uitbreidbaar zonder de dagelijkse snelle UX kwijt te raken. Dit past logisch in de bestaande Settings-structuur:
- `General` voor functionele voorkeuren
- `Interface` voor theme-keuze
- `Logs` voor recente acties

## 2. Scope
Theme Selection v1 omvat:
- nieuw Settings-tabblad: `Interface`
- daarin alleen een pulldown/select: `Theme`
- bestaande snelle dark/light toggle blijft in de hoofdinterface bestaan
- beide keuzes worden opgeslagen in bestaande SQLite settings-opslag
- app leest beide waarden bij startup via backend en past die direct toe

Niet in scope:
- vrije CSS-bestandskeuze
- padinvoer
- upload van themes
- custom theme editor
- theme packs van externe bron

## 3. Theme-model
Aanbevolen model voor v1:
- werk met een whitelist van toegestane theme keys
- werk daarnaast met een aparte whitelist van toegestane color modes
- sla beide als strings op in settings

Aanbevolen settings voor v1:
- `selected_theme: string | null`
- `selected_color_mode: string | null`

Whitelist v1:
- `selected_theme`
  - `default`
- `selected_color_mode`
  - `dark`
  - `light`

Waarom dit veiliger en eenvoudiger is dan bestandsselectie:
- geen vrije filesystemtoegang nodig
- geen risico op ongeldige of kwaadaardige CSS-inhoud
- geen extra upload- of assetbeheer
- duidelijke validatie in backend mogelijk
- stabiel contract tussen backend setting en frontend rendering

## 4. Settings-opslag
Nieuwe settings in bestaande settings-opslag:
- `selected_theme`
- `selected_color_mode`

Semantiek:
- `selected_theme = null` betekent: fallback naar veilige default `default`
- `selected_color_mode = null` betekent: fallback naar veilige default `dark`
- onbekende opgeslagen waarden betekenen: negeren en fallback toepassen

Aanbevolen effectieve defaults:
- theme -> `default`
- mode -> `dark`

## 5. Settings UI
Tabs in Settings worden:
- `General`
- `Interface`
- `Logs`

`Interface` bevat in v1 alleen:
- label: `Theme`
- een select/pulldown met toegestane themes

Belangrijk:
- geen dark/light selector in `Settings > Interface`
- dark/light blijft een snelle hoofdinterface-actie

Aanbevolen v1-UX:
- select toont huidige theme-keuze
- gebruiker kiest andere waarde
- opslaan gebeurt via bestaande settings-saveflow
- keuze wordt direct toegepast in de UI na succesvolle backend-save

## 6. Frontend-impact
Frontend moet bij startup vroeg settings laden en daaruit beide waarden ophalen:
- `selected_theme`
- `selected_color_mode`

Daarna bepaalt frontend het effectieve UI-theme. Aanbevolen intern model:
- `data-theme="default-dark"`
- `data-theme="default-light"`

Aanbevolen volgorde:
1. `GET /api/settings`
2. bepaal effectief theme + mode
3. zet `document.documentElement.dataset.theme`
4. initialiseer de rest van de UI

Relatie met bestaande light/dark toggle:
- toggle blijft bestaan in de hoofdinterface
- toggle wijzigt alleen `selected_color_mode`
- toggle schrijft dus naar backend, niet naar localStorage

Reden:
- snelle dagelijkse UX blijft behouden
- `Settings > Interface` blijft schoon en beperkt tot theme-keuze
- theme en mode blijven conceptueel gescheiden

## 7. Backend-impact
Bestaande settings-API wordt uitgebreid met:
- `selected_theme`
- `selected_color_mode`

Benodigd:
- whitelistvalidatie op backend
- onbekende waarden blokkeren bij write
- bestaande settings repository/service/API uitbreiden

Niet nodig:
- nieuwe dependency
- vrije filesystemtoegang
- nieuwe asset-uploadroute

## 8. Regressierisico
Belangrijkste risico's:
- startup-volgorde: theme moet vroeg genoeg worden toegepast om flicker te beperken
- bestaande theme-toggle logica conflicteert nu nog met localStorage
- onbekende opgeslagen theme/mode-waarden moeten veilig terugvallen
- Settings-tabcomplexiteit mag niet onnodig toenemen

Belangrijkste mitigaties:
- één centrale frontendfunctie die theme en mode uit backend toepast
- localStorage volledig verwijderen als leidende theme-bron
- backend whitelistvalidatie
- fallback naar `default-dark`

## 9. Teststrategie
Backend golden tests:
- default `selected_theme`
- default `selected_color_mode`
- geldige theme save (`default`)
- geldige color mode save (`dark`, `light`)
- ongeldige theme key wordt geblokkeerd
- ongeldige color mode wordt geblokkeerd
- settings response bevat beide velden

UI smoke/regressietests:
- `Settings` bevat tabs `General`, `Interface`, `Logs`
- `Interface` tab bevat alleen theme select
- hoofdinterface bevat nog steeds dark/light toggle
- app leest beide settings via backend
- fallback bij ontbrekende/ongeldige waarde breekt startup niet

Handmatige validatie:
- theme wijzigen in `Settings > Interface`
- mode wisselen via toggle in de hoofdinterface
- app herladen en controleren dat beide keuzes behouden blijven
- controle dat light/dark correct doorwerken in modals, panelen en editor/viewers

## 10. Aanbeveling
Aanbevolen v1-richting met laag regressierisico:
- voeg `Interface` tab toe
- voeg `selected_theme` en `selected_color_mode` toe aan bestaande settings-opslag
- werk alleen met veilige whitelists
- houd v1 beperkt tot:
  - theme: `default`
  - mode: `dark|light`
- laat startup en toggle beide backendpersistente settings gebruiken
- fallback altijd veilig naar `default-dark`

Deze richting is:
- simpel
- veilig
- onderhoudbaar
- duidelijk uitbreidbaar naar extra themes, zonder de dagelijkse dark/light UX opnieuw te moeten ontwerpen