verstak-docs/docs/UI_UX_AUDIT_2026-06-30.md

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.