feat (ui) CSS

project_docs/UI_THEME_V1_DESIGN.md

@@ -0,0 +1,256 @@
+# 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.