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