webmanager-mvp/project_docs/BUILTIN_THEMES_V1_1_DESIGN.md

# Built-in Themes v1.1

## 1. Theme families voor v1
Aanbevolen built-in theme families voor v1.1:
- `default`
- `macos-soft`
- `midnight`
- `graphite`
- `windows11`

Deze set is klein genoeg om beheersbaar te blijven en groot genoeg om visueel zinvolle keuze te bieden zonder een theme-explosie te veroorzaken.

## 2. LCARS
`lcars` hoort expliciet niet in v1.1.

Aanbevolen behandeling:
- niet opnemen in deze slice
- later als aparte v2 onderzoeken

Reden:
- `lcars` is visueel extreem uitgesproken
- hoger risico op regressie in leesbaarheid, functiebalkgebruik, row states, modals en paneelcontrast
- grotere kans dat componentstructuur visueel gaat knellen tegen de huidige dual-pane workflow

Conclusie:
- `lcars` beter behandelen als aparte latere theme-slice met eigen UX-validatie

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

Beide blijven persistent opgeslagen in SQLite settings.

Voorbeelden van effectieve combinaties:
- `default-dark`
- `default-light`
- `macos-soft-dark`
- `macos-soft-light`
- `midnight-dark`
- `graphite-light`
- `windows11-dark`

Belangrijk:
- theme family en color mode blijven twee gescheiden concepten
- de hoofdinterface-toggle blijft alleen `selected_color_mode` wisselen
- `Settings > Interface` blijft alleen `selected_theme` beheren

## 4. CSS-architectuur
Voorkeursrichting voor v1.1:
- één gedeelde `base.css` voor:
  - layout
  - spacing
  - componentstructuur
  - modals
  - panelen
  - functiebalk
  - lijst/tabelstructuur
  - 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 geregeld via selectors of tokens

Dus expliciet niet:
- één enorm all-in-one CSS-bestand met alles door elkaar
- per `theme+mode` een volledig apart layoutbestand

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

Binnen elk theme-family bestand:
- alleen tokens en beperkte theme-afwerking
- geen duplicatie van layoutregels
- geen alternatieve componentstructuur

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

Of equivalent via custom properties.

## 5. Waarom deze architectuur onderhoudbaarder is
Deze architectuur is onderhoudbaarder omdat hij drie dingen schoon van elkaar scheidt:
- wat de UI is: layout en componentstructuur in `base.css`
- welke stijl-family actief is: family-bestand
- welke kleurmodus actief is: dark/light tokens binnen die family

Voordelen:
- layout-CSS staat op één plek
- theme-bestanden blijven klein en thematisch leesbaar
- regressies zijn makkelijker te isoleren per family
- nieuwe family toevoegen vereist minder risico op breken van bestaande layout
- dark/light binnen één family blijft samenhangend beheerd

Hoe duplicatie van layout-CSS voorkomen wordt:
- `base.css` bevat alle structurele regels
- family-bestanden overschrijven alleen tokens en kleine visuele accenten
- geen herhaling van paneelgrid, modal layout, functiebalkstructuur of lijstlayout per family

Hoe theme switching schoon blijft:
- frontend hoeft alleen `selected_theme` en `selected_color_mode` te lezen
- die waarden vertalen naar theme-attributen op `document.documentElement`
- CSS doet de rest via selectors/custom properties
- geen runtime CSS-generatie nodig
- geen vrije bestandsselectie
- geen ingewikkelde asset-resolutie

## 6. Visuele richting per theme
Alle themes behouden exact dezelfde layout en informatiearchitectuur. Alleen visuele stijl verschilt.

### `default`
Doel:
- neutrale baseline
- functioneel
- rustig
- compact

Karakter:
- de huidige standaardstijl, iets verfijnd maar niet uitgesproken

### `macos-soft`
Doel:
- zacht
- verfijnd
- vriendelijk

Karakter:
- subtiele surfaces
- zachte grijstinten
- lichte premium desktop-app indruk
- iets vriendelijkere rounding/shadows, zonder layout te veranderen

### `midnight`
Doel:
- donker
- gefocust
- rustig

Karakter:
- diepere donkere panelen
- koele accenten
- sterke maar nette current/selected contrasten
- geschikt voor langdurig gebruik in dark mode

### `graphite`
Doel:
- sober
- professioneel
- bijna monochroom

Karakter:
- grijs-gedreven palette
- minimale accentkleur
- contrast via luminantie in plaats van felle tinten

### `windows11`
Doel:
- helder
- modern
- clean desktop-app gevoel

Karakter:
- lichtere surfaces
- subtiele border/surface scheiding
- iets luchtiger accentgebruik
- behoud van compacte file-manager ergonomie

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

Dark/light blijft via de bestaande toggle in de hoofdinterface.

Dus:
- Interface tab = keuze van style family
- Main interface toggle = keuze van color mode

Geen extra theme-complexiteit in v1.1:
- geen preview gallery
- geen import/export
- geen vrije CSS-keuze
- geen uploads

## 8. Backend-impact
Backend-aanpassing blijft klein:
- whitelist van `selected_theme` uitbreiden met:
  - `default`
  - `macos-soft`
  - `midnight`
  - `graphite`
  - `windows11`
- `selected_color_mode` blijft bestaan zoals nu
- geen vrije css-bestandskeuze
- geen uploadmechanisme
- geen nieuwe dependencies

De bestaande settings-opslag en settings-API kunnen verder hetzelfde model blijven gebruiken.

## 9. Regressierisico
Belangrijkste risico’s:
- leesbaarheid per theme/mode
- current row / selected row contrast te zwak of te hard
- modals die in bepaalde families te vlak worden
- functiebalk die visueel wegvalt
- editor/viewers die niet goed mee themen
- thumbnail/icon-slot met te weinig contrast
- CSS-fragmentatie als family-bestanden toch structurele regels gaan bevatten
- duplicatie als layout-regels alsnog in family-bestanden belanden

Belangrijk mitigatieprincipe:
- family-bestanden beperken tot visuele tokens en kleine afwerkingsregels
- geen layout-overrides per family
- consistent regressietesten van dezelfde states in alle families

## 10. Aanbeveling
Aanbevolen richting voor deze app:
- ja, `base.css` + aparte CSS per theme-family is de juiste richting

Waarom:
- laag regressierisico
- duidelijke scheiding tussen structuur en uiterlijk
- onderhoudbaar bij toekomstige uitbreiding
- sluit aan op het bestaande model van `selected_theme` + `selected_color_mode`
- voorkomt zowel een gigantisch all-in-one stylesheet als onnodige duplicatie per `theme+mode`

Expliciete aanbevelingen:
- gebruik gedeelde basis-CSS voor layout/componentstructuur
- gebruik aparte CSS per theme-family
- regel dark/light binnen dezelfde family via selectors/tokens
- behandel `lcars` expliciet als aparte latere slice

Conclusie:
- deze architectuur is de juiste basis voor built-in themes in deze app
- `lcars` moet niet worden meegetrokken in v1.1, maar apart worden ontworpen en gevalideerd