webmanager-mvp/project_docs/BUILTIN_THEMES_V1_DESIGN.md

# Built-in Themes v1

## 1. Doel
Built-in themes voegen nu waarde toe omdat de webui functioneel volwassen genoeg is om visuele voorkeuren relevant te maken zonder dat de workflow eerst nog instabiel is. De huidige app heeft al een vaste dual-pane structuur, modals, functiebalk, viewers en editorflow. Dat maakt het logisch om stijlvarianten toe te voegen zolang de interactie en informatiearchitectuur gelijk blijven.

Dit past goed binnen de bestaande `Settings > Interface` structuur, omdat theme-keuze daar een stabiele, globale UI-voorkeur is. De bestaande scheiding tussen theme-family en dark/light mode blijft daarbij bruikbaar:
- `selected_theme` = stijlset / family
- `selected_color_mode` = `dark` of `light` binnen die family

## 2. Scope
Built-in theme families voor v1:
- `default`
- `macos-soft`
- `midnight`
- `graphite`
- `windows11`

Expliciet niet in v1:
- `lcars`
- vrije theme-bestanden
- upload of filesystem picker
- layoutvarianten per theme
- component-specifieke thema-engine buiten CSS tokens/selectors

`lcars` hoort beter in een latere v2-slice. Reden: het is visueel extreem uitgesproken, legt druk op contrast, spacing, functiebalkleesbaarheid en waarschijnlijk ook op de dual-pane ergonomie. Dat is een hoger UX-risico dan de rustige families hierboven.

## 3. Theme-model
Het bestaande settingsmodel blijft leidend:
- `selected_theme`: theme-family key
- `selected_color_mode`: `dark` of `light`

Elke built-in family ondersteunt beide modi:
- `default-light`
- `default-dark`
- `macos-soft-light`
- `macos-soft-dark`
- `midnight-light`
- `midnight-dark`
- `graphite-light`
- `graphite-dark`
- `windows11-light`
- `windows11-dark`

De frontend combineert beide settings tot de effectieve UI-state, bijvoorbeeld via een attribuut zoals:
- `data-theme="macos-soft-light"`
- of combinatie van `data-theme-family` + `data-color-mode`

Aanbevolen voor v1: beide attributen zetten.
Reden: duidelijkere CSS-structuur en minder fragiele string-parsing in selectors.

Aanbevolen HTML-state:
- `data-theme-family="macos-soft"`
- `data-color-mode="dark"`

## 4. CSS-architectuur
Aanbevolen richting:
- een gedeelde `base.css` of equivalent voor:
  - layout
  - spacing
  - componentstructuur
  - modals
  - panelen
  - functiebalk
  - tabel/lijststructuur
  - algemene componentbasis
- aparte CSS-bestanden per theme-family:
  - `theme-default.css`
  - `theme-macos-soft.css`
  - `theme-midnight.css`
  - `theme-graphite.css`
  - `theme-windows11.css`
- light/dark binnen dezelfde family regelen met selectors en tokens in dat family-bestand

Voorbeeldrichting:
- `base.css`
- `theme-default.css`
- `theme-macos-soft.css`
- `theme-midnight.css`
- `theme-graphite.css`
- `theme-windows11.css`

In elk family-bestand staan alleen tokens en beperkte theme-specifieke afwerkingen, bijvoorbeeld:
- background colors
- surface colors
- border colors
- accent colors
- selection/current row tuning
- shadow/radius tuning waar nodig

Niet in theme-bestanden:
- grid-structuur
- flex-layout van panelen
- componentmarkup-afhankelijke layoutlogica
- duplicatie van modals/paneel/functiebalk CSS

Waarom dit onderhoudbaarder is dan één groot CSS-bestand:
- theme-logica blijft per family lokaal leesbaar
- layout en componentstructuur blijven centraal
- minder kans dat een nieuwe family per ongeluk core layout overschrijft
- eenvoudiger regressietesten per family
- duidelijkere grens tussen “wat is de UI” en “hoe ziet de UI eruit”

Waarom ook niet per theme+mode volledig losse bestanden:
- te veel duplicatie
- onnodig onderhoud van dark/light varianten
- grotere kans op drift tussen light en dark binnen dezelfde family

## 5. Visuele richting per theme
Alle themes behouden exact dezelfde layout en componentstructuur. Alleen styling verschilt.

### `default`
Huidige neutrale baseline.
- rustig
- compact
- functioneel
- donkere modus als primaire baseline
- lichte modus als nette tegenhanger

### `macos-soft`
Doel: zachter, verfijnder, subtiel premium.
- lichtere surfaces
- subtiele separators
- iets zachtere contrasten
- afgeronde panelen/modals iets vriendelijker, maar niet groter
- ingetogen blauw/grijs accent

### `midnight`
Doel: donker, gefocust, licht dramatisch maar nog rustig.
- diepe donkere oppervlakken
- koele blauwe accenten
- duidelijke current row / selected row contrasten
- geschikt voor langdurig gebruik in donkere modus

### `graphite`
Doel: sober, professioneel, bijna monochroom.
- neutraal grijs systeem
- minimale accentkleur
- contrast via value shifts in plaats van kleurigheid
- goed voor gebruikers die een stille UI willen

### `windows11`
Doel: helder, modern, iets luchtiger.
- zachtere paneelsurfaces
- subtiele border+surface lagen
- lichtblauw accent
- iets meer "clean desktop app" gevoel zonder de layout te veranderen

## 6. Settings UI
`Settings > Interface` toont een dropdown/select met alleen de built-in theme families:
- `default`
- `macos-soft`
- `midnight`
- `graphite`
- `windows11`

Dark/light blijft in de hoofdinterface via de bestaande toggle.
Die toggle blijft dus een snelle dagelijkse keuze voor kleurmodus, niet voor theme-family.

Geen extra complexiteit in v1:
- geen preview gallery
- geen screenshot previews
- geen themetekstblokken met uitgebreide beschrijvingen
- geen extra subinstellingen per theme

## 7. Backend-impact
Backend-aanpassing is beperkt:
- whitelist voor `selected_theme` uitbreiden van alleen `default` naar:
  - `default`
  - `macos-soft`
  - `midnight`
  - `graphite`
  - `windows11`
- `selected_color_mode` blijft:
  - `dark`
  - `light`
- settings-opslagmodel blijft verder gelijk
- geen nieuwe dependency
- geen vrije filesystemtoegang

Dit is laag risico omdat alleen validatie van settings-uitbreiding nodig is; de settings-API en SQLite-opslag bestaan al.

## 8. Frontend-impact
Aanbevolen organisatie:
- `base.css` blijft altijd geladen
- alle family-bestanden worden ook geladen, maar zijn strikt gescoped op theme selectors
  - of dynamisch geladen/swapped, als dat later nodig blijkt

Aanbevolen v1-richting: alle theme CSS-bestanden statisch laden, maar strikt scopen.
Reden:
- eenvoudiger startup
- minder runtime asset-wisselcomplexiteit
- minder kans op flash of incomplete styling
- aanvaardbaar zolang het aantal families klein blijft

Selector-richting:
- `:root[data-theme-family="macos-soft"][data-color-mode="dark"] { ... }`
- `:root[data-theme-family="macos-soft"][data-color-mode="light"] { ... }`

Of equivalent met custom properties:
- family-bestanden vullen tokens op basis van family+mode
- `base.css` gebruikt alleen tokens

Aanbevolen toepassing:
- startup leest `selected_theme` en `selected_color_mode`
- zet beide attributen vroeg op `document.documentElement`
- bestaande toggle wijzigt alleen `data-color-mode`
- Interface settings wijzigen alleen `data-theme-family`

Dit houdt startup en theme-switching schoon en voorspelbaar.

## 9. Regressierisico
Belangrijkste risico’s:
- leesbaarheid en contrast per family/mode
- current row / selected row onvoldoende onderscheid
- actieve paneelrand te zwak of te dominant
- modals en functiebalk die in sommige themes te vlak worden
- thumbnail/icon-slot die wegvalt tegen achtergrond
- CSS-fragmentatie als family-bestanden toch layoutregels gaan bevatten
- editor/viewers die visueel uit de toon vallen als tokens niet breed genoeg zijn

Belangrijk mitigatieprincipe:
- theme-bestanden mogen alleen token- en lichte afwerkingsverschillen bevatten
- geen layout overrides per family
- smoke-validatie en handmatige check op alle states:
  - normal row
  - current row
  - selected row
  - current+selected
  - inactive selected
  - modal
  - functiebalk
  - editor/viewers

## 10. Teststrategie
### Backend golden tests
- whitelist accepteert alle built-in themes
- ongeldige theme key blijft geblokkeerd
- `selected_color_mode` gedrag blijft intact
- fallback naar `default` en `dark` blijft correct

### UI smoke/regressietests
- `Settings > Interface` bevat alle built-in theme opties
- startup leest theme + color mode uit backend
- hoofdinterface dark/light toggle blijft bestaan
- data-attributen of equivalent theme-state worden correct toegepast
- modals, functiebalk en panelen blijven renderen onder theme-switches

### Handmatige validatie
Per family in light en dark:
- panel readability
- current row zichtbaarheid
- selected row zichtbaarheid
- inactive pane selectie
- viewer/editor modal contrast
- thumbnail/icon-slot contrast
- functiebalk leesbaarheid
- settings modal tabs en form controls

## 11. Aanbeveling
Aanbevolen v1-richting met laag regressierisico:
- built-in themes alleen als veilige whitelist keys
- families:
  - `default`
  - `macos-soft`
  - `midnight`
  - `graphite`
  - `windows11`
- `lcars` expliciet uitstellen naar een aparte latere theme-slice
- architectuur:
  - gedeelde `base.css`
  - aparte CSS per theme-family
  - dark/light binnen elke family via selectors/tokens

Expliciete beoordeling van de voorgestelde architectuur:
- `gedeelde base.css`
- `aparte CSS per theme-family`

Dit is de juiste richting voor deze app.
Reden:
- houdt layout en theming schoon gescheiden
- voorkomt één onleesbaar gigantisch CSS-bestand
- voorkomt ook duplicatie van complete layoutbestanden per theme+mode
- past goed bij de bestaande settings-architectuur met `selected_theme` + `selected_color_mode`
- blijft onderhoudbaar als later nog 1-3 families bijkomen