diff --git a/docs/UI_UX_AUDIT_2026-06-30.md b/docs/UI_UX_AUDIT_2026-06-30.md new file mode 100644 index 0000000..e036135 --- /dev/null +++ b/docs/UI_UX_AUDIT_2026-06-30.md @@ -0,0 +1,494 @@ +# Verstak2 UI/UX Audit - 2026-06-30 + +## Scope + +This audit compares current Verstak2 against the old Verstak repository at +`/home/mirivlad/git/verstak`. The old repository is used only as UI/UX, +feature, and workflow reference. Code and architecture are not copied. + +No previous complete UI/UX comparison report was found in the Verstak2 +repositories. Existing documents cover implementation plans and roadmap items, +but not an end-to-end scenario audit. + +## Environment + +- Date: 2026-06-30 +- Verstak2 desktop repo: `/home/mirivlad/git/verstak2/verstak-desktop` +- Old Verstak repo: `/home/mirivlad/git/verstak` +- Tooling: + - Node.js v24.18.0 installed locally under `/tmp/verstak2-tools` + - Playwright Chromium used through local CLI wrapper + - Wails CLI v2.12.0 installed locally + - Debian 13 WebKitGTK package present as `libwebkit2gtk-4.1-dev` +- Wails note: + - `wails doctor` still reports missing `libwebkit2gtk-4.0-dev`. + - Wails v2.12.0 supports WebKitGTK 4.1 with Go build tag `webkit2_41`. + - `go test -tags webkit2_41 ./...` passes for current `verstak-desktop`. + +## Artifacts + +Screenshots are stored in: + +`docs/ui-ux-audit-assets/2026-06-30/` + +- `v1-start.png` +- `v1-today.png` +- `v1-inbox.png` +- `v1-activity.png` +- `v2-plugin-manager.png` +- `v2-workspace-files.png` +- `v2-command-palette.png` +- `v2-workspace-activity.png` +- `v2-workspace-browser-inbox.png` + +## Verification Summary + +### Repository Update + +All Verstak2 subrepositories were updated. `verstak-desktop` initially could +not fast-forward because of local tracked changes in generated Wails typings +and `scripts/build.sh`. Those changes were saved in: + +`stash@{0}: codex-pre-ui-audit-desktop-update` + +After that, `verstak-desktop` fast-forwarded to `origin/main`. + +### Automated Checks + +Current `verstak-desktop`: + +- `go test -tags webkit2_41 ./...`: pass +- `npm --prefix frontend run build`: pass +- `frontend npm run test:e2e`: 42 passed, 11 failed +- `scripts/check.sh` with `GOFLAGS=-tags=webkit2_41`: fails on gofmt only: + - `plugins/platform-test/backend/main.go` + - `build/bin/plugins/platform-test/backend/main.go` + +### E2E Failures Worth Tracking + +The failed E2E tests cluster around: + +- Plugin Manager navigation selectors expecting `.sidebar .nav-item` while the + current sidebar uses different structure/classes. +- File/workbench editor height regressions: + - text editor height was about 266px where test expects over 300px; + - markdown preview height was about 217px where test expects over 300px. +- Platform Test status bar component failure: + - `openDiagnostics` component not found in bundle. +- Sync status bar failure: + - `SyncStatusBar` bundle content is empty. + +Some selector failures may be stale test assumptions. The editor height and +status bar errors are visible workflow/UI issues. + +### Post-Pull Status - 2026-06-30 Later Sync + +After pulling `verstak-desktop` to `46f754c` (`feat: workspace routing, +GlobalSearch, and shell refinements`), several roadmap items from this audit +are now implemented and verified. + +Current verification: + +- `GOFLAGS=-tags=webkit2_41 go test ./...`: pass +- `npm --prefix frontend run test:e2e`: 71 passed +- Focused UX coverage now includes: + - app starts in the first workspace instead of Plugin Manager; + - workspace opens with a shell-level Today tab before plugin tools; + - workspace selection and main content stay in sync after Plugin Manager + round trips; + - workspace tool selection survives Workbench open/back/close flows; + - status bar plugin failures do not render large error panels; + - Plugin Manager remains reachable from the status/settings menu; + - Files uses readable dates and understandable labeled controls; + - Vault Selection is localized and has clear primary actions; + - global search stays visible after opening tool views; + - global search searches workspaces and file contents with RU/EN layout + fallback; + - plugin settings modal has enough space for complex panels; + - Browser Inbox desktop workflow renders an empty capture flow, stored + captures, detail metadata, and create/remove actions; + - Activity desktop workflow renders an empty event flow, stored events, and + worklog suggestions; + - Command Palette promotes shell workflow commands before diagnostics and can + open Today, Files, Activity, Browser Inbox, Plugin Manager, and start + markdown/text file creation; + - Command Palette can run Sync Now and open Sync settings. + +The historical screenshots in `docs/ui-ux-audit-assets/2026-06-30/` remain +useful as "before" evidence, but the active roadmap below supersedes the +original P0 ordering. + +## Scenario Findings + +### 1. First Meaningful Screen + +Old Verstak opens into a working shell: + +- left navigation has clear system sections: Today, Inbox, Activity; +- workspace tree sits in the same navigation context; +- global search is immediately visible in the header; +- sync status and settings are discoverable but secondary. + +Verstak2 opens into Plugin Manager: + +- the first screen is technical/admin-oriented rather than user-task-oriented; +- plugin cards expose implementation details such as capabilities, roots, + permissions, API versions, and contribution counts; +- status bar plugin errors are visible immediately; +- workspace entry exists in the sidebar, but it is not the primary landing + experience. + +Verdict: Verstak2 is feature-visible, but not user-workflow-first. + +### 2. Navigation Model + +Old Verstak has one coherent navigation model: + +- System section for cross-workspace workflows; +- Workspace section for user cases/spaces; +- settings and sync anchored at the bottom; +- current page title and search are consistent. + +Verstak2 separates: + +- Tools; +- Workspaces; +- workspace tabs; +- Plugin Manager; +- status bar settings. + +This is architecturally accurate for a platform, but it leaks platform concepts +too strongly into daily use. The user needs "work", "capture", "search", +"activity", and "settings"; they should not need to reason about plugin +contributions on the main path. + +### 3. Workspace Files + +Verstak2 workspace Files is one of the stronger current screens: + +- workspace header exists; +- search slot exists; +- Files, Activity, Browser Inbox tabs are correctly scoped to workspace; +- file rows, folder rows, filtering, sorting, and action buttons are present. + +Problems: + +- Files toolbar buttons render visually as near-identical small squares in the + screenshot. Accessibility names exist, but visible affordance is poor. +- Editor/preview area appears too short in E2E, causing regressions for file + opening workflows. +- Status bar error area consumes a large part of the lower viewport and reduces + usable file space. + +### 4. Activity + +Old Verstak gives Activity a clear system-level place and empty state. +Today also exposes related workflow tabs: feed, suggestions, in-progress, +captures, browser. + +Original Verstak2 desktop mock rendered only: + +- heading `Activity`; +- text `Global activity feed`. + +Current desktop shell/mock now mirrors the official Activity plugin's core +visible workflow: scoped empty state, event count, stored event rows, clear +action, and worklog suggestions. Remaining work is to expose real activity +ingestion and Journal import from the visible app flow, not just prove the +surface contract in mock E2E. + +### 5. Browser Inbox / Capture Flow + +Old Verstak "Неразобранное" has: + +- a clear name for unprocessed captures; +- explanatory text; +- an immediate visible action: paste from clipboard. + +Original Verstak2 desktop mock rendered only: + +- heading `Browser Inbox`; +- text `Global browser inbox`. + +Current desktop shell/mock now mirrors the official Browser Inbox plugin's core +visible workflow: scoped empty state, capture count, stored capture rows, +detail metadata, and visible conversion/remove actions. Remaining work is to +make the real capture ingestion path and extension pairing visible from the +app. + +### 6. Command Palette + +Verstak2 command palette opens and is keyboard-accessible. Current visible +commands are only Platform Test commands. It is useful infrastructure, but not +yet a meaningful user launcher. + +Expected near-term commands: + +- open/create workspace; +- search workspace; +- create note; +- create file; +- open Browser Inbox; +- open Activity; +- sync now / sync settings; +- plugin/settings only after user tasks. + +### 7. Status Bar + +Status bar is currently the largest immediate UX blocker. + +Observed: + +- permanent lower panel shows plugin errors; +- error cards overlap/consume workspace area; +- messages expose internal plugin/component/bundle details; +- normal user status is visually dominated by red plugin failure content. + +The old version keeps sync/settings status quiet and secondary. Verstak2 should +follow that principle: status should be compact, actionable, and non-blocking. +Developer diagnostics belong behind an explicit diagnostics surface. + +## Priority Plan + +### DONE - Remove User-Facing Internal Errors From Main Workspace + +Goal: no normal user screen should be dominated by plugin bundle errors. + +Status: implemented in `verstak-desktop` and verified by +`frontend/e2e/ux-p0.spec.js` plus `frontend/e2e/status-bar.spec.js`. + +Actions: + +- Fix Platform Test status contribution: + - manifest/component mismatch around `openDiagnostics` vs available bundle + components. +- Fix Sync status contribution: + - empty frontend bundle content for `SyncStatusBar`. +- Change status bar error rendering: + - compact "Plugin issue" badge; + - details only on click; + - cap height so it cannot cover workspace content. + +Verification: + +- `frontend/e2e/status-bar.spec.js` passes. +- First workspace screenshot has no large red error cards. + +### DONE - Make Workspace The Default User Landing + +Goal: after vault opens, user lands in a productive workspace or Today-style +overview, not Plugin Manager. + +Status: implemented in `verstak-desktop`; current mock flow starts in the first +workspace and keeps Plugin Manager reachable through settings. + +Actions: + +- If a vault has workspaces, open the last active workspace. +- If no workspace exists, show a first-run workspace creation screen. +- Move Plugin Manager out of the primary default route: + - keep accessible through Settings; + - optionally expose via command palette. + +Verification: + +- Initial app screen shows workspace or useful overview. +- Plugin Manager remains reachable but is not the first user-facing surface. + +### PARTIAL - Restore Old "Today / Inbox / Activity" Workflow Shape + +Goal: preserve the old product's user workflow while keeping Verstak2 plugin +architecture. + +Status: first shell-level Today surface is implemented in `verstak-desktop`. +Workspace now opens with `Today` before plugin tools, showing captures, recent +activity, worklog suggestions, and quick actions. The Today "Open Inbox" action +switches into the workspace Browser Inbox tool, and Files remains stable after +Workbench open/back/close flows. + +Remaining gap: this is still a thin aggregation layer. Activity, Browser Inbox, +and Journal exist as plugin-backed surfaces, but the old product's richer +"what should I do now?" flow needs real capture/activity/journal data density +and stronger empty-state actions. Current architecture has the ingredients: + +- `verstak.activity` stores scoped activity and exposes worklog suggestion + command `verstak.activity.suggestWorklog`; +- `verstak.browser-inbox` stores scoped captures and can convert captures into + notes, links, and files; +- `verstak.journal` stores worklog entries and can import Activity suggestions; +- `GlobalSearch` indexes workspaces, tools, files, Browser Inbox, Activity, and + Journal plugin settings. + +Actions: + +- Expand the user-level `Today` surface with richer real data. +- Surface and prioritize: + - recent activity; + - unprocessed captures; + - in-progress work; + - worklog suggestions; + - quick create actions. +- Keep implementation plugin-driven, but present as one coherent workflow. +- Add first-class commands for opening Today, Inbox, Activity, and creating + work items. + +Verification: + +- User can answer "what should I do now?" from the first screen. +- Browser captures and activity are visible without opening Plugin Manager. +- `frontend/e2e/ux-today.spec.js` covers Today-first startup and the Today to + Browser Inbox quick-action path. + +### PARTIAL - Make Activity A Real Visible Workflow + +Goal: Activity should look useful even with no events and should connect events +to worklog reconstruction. + +Status: partially implemented. The real Activity plugin has scoped storage, +event subscriptions, worklog suggestion generation, and a command contribution +for `verstak.activity.suggestWorklog`. The desktop E2E/mock surface now mirrors +the core visible workflow: scoped empty state, event count, stored event rows, +clear action, and worklog suggestions. + +Remaining UX work is mostly around real activity ingestion from app actions, +Journal import/review, and making suggestions actionable from Today/Activity +rather than merely visible. + +Actions: + +- Keep empty-state copy explaining that file changes, browser captures, and + conversions will appear here. +- Add visible actions for: + - import worklog suggestion to Journal; + - filter by source/type; + - open related file/capture from an activity row. +- Connect Today worklog suggestions to Activity/Journal actions. + +Verification: + +- Empty Activity explains what will appear. +- Stored events render with source/type/summary. +- Worklog suggestions are visible from activity events. +- `frontend/e2e/activity.spec.js` covers the desktop shell/mock contract. + +### PARTIAL - Make Browser Inbox A Real Visible Workflow + +Goal: Browser Inbox should look usable even when empty. + +Status: partially implemented. The real Browser Inbox plugin has storage, +event subscriptions, scoped capture lists, domain binding, and Create Note / +Create Link / Create File actions for selected captures. The desktop E2E/mock +surface now mirrors the core visible workflow: scoped empty state, capture +count, stored capture list, detail metadata, and Create Note / Create Link / +Create File / Remove actions. Today also opens this workspace tool directly. + +Remaining UX work is mostly around actual primary capture actions, extension +pairing/settings visibility, and making the real capture ingestion path easy to +exercise from the app. + +Actions: + +- Keep empty-state copy explaining capture flow. +- Add primary actions: + - paste from clipboard; + - open browser extension pairing/settings; + - create note/link/file from selected capture when data exists. +- Show domain/workspace binding state if configured. + +Verification: + +- Empty Browser Inbox explains the capture flow. +- Stored captures render with visible metadata and conversion actions. +- Captures can be converted from the visible UI in the real plugin. +- `frontend/e2e/browser-inbox.spec.js` covers the desktop shell/mock contract. + +### DONE - Fix Files Toolbar Visual Affordance + +Goal: toolbar buttons must be visually recognizable, not identical dark boxes. + +Status: implemented and verified by `frontend/e2e/ux-p0.spec.js` and the full +Files E2E suite. Files now uses readable dates and understandable action +controls; editor/preview height regressions are covered by passing E2E. + +Actions: + +- Ensure Lucide icons render with sufficient contrast and size. +- Add tooltips for icon-only buttons. +- Disable unavailable actions visibly instead of showing identical active + squares. +- Keep layout dense, but make grouping clear: navigation, create, selected item + actions, clipboard, filter/sort. + +Verification: + +- Screenshot shows recognizable icons. +- Buttons have accessible names and hover tooltips. +- File open editor/preview height returns above E2E threshold. + +### PARTIAL - Make Command Palette User-Oriented + +Goal: command palette should be a power-user entry point for real tasks. + +Status: partial. Command Palette works, executes active plugin commands, and +now promotes shell workflow commands above diagnostics: Open Today, Open Files, +Open Activity, Open Browser Inbox, Open Plugin Manager, Create Markdown File, +Create Text File, Sync Now, and Open Sync Settings. Remaining command coverage +gaps are capture actions, richer note templates, Journal import/review, and +hiding test diagnostics from production-like mode. + +Actions: + +- Register remaining user commands from Browser Inbox, Activity, Search, and + Journal. +- Keep user commands ranked above diagnostics/test commands. +- Hide test/plugin diagnostics from production-like mode. + +Verification: + +- `Ctrl+K` shows open Today/Files/Activity/Inbox commands before diagnostics. +- `Ctrl+K` can start markdown/text file creation through the visible Files + workflow. +- `Ctrl+K` can run Sync Now and open Sync settings. +- `frontend/e2e/command-palette.spec.js` covers shell command ranking and the + Open Activity, create-file, and sync command paths. + +### DONE - Reduce Plugin Manager Density + +Goal: Plugin Manager should remain useful but stop looking like the product's +main screen. + +Status: implemented enough for the current roadmap. Plugin cards now show a +short default surface and hide API version, root, capabilities, optional +requires, and permissions under `Technical details`. + +Actions: + +- Split default view into simple plugin list: + - name; + - enabled/disabled; + - short description; + - settings; + - disable/enable. +- Put capabilities, permissions, roots, and contribution details behind + expandable "Developer details". + +Verification: + +- Plugin Manager fits more plugins per viewport. +- Non-developer user can safely enable/disable/configure without reading + internal contracts. + +## Next Review Steps + +1. Design and implement the user-level Home/Today surface. +2. Re-run: + - `GOFLAGS=-tags=webkit2_41 ./scripts/check.sh` + - `npm --prefix frontend run test:e2e` +3. Re-capture the same screenshots as "after" evidence. +4. Run real Wails GUI smoke with: + - `wails dev -tags webkit2_41` +5. Do a second audit focused on: + - first-run/open vault; + - real filesystem vault; + - Browser extension capture; + - native window/WebKitGTK rendering differences. diff --git a/docs/ui-ux-audit-assets/2026-06-30/v1-activity.png b/docs/ui-ux-audit-assets/2026-06-30/v1-activity.png new file mode 100644 index 0000000..253897d Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v1-activity.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v1-inbox.png b/docs/ui-ux-audit-assets/2026-06-30/v1-inbox.png new file mode 100644 index 0000000..b1258f0 Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v1-inbox.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v1-start.png b/docs/ui-ux-audit-assets/2026-06-30/v1-start.png new file mode 100644 index 0000000..45ac827 Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v1-start.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v1-today.png b/docs/ui-ux-audit-assets/2026-06-30/v1-today.png new file mode 100644 index 0000000..ef1e9b9 Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v1-today.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v2-command-palette.png b/docs/ui-ux-audit-assets/2026-06-30/v2-command-palette.png new file mode 100644 index 0000000..6447650 Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v2-command-palette.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v2-plugin-manager.png b/docs/ui-ux-audit-assets/2026-06-30/v2-plugin-manager.png new file mode 100644 index 0000000..5662066 Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v2-plugin-manager.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-activity.png b/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-activity.png new file mode 100644 index 0000000..b7b8a97 Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-activity.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-browser-inbox.png b/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-browser-inbox.png new file mode 100644 index 0000000..bf515b9 Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-browser-inbox.png differ diff --git a/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-files.png b/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-files.png new file mode 100644 index 0000000..ad3b9dc Binary files /dev/null and b/docs/ui-ux-audit-assets/2026-06-30/v2-workspace-files.png differ