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