webmanager-mvp/project_docs/UI_THEME_V1_DESIGN.md

# UI Theme v1 Design

## 1. Doel

Doel van deze stap is de huidige webui visueel moderner, rustiger en prettiger te maken zonder de dual-pane file manager workflow te verzwakken.

De huidige UI heeft al een functionele structuur:
- compacte topbar
- twee dominante browsepanelen
- compacte functiebalk
- modals voor view/edit/rename-move

De visuele refresh moet daarom niet proberen de informatiearchitectuur opnieuw uit te vinden, maar moet vooral:
- duidelijkere visuele hiërarchie geven
- betere contrastverhoudingen bieden
- light en dark mode ondersteunen
- selectie/current-row/actieve paneelstatus leesbaarder maken
- de interface consistenter laten aanvoelen

De dual-pane bestandslijst blijft het hoofdonderdeel van het scherm. Decoratie is ondergeschikt aan bruikbaarheid.

## 2. Themastructuur

Aanbevolen richting: CSS custom properties met één gedeeld tokenmodel, aangestuurd via een `data-theme` attribuut op `html` of `body`.

### Basistokens

Aanbevolen tokenset:
- `--color-page-bg`
- `--color-surface`
- `--color-surface-elevated`
- `--color-border`
- `--color-border-strong`
- `--color-text-primary`
- `--color-text-muted`
- `--color-accent`
- `--color-accent-contrast`
- `--color-selection-bg`
- `--color-selection-border`
- `--color-current-row-bg`
- `--color-current-row-border`
- `--color-active-pane-border`
- `--color-button-bg`
- `--color-button-hover`
- `--color-button-secondary-bg`
- `--color-danger`
- `--color-danger-bg`
- `--color-overlay-bg`
- `--shadow-elevated`
- `--radius-sm`
- `--radius-md`

### Dark mode voorstel

Dark mode moet geen pure zwarte UI zijn, maar een rustige donkergrijze werkruimte.

Voorstel:
- page background: donker koel grijs-blauw
- panel surface: iets lichter dan page background
- elevated surface: nog een stap lichter voor modals/topbar/footer
- borders: lage contrastgrijze lijnen
- text primary: bijna wit maar niet hard wit
- text muted: gedempt blauwgrijs
- selected row: duidelijke, maar niet schreeuwerige accentvulling
- current row: subtiele focuslaag bovenop de lijst
- active pane border: heldere accentkleur
- primary buttons: rustige accentkleur
- secondary buttons: neutrale dark surface
- danger state: warm rood met goede contrasttekst
- overlay/modal background: transparant donker vlak

### Light mode voorstel

Light mode moet frisser en moderner zijn dan de huidige variant, zonder fel of vlak te worden.

Voorstel:
- page background: zacht koel lichtgrijs
- panel surface: wit of bijna wit
- elevated surface: iets warmere/luxere lichte toon voor topbar/footer/modals
- borders: verfijnde grijsblauwe lijn
- text primary: diep donkerblauwgrijs
- text muted: medium koel grijs
- selected row: zachte accenttint
- current row: subtiele focusrand en lichte achtergrond
- active pane border: sterke accentkleur
- primary buttons: accentkleur met heldere tekst
- secondary buttons: rustige lichte surface
- danger state: donker rood met zachte foutachtergrond
- overlay/modal background: transparant donkergrijs

## 3. UI-onderdelen die moeten meedoen

### Topbar
- achtergrond uit `surface-elevated`
- statusregel leesbaarder maken
- theme toggle rechts in dezelfde balk
- titel en status optisch beter uitlijnen

### Dual-pane panels
- panel surface en border via tokens
- active pane alleen via rand/focus, niet via zware achtergrondwisseling
- subtiele elevation of contrastlaag mogelijk, maar beperkt

### Bestandslijsten
- lijst blijft visueel dominant
- grid header moet in beide thema’s voldoende contrast houden
- directory-links mogen accent gebruiken, maar niet te fel

### Current row / selected row
- current row en selected row moeten visueel onderscheidbaar blijven
- combinatie current + selected moet in beide thema’s bruikbaar blijven
- contrast moet ook werken bij lange sessies en veel selectie

### Functiebalk onderaan
- dezelfde visuele taal als topbar/modals
- compacte maar duidelijke knopstates
- disabled buttons goed zichtbaar als niet-beschikbaar, zonder onleesbaar te worden

### Modals
- view/edit/rename-move/wildcard/batch move moeten dezelfde elevated surface gebruiken
- overlay donker genoeg om focus te geven
- popup-card iets zachtere rounding en subtiele shadow

### Meldingen / feedback
- statusregel, fouten in panelen en actiefeedback moeten in beide thema’s leesbaar zijn
- error-kleur moet duidelijk zijn zonder hard neon-effect

### Breadcrumbs
- breadcrumbs en klikbare delen moeten goed zichtbaar blijven in beide thema’s
- hover/focus states moeten subtiel maar duidelijk zijn

## 4. Light/dark mode gedrag

### Toggle gedrag
- kleine theme toggle knop met zonnetje/maantje
- positie: in de bovenste balk, rechts van de status/actie tekst
- dus visueel: `titel | statusbericht | theme toggle`

### Interactie
- knop toggelt tussen light en dark
- icoon reflecteert de actie of huidige mode, maar moet consequent gekozen worden

Aanbevolen keuze:
- toon huidige mode als icoon
- dark mode: maantje zichtbaar
- light mode: zonnetje zichtbaar

### Opslag
- keuze opslaan in `localStorage`
- sleutel bijvoorbeeld: `webmanager-theme`

### Default
Aanbevolen default:
- als `localStorage` nog leeg is: volg `prefers-color-scheme`
- fallback daarna naar `dark`

Motivatie:
- voelt moderner en meer app-achtig
- sluit goed aan op een dual-pane file manager werkruimte
- blijft respectvol naar systeeminstellingen

## 5. Visuele principes

### Compacter en rustiger
- minder visuele ruis in de topbar en functiebalk
- consistenter gebruik van spacing
- minder harde contrastwisselingen tussen onderdelen

### Duidelijke hiërarchie
- bestandslijsten zijn primair
- topbar en footer zijn ondersteunend
- modals zijn duidelijk elevated maar niet zwaar gedecoreerd

### Geen zware effecten
- geen sterke gradients
- geen glows of drukke schaduwen
- alleen subtiele shadows waar elevation functioneel is

### Functionele rounding
- lichte rounding op panelen, buttons en modals
- niet overdreven rond; doel is rust en moderniteit, niet speelsheid

### Lijst dominant
- meeste visuele aandacht blijft bij de twee paneellijsten
- kleuren en effecten moeten de lijst leesbaarder maken, niet concurreren met de inhoud

## 6. Regressiebehoud

Stylingwijzigingen mogen niet breken:
- selectiegedrag
- checkbox-hit areas
- current row zichtbaarheid
- keyboard navigation focusgevoel
- active pane herkenning
- popup interactie
- dual-pane layout

Concreet:
- geen layoutwijziging waardoor paneelhoogte of interne scroll verslechtert
- geen topbar-uitbreiding die verticale ruimte van de lijst substantieel opslokt
- geen functiebalk-styling die de onderbalk hoger of drukker maakt dan nodig

## 7. Impactanalyse

Waarschijnlijk te wijzigen frontendbestanden:
- `webui/html/style.css`
- `webui/html/index.html`
- `webui/html/app.js`

Waarom:
- `style.css`: nieuw tokenmodel en themaspecifieke styles
- `index.html`: plaatsing van de theme toggle in de topbar
- `app.js`: thema initialiseren, togglen en opslaan in `localStorage`

Geen backendimpact verwacht.

### Regressierisico

Laag tot middel:
- laag voor backend en API, want geen backendwijzigingen
- middel voor frontend omdat de topbar en globale CSS geraakt worden
- grootste risico zit in contrast, selected/current row zichtbaarheid en behoud van compacte verticale ruimte

## 8. Teststrategie

### UI smoke tests aanpassen

Minimaal toevoegen/controleren:
- theme toggle knop aanwezig in topbar
- status-element blijft aanwezig
- topbar bevat zowel status als toggle
- relevante modalcontainers blijven aanwezig
- statische assets blijven werken

### Handmatige validatie

Nodig voor:
- light mode leesbaarheid van bestandslijsten
- dark mode leesbaarheid van bestandslijsten
- selected row en current row in beide thema’s
- active pane border in beide thema’s
- breadcrumbs hover/focus states
- modals in beide thema’s
- localStorage-persistentie na refresh
- default gedrag bij lege localStorage en system preference

## Aanbevolen implementatierichting

Aanbevolen v1-richting:
- implementeer een klein, stabiel tokenmodel in `style.css`
- gebruik `data-theme="light|dark"` op `document.documentElement`
- voeg een compacte theme toggle toe in de topbar rechts van `#status`
- laat `app.js` de initiële theme bepalen via `localStorage` -> `prefers-color-scheme` -> fallback
- houd layout en spacing grotendeels gelijk, en focus de refresh op kleur, contrast, borders, surfaces en modals

Dit geeft de hoogste UX-winst met het laagste regressierisico.