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.