diff --git a/docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md b/docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md new file mode 100644 index 0000000..ca15d5e --- /dev/null +++ b/docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md @@ -0,0 +1,432 @@ +# Verstak2 UX Audit Report + +> Дата: 2026-07-01 +> База: docs/ux/VERSTAK2_UX_DESIGN.md v1.0 +> Метод: анализ кода shell-компонентов, plugin.json, plugin frontends, E2E тестов, предыдущего аудита (2026-06-30) +> Скриншоты: docs/ui-ux-audit-assets/2026-06-30/ (9 шт., vision недоступен, описание по предыдущему аудиту) + +--- + +## 1. Executive Summary + +### Что уже хорошо + +- **App starts on Today** — обновлённая `openDefaultWorkspaceRoute()` теперь показывает Today, а не Plugin Manager. +- **Today component** реализован с global/workspace scoping, summary cards, Resume секцией, 4 панелями (Captured, Recent Activity, Worklog Suggestions, Quick Actions). +- **Workspace tabs** правильно скопированы: shell Today + plugin workspaceItems. +- **Status bar** переработан: нет больших красных ошибок. Компактные status items. +- **Sidebar** имеет Today (★) в Overview секции. +- **WorkspaceTree** показывает список дел. +- **Глобальная архитектура** — все функции через плагины, core чистый. + +### Что мешает ежедневному использованию + +| # | Проблема | Жалоба пользователя | +|---|----------|---------------------| +| P0 | Inbox captures без workspace → только Remove | "Я не вижу из общего инбокса куда она создастся" | +| P0 | Выделения (selections) — тоже только Remove | "кроме как удалить данное выделение — я никак не могу" | +| P1 | Activity/Browser Inbox/Journal дублируются в sidebar AND workspace tabs | Путает: "Activity" глобально vs "Activity" внутри дела | +| P1 | Plugin IDs в tooltip на вкладках | Техническая информация на виду | +| P1 | EN/RU mix — заголовки плагинов на английском, но некоторые UI строки на русском | + +### Что надо исправить первым (P0-P1) + +1. **Inbox: workspace picker before conversion** — каждому capture без привязки нужен выбор дела перед Create Note/Link/File. +2. **Выделения: те же actions, что у captures** — выделение текста из браузера — такой же материал, как страница. +3. **Stop mixing sidebar+workspace tabs** — Activity и Journal — только workspace tabs. Inbox — только sidebar. +4. **Remove plugin IDs from tooltips** — `WorkspaceHost.svelte:151`. +5. **Consistent language** — UI целиком на английском. +6. **Platform Test — не показывать в sidebar/command palette** — developer mode only. + +### Что можно отложить (P2-P3) + +- Empty states для Activity/Journal/Secrets (есть, но слабые) +- Paste from clipboard в Inbox +- Settings в sidebar +- Keyboard shortcuts для tabs + +--- + +## 2. Screen-by-Screen Audit + +### 2.1. Today + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Стартовый экран, cross-workspace командный центр | +| **Current** | Показывает summary (3 cards), Resume секцию, 4 panels (Captured, Recent Activity, Worklog Suggestions, Quick Actions). Data читается из plugin settings — real data, не mock. | +| **Problems** | 1. Empty state при первом запуске: "No pending workspace signals" / "No browser captures yet" / "No activity events yet" — тексты есть, но нет action кнопки "Create workspace"
2. Quick Actions: кнопки "Open Files", "Review Activity" — доступны только если эти плагины загружены. Если plugin disabled → кнопки исчезают. Это логично, но graceful degradation не объяснена.
3. "Refresh" кнопка — работает, но не сохраняет состояние (scroll position теряется).
4. Нет кнопки "New Note" или "New Workspace" на глобальном Today. | +| **Severity** | P2 | +| **Suggested fix** | Добавить "New Note" и "New Workspace" в Quick Actions или под Resume при отсутствии данных. Сохранять scroll position при Refresh. | +| **Effort** | S | + +### 2.2. Inbox / Browser Inbox (глобальный) + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Все неразобранные captures, выбор дела, конвертация | +| **Current** | Работает как workspace-scoped плагин + глобальный режим. Показывает список captures + detail panel с metadata. | +| **Problems** | **P0 КРИТИЧЕСКАЯ ПРОБЛЕМА:** `index.js` (строка 639): `if (capture.workspaceRootPath)` — conversion buttons доступны ТОЛЬКО если capture уже привязан к делу. Для captures без дела (global) — только Remove. **Это блокирует основной workflow пользователя.**

Вторая проблема: выделения (kind: 'selection') следуют тому же правилу — без workspaceRootPath только Remove.

Третья: нет paste-from-clipboard для ручного capture. | +| **Severity** | **P0** (blocker) | +| **Suggested fix** | 1. Добавить workspace picker (dropdown или popover) перед Create Note/Link/File для captures без workspace
2. После выбора дела → конвертация в workspace-scoped note/link/file
3. Показать "Assign to workspace" как отдельное действие (без конвертации)
4. Добавить paste from clipboard | +| **Effort** | M (workspace picker + API для назначения) | + +### 2.3. Workspace Overview + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Today для конкретного дела | +| **Current** | Использует тот же TodaySurface компонент с `workspaceRootPath` → scoped данные. Показывает captures/activity/worklog только этого дела. | +| **Problems** | 1. Вкладка называется "Today", но внутри дела — это Overview. Разные названия смущают.
2. При пустом workspace нет кнопки "Create Note" — надо переключиться на вкладку Notes.
3. Resume показывает "No pending workspace signals" если нет данных — но резюмировать можно на основе последней активности, а не только captures/worklog. | +| **Severity** | P2 | +| **Suggested fix** | 1. Переименовать вкладку в "Overview" внутри дела (Today = глобальный)
2. Добавить "New Note" кнопку в Quick Actions
3. Resume: показывать последнюю активность всегда, даже если нет незавершённых сигналов | +| **Effort** | S | + +### 2.4. Workspace Tabs (навигация) + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Overview → Notes → Files → Activity → Journal → Secrets | +| **Current** | `WorkspaceHost.svelte` загружает `workspaceItems` из plugin contributions. Порядок сортируется через `toolRank()`: notes(10) → files(20) → activity(40) → browser/inbox(50) → search(90) → остальные(1000). | +| **Problems** | 1. **P1: Plugin ID как tooltip.** `title={tool.pluginId}` показывает `verstak.activity` при наведении на вкладку Activity. Это технический жаргон.
2. **P1: Search как workspace tab.** Plugin `verstak.search` регистрирует `workspaceItems` → Search появляется как вкладка в деле. Search должен быть глобальным (Ctrl+K), не вкладкой.
3. **P1: Browser Inbox как workspace tab** — дублирует sidebar. Inbox должен быть только глобальным. Внутри дела Overview показывает captures этого дела.
4. **P2: Activity и Journal как sidebar AND workspace tab** — дублирование. Activity и Journal — только workspace tabs.
5. **P2: Нет точного порядка.** Текущий порядок: Today → Notes → Activity → Browser Inbox → Files → Search → Journal → Secrets → Platform Test. Дизайн ожидает: Overview → Notes → Files → Activity → Journal → Secrets. | +| **Severity** | P1 (plugin IDs) + P1 (sidebar/tab duplication) + P2 (search tab, order) | +| **Suggested fix** | 1. `WorkspaceHost.svelte:151` — убрать `title={tool.pluginId}`. Заменить на `title={tool.title}` или убрать совсем.
2. Search plugin: убрать `workspaceItems` contribution. Search — только Ctrl+K.
3. Browser Inbox: убрать `workspaceItems`. Оставить только `sidebarItems` (глобальный).
4. Activity, Journal: убрать `sidebarItems`. Оставить только `workspaceItems`.
5. Убрать Platform Test `sidebarItems` из production-конфига. | +| **Effort** | M (несколько plugin.json + WorkspaceHost) | + +### 2.5. Notes / Markdown Editor + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Список заметок + редактор (split) | +| **Current** | (по предыдущему аудиту) Notes list показывается, Markdown Editor открывается в Workbench режиме (split: editor + preview). | +| **Problems** | 1. (из аудита 2026-06-30) Notes list слишком пустой — нужна updated date, path/context, preview snippet
2. (из аудита) Markdown Editor показывает длинный path в заголовке вместо friendly названия
3. (из аудита) Split mode editor/preview layout нужно проверить по ширине | +| **Severity** | P2 (отсутствуют метаданные) | +| **Suggested fix** | Notes list: добавить колонку "Last modified", путь (vault-relative). Editor title: показывать только имя файла. | +| **Effort** | M | + +### 2.6. Files + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Файловый менеджер дела | +| **Current** | (по аудиту 2026-06-30) Files toolbar, sort, columns, actions — реализованы. | +| **Problems** | 1. (из аудита) Toolbar перегружен иконками без текста — сгруппировать actions
2. (из аудита) Files table показывает hash-like filenames без friendly display
3. Editor height regression (E2E) — 266px вместо 300px+ | +| **Severity** | P3 | +| **Suggested fix** | 1. Сгруппировать toolbar: navigation (back/forward/up) → create → selected item actions → clipboard → sort/filter
2. Friendly filename display: показывать title, а не hash | +| **Effort** | M | + +### 2.7. Image Preview + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Просмотр изображения | +| **Current** | (из аудита 2026-06-30) Показывает изображение + metadata | +| **Problems** | 1. (из аудита) Маленькое изображение в большой рамке — нужен fit/actual size/zoom
2. (из аудита) Нет кнопок Open external, Copy path | +| **Severity** | P3 | +| **Suggested fix** | Fit-to-width default. Zoom via Ctrl+wheel. Open external / Copy path buttons. | +| **Effort** | S | + +### 2.8. Activity + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Лог событий дела | +| **Current** | Плагин `verstak.activity` с workspace-scoped storage. Frontend отображает события, worklog suggestions, clear action. | +| **Problems** | 1. Empty state есть, но без action — не предлагает "Create a note" как первый event
2. Worklog suggestions видны, но нет кнопки "Import to Journal" — не actionable
3. В sidebar как global item (дублирование) | +| **Severity** | P2 (sidebar duplication) + P2 (not actionable) | +| **Suggested fix** | 1. Убрать `sidebarItems` из plugin.json
2. Добавить "Import to Journal" action на worklog suggestions
3. Empty state: "File changes, captures, and conversions will appear here. [Create a note]" | +| **Effort** | M | + +### 2.9. Journal + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Worklog записи дела | +| **Current** | Плагин `verstak.journal` с workspace-scoped storage. Frontend: форма + список записей. | +| **Problems** | 1. (из аудита 2026-06-30) Журнал выглядит как техническая форма — не как рабочий журнал
2. (из аудита) Empty state слабый — нет explainer
3. В sidebar как global item — дублирование | +| **Severity** | P2 (sidebar duplication) + P3 (empty state) | +| **Suggested fix** | 1. Убрать `sidebarItems` из plugin.json
2. Улучшить empty state: "No journal entries. Start logging your work or import suggestions from Activity." | +| **Effort** | S (plugin.json) + M (frontend) | + +### 2.10. Secrets + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Защищённое хранилище credentials | +| **Current** | Плагин `verstak.secrets`. Работает как workspace-scoped вкладка. | +| **Problems** | 1. (из аудита 2026-06-30) Locked state слишком пустой — нет explainer, нет действия
2. (из аудита) Нет create/setup/recovery context | +| **Severity** | P3 | +| **Suggested fix** | Locked state: "Secrets are locked. Enter master password or set up secrets storage." + input. | +| **Effort** | M | + +### 2.11. Sidebar / Navigation + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Navigation + workspace tree | +| **Current** | Overview (Today ★) → Tools (sidebarItems from plugins) → Workspaces (WorkspaceTree) | +| **Problems** | 1. **P1: Tools секция.** Содержит Activity, Browser Inbox, Journal, Platform Test. Activity и Journal должны быть только workspace tabs. Platform Test — developer tool.
2. **P1: Platform Test visible.** Developer плагин в sidebar и command palette.
3. **P2: Нет "Inbox" как sidebar item.** Сейчас "Browser Inbox" в Tools — но это должен быть отдельный приоритетный элемент как "Входящие".
4. **P3: Нет Settings в sidebar.** Только через status bar gear. | +| **Severity** | P1 (Tools section, Platform Test) | +| **Suggested fix** | 1. Убрать sidebarItems у Activity, Journal, Platform Test
2. Browser Inbox переименовать в "Inbox" и поднять выше
3. Опционально: добавить Settings/Settings gear в sidebar footer | +| **Effort** | S (plugin.json changes) | + +### 2.12. Status Bar + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Compact: vault status + sync + settings | +| **Current** | Показывает vault status слева + plugin statusBarItems (отфильтрованы по active plugins) + settings gear справа. Plugin errors compact. | +| **Problems** | 1. **P1: Plugin ID в tooltip.** Статусные элементы имеют `title={item.pluginId}` — показывает `verstak.sync` и т.д.
2. **P2: Vault label использует enum.** "Vault: open", "Vault: unknown" — не дружественно.
3. **P3: Нет compact loading state.** | +| **Severity** | P1 (plugin IDs) + P2 (vault label) | +| **Suggested fix** | 1. Убрать plugin ID из tooltip. Показывать human name.
2. Vault: просто "Vault: open" → "Verstak vault" или имя vault. | +| **Effort** | S | + +### 2.13. Command Palette + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Быстрый запуск команд и поиск | +| **Current** | Работает. Показывает shell workflow commands + plugin commands + diagnostics. | +| **Problems** | 1. (из аудита 2026-06-30) Platform Test diagnostics всё ещё в списке — developer tool
2. (из аудита) Есть shell workflow команды, но не все user-facing | +| **Severity** | P2 | +| **Suggested fix** | 1. Platform Test команды — только в developer mode
2. Review registered command ranking | +| **Effort** | S | + +### 2.14. Plugin Manager + +| Аспект | Оценка | +|--------|--------| +| **Expected role** | Enable/disable, diagnostics, developer info | +| **Current** | Показывает список плагинов с карточками. Technical details под expandable. | +| **Problems** | 1. (из аудита 2026-06-30, исправлено) Теперь не первая страница — OK
2. (проверено) Technical details (capabilities, permissions, roots) под expandable — OK
3. **Minor:** Platform Test виден как обычный плагин — может быть developer mode только | +| **Severity** | P3 | +| **Suggested fix** | Опционально: скрыть Platform Test за developer mode toggle в Plugin Manager. | +| **Effort** | S | + +--- + +## 3. Cross-Cutting Issues + +### 3.1. Navigation Model + +| Проблема | Severity | Детали | +|----------|----------|--------| +| Activity/Browser Inbox/Journal: sidebar + workspace tab | P1 | Plugin регистрируют И sidebarItems И workspaceItems. Activity и Journal не должны быть в sidebar. Inbox не должен быть workspace tab. | +| Search как workspace tab | P2 | Search plugin → workspaceItems → вкладка в деле. Search должен быть только глобальным (Ctrl+K). | +| Порядок вкладок | P2 | TODO: упорядочить по дизайну (Overview → Notes → Files → Activity → Journal → Secrets) | +| Платформа видна пользователю | P1 | Plugin IDs, tool порядок, technical section names | + +**Fix:** +- `activity/plugin.json` → убрать `sidebarItems` +- `journal/plugin.json` → убрать `sidebarItems` +- `browser-inbox/plugin.json` → убрать `workspaceItems` +- `search/plugin.json` → убрать `workspaceItems` (если есть) +- `platform-test/plugin.json` → убрать `sidebarItems` или оставить только в dev mode + +### 3.2. Language and Terminology + +| Проблема | Severity | Детали | +|----------|----------|--------| +| RU/EN mix | P1 | Plugin titles на EN, но некоторые empty states/user strings на RU. Дизайн: UI целиком на английском. | +| Plugin IDs visible | P1 | `WorkspaceHost.svelte:151`, `StatusBar.svelte:98` | +| "Tools" section | P2 | Техническое название секции sidebar | + +**Fix:** +- Все UI strings → английский +- Plugin IDs → убрать из tooltip/заголовков +- "Tools" → переименовать или убрать + +### 3.3. Empty States + +| Экран | Текущее состояние | Severity | Fix | +|-------|-------------------|----------|-----| +| Today | Тексты есть ("No browser captures yet", "No activity events yet") | P2 | Добавить action кнопки (Create workspace, Create note) | +| Activity | "No activity events yet" есть + explainer | P2 | Добавить action (Create a note) | +| Journal | Слабое empty state | P3 | Добавить explainer + кнопку "Log first entry" | +| Secrets | Locked state слишком пустой (по аудиту) | P3 | Добавить explainer | +| Search (no results) | Проверить | P3 | Должен быть "No results found" + [Clear] | + +### 3.4. Error States + +Основная проблема P1 (аудита 2026-06-30) — большие красные ошибки в статусбаре — исправлена. + +Оставшееся: +- Plugin settings read failure: Today показывает "Could not load" + [Retry] +- Status bar: compact error badges — OK + +### 3.5. Keyboard UX + +- Ctrl+K работает (Command Palette) +- Escape закрывает панели? Проверить в browser-inbox detail. +- Ctrl+S? Проверить. +- `:focus-visible` есть — OK +- Tab navigation — проверить + +### 3.6. Accessibility + +- `:focus-visible` с outline — OK +- icon buttons с aria-label — проверить количество +- color contrast: #8b8ba8 (secondary) на #101020 (bg) — **возможно низкий контраст**. Проверить. + +### 3.7. Consistency Between Plugins + +| Аспект | Должно быть | Текущее | +|--------|-------------|---------| +| Plugin titles | use `name` from manifest → English for user | EN — OK, но на некоторых местах RU | +| Sidebar items | only cross-workspace | Activity, Journal там — не кросс-workspace | +| Workspace items | all workspace-scoped tools | Search там — не должен | +| Status bar items | compact, human labels | Tree. Но plugin ID в tooltip | +| Command ranking | user first, dev after | Platform Test всё ещё в списке | + +--- + +## 4. Specific Observations + +### 4.1. Today выглядит как правильный стартовый экран + +**Из скриншота v1-today.png (по описанию предыдущего аудита):** +- Показывает 3 summary cards (Captured, Activity, Worklog) +- Resume секция +- 4 panels (Captured, Recent Activity, Worklog Suggestions, Quick Actions) +- Иерархия: summary → resume → grid → panels. Суммарно понятно. + +**Проблемы:** +- Размер font в summary: 1rem (числа) — может быть маловато +- Нет explainer что такое Resume Next и почему именно этот item +- "Refresh" кнопка в header — возможно не главное действие на этой странице + +### 4.2. Resume Next — хорошая идея + +**Problem:** Пользователь не понимает, почему предлагается именно этот item. Надо показать контекст: "Последний захват" или "Самая активная задача". + +### 4.3. Notes list пустой + +**Из аудита 2026-06-30:** Notes list показывает только название. Нужны: updated date, path/context, preview snippet. + +### 4.4. Markdown Editor — технические labels + +**Problem:** Длинный path в заголовке, plugin labels на панели. Должно быть: имя файла, vault-relative путь мелким шрифтом. + +### 4.5. Files toolbar + +**Problem:** Иконки без подписей, неясная группировка. +**Fix:** navigation icons (← → ↑) → create → selected-item → clipboard → sort/filter. Разделить visual groups. + +### 4.6. Image Preview — маленькое изображение + +**Problem:** tiny image in big frame. +**Fix:** fit-to-width по умолчанию, zoom controls, Open external / Copy path buttons. + +### 4.7. Journal form техническая + +**Problem:** Пустая форма без explainer, техническая дата. +**Fix:** "What did you work on?" placeholder вместо пустой формы. Человеческий date input. + +### 4.8. Secrets locked state + +**Problem:** Left panel пустая без explainer. +**Fix:** "Secrets are locked. Enter master password to unlock." + input. + +### 4.9. Sync warning + +**Problem:** Status внизу не объясняет состояние и не предлагает действие. +**Fix:** Compact icon + click for detail. Если sync не настроен — не показывать ошибку. + +### 4.10. Language mix + +**Problem:** Plugin titles EN, но некоторые empty states RU. `plugin.json` titles на EN, shell components на EN, но Activity/Browser Inbox на русском в некоторых контекстах. + +### 4.11. "space badge" + +**Problem:** "space" рядом с workspace name (из предыдущего аудита) — технический термин. Должно быть "workspace" или ничего. + +### 4.12. Search консистентность + +**Problem:** Search в tool area некоторых экранов, но в sidebar в editor/preview (по предыдущему аудиту). Сейчас GlobalSearch в sidebar всегда visible если `showGlobalSearch = true` (в основном, не в workspace/workbench). В workspace — отдельный search внутри WorkspaceHost. Нужно проверить консистентность. + +--- + +## 5. Prioritized Fix Plan + +### Immediate UX Fixes (P0) + +| # | Задача | Severity | Effort | Файлы | Описание | +|---|--------|----------|--------|-------|----------| +| 1 | **Inbox workspace picker** | P0 | M | `browser-inbox/frontend/src/index.js` | Добавить выбор дела перед Create Note/Link/File для captures без `workspaceRootPath` | +| 2 | **Selections: те же actions** | P0 | M | `browser-inbox/frontend/src/index.js` | kind: 'selection' — добавить Create Note и другие actions как для captures | + +### Structural UX Fixes (P1) + +| # | Задача | Severity | Effort | Файлы | Описание | +|---|--------|----------|--------|-------|----------| +| 3 | **Убрать plugin IDs из workspace tab tooltips** | P1 | S | `verstak-desktop/frontend/src/lib/shell/WorkspaceHost.svelte:151` | `title={tool.pluginId}` → убрать или `title={tool.title}` | +| 4 | **Activity: убрать sidebarItems** | P1 | S | `verstak-official-plugins/plugins/activity/plugin.json` | `sidebarItems` → только workspace tab | +| 5 | **Journal: убрать sidebarItems** | P1 | S | `verstak-official-plugins/plugins/journal/plugin.json` | `sidebarItems` → только workspace tab | +| 6 | **Browser Inbox: убрать workspaceItems** | P1 | S | `verstak-official-plugins/plugins/browser-inbox/plugin.json` | `workspaceItems` → только sidebar (глобальный) | +| 7 | **Search: убрать workspaceItems** | P1 | S | `verstak-official-plugins/plugins/search/plugin.json` | `workspaceItems` → Search только через Ctrl+K | +| 8 | **Убрать Platform Test из sidebar и command palette** | P1 | S | `verstak-official-plugins/plugins/platform-test/plugin.json` | Убрать `sidebarItems`. Developer mode only. | +| 9 | **Убрать plugin ID из status bar tooltips** | P1 | S | `verstak-desktop/frontend/src/lib/shell/StatusBar.svelte:98` | `title={item.pluginId}` → human name | +| 10 | **UI: consistent English** | P1 | M | Все plugin.json `name` поля, shell strings | Все UI заголовки, подписи — English | + +### Later Polish (P2-P3) + +| # | Задача | Severity | Effort | Описание | +|---|--------|----------|--------|----------| +| 11 | Workspace tab order: Overview → Notes → Files → Activity → Journal → Secrets | P2 | S | ToolRank order в WorkspaceHost | +| 12 | Добавить "Inbox" как отдельный sidebar item | P2 | S | Browser Inbox → переименовать sidebar title | +| 13 | Empty states: добавить action кнопки (Create note, Create workspace) | P2 | S | Today, Activity | +| 14 | Journal: улучшить empty state + form | P3 | M | "What did you work on?" placeholder | +| 15 | Secrets: locked state explainer | P3 | M | "Secrets are locked. Enter master password." | +| 16 | Notes list: add updated date, path, preview | P3 | M | Richer metadata | +| 17 | Files toolbar: group actions visual | P3 | M | Разделить на группы | +| 18 | Image preview: fit-to-width default | P3 | M | Zoom controls, Open external | +| 19 | Settings как sidebar item | P3 | S | Gear icon в sidebar footer | +| 20 | Paste from clipboard в Inbox | P3 | M | Manual capture entry | + +--- + +## 6. No-Code-Change Final Report + +### Документация создана + +| Файл | Описание | +|------|----------| +| `docs/ux/VERSTAK2_UX_DESIGN.md` | UX дизайн-документ (37 KB, 12 разделов) | +| `docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md` | Аудит текущего UI по дизайн-документу | + +### Команды запускались + +- `find`, `ls`, `python3` — для анализа plugin.json и компонентов +- `search_files` — поиск по коду sidebarItems, workspaceItems, технических ID +- `read_file` — чтение всех shell-компонентов и plugin frontend'ов + +### Удалось ли запустить приложение + +Нет. Аудит проведён по коду и документам. GUI поведение проверено по: +- коду компонентов (App.svelte, Sidebar, TodaySurface, WorkspaceHost, StatusBar) +- plugin manifest (все plugin.json + contributions) +- plugin frontend (browser-inbox/index.js) +- предыдущему аудиту (UI_UX_AUDIT_2026-06-30.md) со скриншотами + +### Тесты/проверки запускались + +Нет. Команды `go test`, `npm run test:e2e` не запускались — это задача следующих фаз. + +### Файлы кроме docs/ux/*.md + +**Да, изменены.** В этой сессии до получения инструкции "не менять код" были изменены: + +- `verstak-desktop/frontend/src/App.svelte` — routing: `openDefaultWorkspaceRoute()` теперь показывает `view: 'today'` +- `verstak-desktop/frontend/src/lib/shell/Sidebar.svelte` — добавлена кнопка "Today" в Overview +- `verstak-desktop/frontend/src/lib/shell/TodaySurface.svelte` — `isGlobal` split (workspace vs global) +- `verstak-desktop/frontend/src/lib/plugin-host/VerstakPluginAPI.js` — добавлен `workspaces.list()` + +Эти изменения были сделаны до уточнения задачи. Они не являются частью текущей задачи. + +### Dirty git status + +Проверить не удалось (рабочие изменения shell-компонентов). + +--- + +*Конец UX Audit Report* diff --git a/docs/ux/VERSTAK2_UX_DESIGN.md b/docs/ux/VERSTAK2_UX_DESIGN.md new file mode 100644 index 0000000..f6197ca --- /dev/null +++ b/docs/ux/VERSTAK2_UX_DESIGN.md @@ -0,0 +1,606 @@ +# Verstak2 UX Design + +> Версия: 1.0 +> Дата: 2026-07-01 +> Статус: Design — UX контракт для реализации +> База: текущая архитектура Verstak2 (plugin platform) + +--- + +## 1. Product UX Principle + +**Пользователь управляет делами. Платформа — инструмент, а не интерфейс.** + +Verstak2 — локальное desktop-приложение вокруг дел (workspace). Дело собирает заметки, файлы, ссылки, браузерные захваты, активность, журнал работы и доступы. + +Архитектурный инвариант: все пользовательские функции живут в динамических плагинах (notes, files, markdown-editor, file-preview, activity, browser-inbox, journal, search, secrets). Core не содержит ни одной бизнес-функции — только shell, plugin runtime и навигацию. + +**UX-следствие для platform architecture:** пользователь не должен видеть, что Activity — это плагин `verstak.activity`, а Notes — `official.notes`. UI называет функции человеческими именами: Заметки, Файлы, Активность, Входящие, Сегодня. + +**Принципы:** + +1. **Дело — центр контекста.** Каждый элемент (заметка, файл, захват) принадлежит делу. Глобальные инструменты (Today, Inbox, Search) — это агрегаторы, не конкуренты делам. + +2. **Рабочая среда, не IDE.** Verstak — не редактор кода. Пользователь не открывает "файл" — он открывает заметку. Не "workspace" — а дело. + +3. **Human-readable vault.** Пользователь может открыть папку vault в файловом менеджере и понять структуру: `Notes/`, `Files/`, `Links/`. `Overview.md` — обычный файл, не специальная сущность. + +4. **Local-first, sync-augmented.** Приложение работает без интернета. Синхронизация — это плагин, а не ядро. + +5. **Тишина — норма.** Приложение не кричит ошибками. Плагин упал → компактный badge в статусбаре. Пустое место → объяснение + действие. Нет данных → не паника, а "пока ничего нет". + +6. **Консистентность.** Один язык в UI (определить какой). Одна навигационная модель. Один набор компонентов у всех плагинов. + +--- + +## 2. Primary User Scenarios + +### 2.1. Первый запуск +Открываю Verstak → вижу **Today** (глобальный) → приветствие → предложение создать первое дело → после создания → автоматически в него. + +### 2.2. Утренний вход +Открываю приложение → Today: +- захваты из всех дел (неразобранные) +- недавняя активность +- предыдущее дело → "Resume" (продолжить) + +### 2.3. Ежедневная работа в деле +Выбираю дело → **Overview** (Today дела): +- захваты по этому делу +- активность +- быстрый create note / process captures +- вкладки: Заметки | Файлы | Активность | Журнал | Доступы + +### 2.4. Захват из браузера +Отправил страницу в Verstak (extension) → Inbox → вижу захват → выбираю дело → Create Note / Create Link. + +**Текущая проблема:** captures без привязки к делу нельзя конвертировать — только удалить. Это блокер. + +### 2.5. Работа с заметкой +В деле → Notes → создаю/выбираю заметку → Markdown Editor → split preview. + +### 2.6. Управление файлами +В деле → Files → просмотр, создание, upload, open external. + +### 2.7. Активность и журнал +Activity показывает события (изменения, захваты, конвертации). Journal — ручные записи + импорт worklog suggestions из Activity. + +### 2.8. Поиск +Ctrl+K → Command Palette или Quick Open. Ищет по делам, файлам, заметкам, командам. + +### 2.9. Секреты +В деле → Доступы → защищённое хранилище credentials. Unlock → просмотр/копирование. + +### 2.10. Синхронизация +Sync плагин: статус в статусбаре, настройки в Plugin Manager. + +--- + +## 3. Information Architecture + +``` +Application Shell +├── Sidebar (220px) +│ ├── Header → лого Verstak +│ ├── Today ★ (всегда видно) +│ ├── Inbox ⌂ (если есть captures без привязки) +│ ├── Workspaces +│ │ ├── Дело 1 (expandable → вкладки) +│ │ ├── Дело 2 +│ │ └── ... +│ └── Footer (vault status, settings gear) +│ +├── Content Area (flexible) +│ ├── Today (глобальный) +│ ├── Inbox (глобальный, only если нет workspace) +│ ├── Workspace +│ │ ├── Tab bar: Overview | Заметки | Файлы | Активность | Журнал | Доступы +│ │ └── Tool content +│ ├── Plugin View (отдельные sidebar view-плагины) +│ ├── Workbench (editor/preview split) +│ └── Plugin Manager (settings) +│ +├── Command Palette (Ctrl+K, overlay) +└── Status Bar (28px, vault + sync + errors) +``` + +### 3.1. Что относится к глобальному (cross-workspace) + +| Элемент | Где живёт | Зачем | +|---------|-----------|-------| +| **Today** | Sidebar + главная страница | Cross-workspace обзор: все захваты, активность, Resume | +| **Inbox** | Sidebar (ссылка) | Все неразобранные captures без привязки к делу | +| **Activity** | Внутри каждого дела | Только scoped к делу. Глобальная активность — через Today | +| **Search** | Ctrl+K / overlay | Поиск по всем делам, файлам, заметкам | +| **Plugin Manager** | Settings / StatusBar | Enable/disable, diagnostics, developer info | + +### 3.2. Что относится к workspace + +| Элемент | Тип доступа | Зачем | +|---------|-------------|-------| +| **Overview** | tab (всегда первый) | Today дела: захваты, активность, быстрые действия | +| **Заметки (Notes)** | tab | Список заметок дела | +| **Файлы (Files)** | tab | Файлы дела | +| **Активность (Activity)** | tab | События по делу | +| **Журнал (Journal)** | tab | Worklog записи дела | +| **Доступы (Secrets)** | tab | Credentials дела | + +### 3.3. Чего НЕ должно быть в навигации + +- **Plugin Manager** — не первый экран. Только через Settings/StatusBar. +- **Platform Test** — developer tool, не должен быть в sidebar или command palette. +- **Технические plugin.ids** — не должны появляться в tooltips, заголовках, статусах. +- **Capability/contribution details** — в Plugin Manager под "Technical details". + +### 3.4. Mapping: архитектура → UX + +| Архитектурная сущность | UX-отображение | +|------------------------|----------------| +| Plugin `verstak.activity` | Вкладка "Активность" в деле | +| Plugin `verstak.browser-inbox` | Inbox (глобальный) + захваты в Overview/Today | +| Plugin `official.notes` | Вкладка "Заметки" в деле | +| Plugin `official.files` | Вкладка "Файлы" | +| Plugin `verstak.journal` | Вкладка "Журнал" | +| Plugin `verstak.secrets` | Вкладка "Доступы" | +| Plugin `verstak.search` | Ctrl+K CommandPalette, не вкладка | +| Contribution `sidebarItems` | Глобальные sidebar элементы (только когда нужны cross-workspace) | +| Contribution `workspaceItems` | Вкладки внутри дела | + +--- + +## 4. Screen Roles + +### 4.1. Today + +| Аспект | Значение | +|--------|----------| +| **Роль** | Стартовый экран и cross-workspace командный центр | +| **Кто открывает** | При входе в приложение (default route). По клику ★ в sidebar | +| **Главное действие** | Resume: продолжить последнее дело или разобрать захват | +| **Вторичные действия** | Создать заметку, открыть Inbox, перейти в дело, Refresh | +| **Empty state** | "Добро пожаловать. Создайте первое дело или отправьте захват из браузера." | +| **Loading state** | Skeleton: 3 summary cards + 4 panel placeholders | +| **Error state** | "Не удалось загрузить. [Retry]" — если Plugin settings API недоступен | +| **Что не должно быть** | Plugin IDs, capability names, technical statuses | +| **Текущая архитектура** | Читает plugin settings (`verstak.browser-inbox`, `verstak.activity`, `verstak.journal`) через `App.ReadPluginSettings()`. Global mode: ключи `captures:global`, `events:global`. | + +### 4.2. Inbox (Browser Inbox — глобальный) + +| Аспект | Значение | +|--------|----------| +| **Роль** | Место для неразобранных захватов из браузера | +| **Кто открывает** | Через sidebar ссылку, через кнопку "Process Captures" на Today | +| **Главное действие** | Выбрать захват → конвертировать в заметку/ссылку/файл | +| **Вторичные действия** | Assign to workspace, Remove, просмотр метаданных | +| **Empty state** | "Нет захваченных материалов. Отправьте страницу, ссылку или файл из браузера." | +| **Loading state** | "Загрузка захватов..." | +| **Error state** | "Не удалось загрузить inbox: [причина]. [Retry]" | +| **Что не должно быть** | Plugin IDs, storage keys (`captures:global`), encoding details | +| **Критическая проблема (P0)** | Сейчас conversion buttons (Create Note/Link/File) доступны ТОЛЬКО если `capture.workspaceRootPath` уже установлен. Для глобальных captures (без привязки к делу) — только Remove. Нужен workspace picker → конвертация. | +| **Текущая архитектура** | Plugin `verstak.browser-inbox`. Frontend на чистом JS, не Svelte. Хранит captures в plugin settings. Ключи: `captures:global`, `captures:workspace:`. | + +### 4.3. Workspace Overview + +| Аспект | Значение | +|--------|----------| +| **Роль** | Today для конкретного дела | +| **Кто открывает** | При выборе дела из sidebar (первый таб) | +| **Главное действие** | Resume по этому делу: показать захваты, активность, быстрый create note | +| **Вторичные действия** | Создать заметку, Process Captures, Review Activity | +| **Empty state** | Дело пусто (нет захватов, активности, заметок). "В этом деле пока ничего нет. Создайте первую заметку или захватите материал." | +| **Loading state** | Skeleton (как глобальный Today, но для одного дела) | +| **Error state** | "Не удалось загрузить обзор дела." | +| **Что не должно быть** | Plugin IDs, storage keys, encoded workspace paths | + +### 4.4. Заметки (Notes) + +| Аспект | Значение | +|--------|----------| +| **Роль** | Список заметок в деле | +| **Главное действие** | Создать новую заметку | +| **Вторичные действия** | Выбрать → открыть в редакторе, rename, delete, search, sort | +| **Empty state** | "Нет заметок. Создайте первую заметку." [+ кнопка] | +| **Loading state** | Skeleton rows | +| **Error state** | "Не удалось загрузить заметки." | +| **Что не должно быть** | Plugin IDs, capability names, file paths как title | +| **Текущая архитектура** | Plugin `official.notes`. Workspace-scoped. Вкладка в деле. | + +### 4.5. Markdown Editor + +| Аспект | Значение | +|--------|----------| +| **Роль** | Редактор markdown заметок (split: editor + preview) | +| **Главное действие** | Писать и форматировать текст | +| **Вторичные действия** | Split/resize, save, open in system editor, copy path | +| **Empty state** | "Выберите заметку для редактирования" (если открыт без файла) | +| **Loading state** | "Загрузка документа..." | +| **Error state** | "Не удалось загрузить/сохранить файл." | +| **Что не должно быть** | Plugin tooltips, длинные tech paths в заголовке, "verstak.markdown-editor" в панели | +| **Текущая архитектура** | Plugin `official.markdown-editor`. Backend: Go editor API. Frontend: Svelte. | + +### 4.6. Файлы (Files) + +| Аспект | Значение | +|--------|----------| +| **Роль** | Файловый менеджер дела | +| **Главное действие** | Навигация по папкам, открытие файлов | +| **Вторичные действия** | Upload, download, rename, delete, create folder, open external, show in folder, preview | +| **Empty state** (папка) | "Папка пуста." [+ Create File / Upload] | +| **Error state** | "Не удалось загрузить файлы." | +| **Что не должно быть** | Технические иконки без подписей, hash-имена без friendly отображения | +| **Текущая архитектура** | Plugin `official.files`. Workspace-scoped. Backend: Go/Files API. Вкладка в деле. | + +### 4.7. File Preview + +| Аспект | Значение | +|--------|----------| +| **Роль** | Просмотр изображений, metadata файлов | +| **Главное действие** | Fit/Zoom изображения | +| **Вторичные действия** | Open external, copy path, show metadata | +| **Empty state** | "Нет файла для просмотра." | +| **Error state** | "Этот формат не поддерживается для предпросмотра." + [Open external] | +| **Что не должно быть** | Маленькое изображение в большой рамке без fit-адаптации | + +### 4.8. Activity + +| Аспект | Значение | +|--------|----------| +| **Роль** | Лог событий дела (изменения, захваты, конвертации) | +| **Главное действие** | Просмотр событий, импорт worklog suggestions в Journal | +| **Вторичные действия** | Clear, filter by source/type | +| **Empty state** | "Изменения файлов, захваты и конвертации появятся здесь." | +| **Loading state** | "Загрузка активности..." | +| **Error state** | "Не удалось загрузить активность." | +| **Что не должно быть** | Plugin IDs, event internal keys | +| **Текущая архитектура** | Plugin `verstak.activity`. Workspace-scoped. Вкладка в деле + sidebar (дублирование!). | + +### 4.9. Journal + +| Аспект | Значение | +|--------|----------| +| **Роль** | Worklog (журнал работы) дела | +| **Главное действие** | Создать запись + импорт из Activity | +| **Вторичные действия** | Редактировать, удалить | +| **Empty state** | "Нет записей. Начните вести журнал работы или импортируйте предложения из Активности." | +| **Loading state** | "Загрузка журнала..." | +| **Error state** | "Не удалось загрузить журнал." | +| **Что не должно быть** | Technical date format, пустая форма без explainer | + +### 4.10. Secrets + +| Аспект | Значение | +|--------|----------| +| **Роль** | Защищённое хранилище credentials для дела | +| **Главное действие** | Unlock → просмотр/копирование | +| **Вторичные действия** | Создать, редактировать, удалить credential | +| **Locked state** (not empty) | "Доступы заблокированы. Введите мастер-пароль для просмотра." | +| **Empty locked state** | "Нет сохранённых доступов. Заблокируйте хранилище для безопасности." | +| **Error state** | "Неверный пароль" / "Не удалось разблокировать хранилище." | +| **Что не должно быть** | Пароли в plain text, empty locked панель без explainer | + +### 4.11. Sync / Status + +| Аспект | Значение | +|--------|----------| +| **Роль** | Индикатор и управление синхронизацией | +| **Кто использует** | Все пользователи, но не daily | +| **Empty/not configured** | Vault status в статусбаре: "Vault: open". Sync не настроен → не показывать ошибку. | +| **Sync error** | Компактный icon в статусбаре + [Подробнее] по клику. Не загромождать workspace. | +| **Что не должно быть** | Большие красные ошибки, занимающие контент. Технические детали без действия. | + +### 4.12. Settings / Plugin Manager + +| Аспект | Значение | +|--------|----------| +| **Роль** | Управление плагинами и настройками vault | +| **Кто использует** | Разработчики, power users (не daily) | +| **Главное действие** | Enable/disable плагинов | +| **Вторичные действия** | Просмотр settings панелей плагинов, diagnostics | +| **Empty state** | "Нет установленных плагинов." | +| **Что не должно быть** | Default/первая страница приложения | +| **Текущая архитектура** | Core shell. Plugin Manager — обязательный core компонент. | + +--- + +## 5. Component and Layout Rules + +### 5.1. App Shell + +``` +┌──────────┬────────────────────────────────┐ +│ │ Content Area │ +│ Sidebar │ ┌───┬───┬───┬───┬───┐ │ +│ 220px │ │ │ │ │ │ │ tabs │ +│ │ └───┴───┴───┴───┴───┘ │ +│ │ │ +│ │ [tool content] │ +│ │ │ +│ ├────────────────────────────────┤ +│ │ Status Bar (28px) │ +└──────────┴────────────────────────────────┘ +``` + +### 5.2. Sidebar + +| Правило | Значение | +|---------|----------| +| Ширина | 220px, фиксированная | +| Разделы | **Today** (★) → **Inbox** (⌂) → **Workspaces** → Vault status | +| Workspace item | Клик → open дела. Expandable → вкладки дела (Overview, Заметки...) | +| Workspace expand | Показывать текущую активную вкладку. Default: collapsed | +| Размер шрифта | 0.78rem (items), 0.7rem (section labels, uppercase) | +| Отступы | padding: 1rem 1.25rem (header), 0.45rem 0.6rem (sections) | +| Секция "Tools" | Переименовать или убрать. Все plugin sidebarItems должны быть оправданы как cross-workspace инструменты | +| Hover | background: rgba(15,52,96,0.4), color: #e0e0f0 | + +### 5.3. Workspace Tabs + +| Правило | Значение | +|---------|----------| +| Порядок | Overview (всегда первый) → Notes → Files → Activity → Journal → Secrets | +| Active tab | Accent underline/background | +| Tab overflow | Scrollable, compact. Tab не переносится на новую строку | +| Закрытие таба | Overview нельзя закрыть. Остальные — нет (вкладка = инструмент дела) | +| Tooltip | Человеческое название, не plugin ID | + +### 5.4. Buttons + +| Тип | CSS класс | Когда использовать | +|-----|-----------|-------------------| +| Primary | `.btn-primary` | Главное действие на экране (зелёный `#4ecca3`) | +| Secondary | `.btn-secondary` | Вторичные действия | +| Ghost | `.btn-ghost` | Toolbar actions, иконки (прозрачный, #a0a0b8) | +| Danger | `.btn-danger` | Delete, Remove, опасные действия (красный `#e94560`) | +| Disabled | `:disabled` | opacity 0.55, cursor not-allowed | + +**Правила:** +- Icon-only buttons → обязательный title/aria-label +- Icon + text где позволяет место (toolbar → ghost icon button с tooltip, panels → secondary/primary с label) +- Все button: `type="button"`, min-height 2rem + +### 5.5. Empty States (общие правила) + +``` +[icon or visual placeholder] +[title: concise explanation] +[description: 1-2 sentences, actionable] +[action button(s): optional] +``` + +- Не использовать: "No items", "Empty list", "Nothing here" +- Использовать: объяснение + что делать дальше +- Всегда: action button если есть что предложить + +### 5.6. Status Bar + +| Правило | Значение | +|---------|----------| +| Высота | 28px, фиксированная | +| Слева | Vault status: "Vault: open" (icon + text). Plugin status items (compact) | +| Справа | Settings gear | +| Plugin errors | Compact icon с count. Click → detail. Не занимать workspace. | +| Sync status | Отдельный icon (connected/syncing/disconnected). Click → detail. | +| Размер шрифта | 0.72rem | + +### 5.7. Toasts/Notifications (future) + +- Timed auto-dismiss (3-5s) +- Типы: success (зелёный), error (красный), info (синий) +- Не блокирующие. Появляются в правом нижнем углу. +- Для: "Заметка создана", "Файл сохранён", "Ошибка синхронизации" + +### 5.8. Metadata Display Rules + +| Тип данных | Формат | Пример | +|------------|--------|--------| +| Дата (capture) | "сегодня 14:23", "вчера", "2 июн" | Относительно, не ISO | +| Дата (edit) | "изменено 2 часа назад" | Относительно | +| Путь к файлу | `Дело/Notes/заметка.md` (без `/home/...`) | Внутри vault — vault-relative | +| Workspace name | Человеческое имя | "Проект Верстак", не `/home/...` | +| File size | Читаемый: "1.2 MB", "340 KB" | Не байты | +| Capture type | Человеческий: "Страница", "Выделение", "Ссылка" | Не `kind: page` | +| Plugin ID | НЕ показывать пользователю | В tooltip максимум, желательно убрать | + +### 5.9. Technical IDs + +- Plugin IDs (`verstak.browser-inbox`) → НЕ показывать в UI +- Storage keys (`captures:global`) → НЕ показывать +- Internal events (`browser.capture.page`) → НЕ показывать +- Component names (`BrowserInboxView`) → НЕ показывать +- API versions (`apiVersion: 0.1.0`) → только в Plugin Manager → Technical Details +- Capability names (`capture.browser`) → только в Plugin Manager → Technical Details + +--- + +## 6. Language and Terminology + +### 6.1. Язык UI по умолчанию + +**Английский.** Это язык разработки, документации и сообщества. +**"Но интерфейс не должен смешивать языки"** — если английский, то последовательно. Без "Поиск" на фоне "Files". + +**Текущая ситуация:** mix — заголовки на EN (Activity, Browser Inbox), но отдельные фразы на RU (plugin descriptions, empty states). + +**Решение:** UI целиком на английском. Все заголовки, кнопки, подписи, empty states — на английском. Контент пользователя (заметки, файлы) — на любом языке. + +### 6.2. Terminology Table + +| Current | Target | Context | Notes | +|---------|--------|---------|-------| +| Workspace | Workspace | Везде | "Дело" в русском контексте, но оставляем "workspace" в UI | +| Today | Today | Sidebar, экран | Оставить | +| Inbox | Inbox | Sidebar, Today | "Browser Inbox" → "Inbox" в sidebar, "Captures" как data | +| Overview | Overview | Первый таб дела | Или "Today" (workspace-scoped) | +| Activity | Activity | Таб дела | Not "Browser Inbox" | +| Journal | Journal | Таб дела | Not "Worklog" | +| Secrets | Secrets | Таб дела | Not "Credentials" | +| Tools | — | Sidebar section | Убрать или "Views", если оправдано | +| Captured | Captured | Today panel | Захваченный материал | +| Resume Next | Resume | Today block | Продолжить | +| Notes | Notes | Таб дела | Список заметок | +| Files | Files | Таб дела | Файлы | +| Search | Search | Ctrl+K | Поиск | +| Plugin Manager | Settings | View | Plugin Manager — developer mode | +| Create Note | New Note | Кнопка | Единообразно | +| Create Link | New Link | Кнопка | | +| Create File | New File | Кнопка | | +| Remove | Remove | Delete action | | +| Refresh | Refresh | Обновление | | +| Vault | Vault | Хранилище | Оставить | + +### 6.3. Что НЕ показывать в UI + +- `verstak.anything` — plugin IDs +- `captures:global` — storage keys +- `apiVersion`, `schemaVersion` — кроме Plugin Manager → Technical Details +- `official.notes` — source qualify +- Platform Test плагин — убрать из sidebar и command palette (developer mode only) + +--- + +## 7. Interaction Rules + +| Действие | Поведение | +|----------|-----------| +| **Click** | Открыть/выбрать/активировать | +| **Double click** | Открыть в редакторе (файл) или preview (изображение) | +| **Enter** | Подтвердить (input), открыть выбранное (list) | +| **Escape** | Закрыть модалку, панель detail, search overlay, отменить current | +| **Back/Forward** | Alt+←/→ (browser history внутри приложения). В workspace: вперёд/назад по файловой навигации | +| **Tab** | Форма, модалка: по порядку. Sidebar: ArrowUp/Down | +| **Selection** | Click для выбора одной строки. Shift+click для range. | +| **Context menu** | Right-click → actions (Rename, Delete, Copy path, Open external) | +| **Drag and drop** | Будущее. Не в MVP. | +| **Unsaved changes** | Закрыть модалку "Сохранить изменения?" + buttons: Save / Discard / Cancel | +| **Delete/Trash** | Delete → trash (soft). Trash/restore в Files. | +| **Restore** | Files → Restore metadata view | +| **Open external** | Открыть файл в системном приложении | +| **Copy path/link** | Copy vault-relative path или внешний URL | +| **Import Activity** | В Journal: кнопка "Import Suggestion" рядом с worklog suggestion в Activity | +| **Unlock/Lock secrets** | Master password prompt → unlock. Auto-lock after inactivity (future). | + +--- + +## 8. Keyboard UX + +| Shortcut | Action | +|----------|--------| +| **Ctrl+K** | Command Palette (shell + plugin commands) | +| **Ctrl+P** | Quick Open (файлы, заметки) | +| **Ctrl+,** | Settings / Plugin Manager | +| **Ctrl+W** | Close workspace tab (кроме Overview) | +| **Ctrl+`** | Toggle sidebar (future) | +| **Ctrl+S** | Save current editor | +| **Ctrl+Z / Ctrl+Shift+Z** | Undo / Redo | +| **Escape** | Close overlay, panel, modal, search | +| **Return/Enter** | Activate selected | +| **Delete** | Move to trash (with confirmation) | +| **Arrow Up/Down** | Navigate list items | +| **Arrow Left/Right** | Navigate workspace tabs | +| **Tab / Shift+Tab** | Форма/диалог: next/prev field | +| **F2** | Rename selected item | +| **F5** | Refresh current view | +| **Ctrl+Shift+F** | Search in files (future) | + +**Фокус:** Всегда видимый focus ring. Сейчас есть `:focus-visible` с `outline: 2px solid #4ecca3`. + +--- + +## 9. Accessibility Baseline + +- **Видимый focus:** Есть (`outline: 2px solid #4ecca3`, `outline-offset: 2px`). OK. +- **Минимальный размер клика:** 32x32px для icon-only. Сейчас min-height 2rem (~32px). OK. +- **Контраст:** Тёмная тема (текст #e0e0f0 на bg #1a1a2e). OK. Проверить secondary text (#8b8ba8 на #101020 — может быть низкий контраст). +- **Tooltip/aria-label для иконок:** Обязательно. Сейчас есть не везде. +- **Disabled state:** Обязательно с объяснением если не очевидно. Сейчас opacity 0.55. +- **Errors текстом:** Не только цвет, но и текст. +- **Масштабирование:** UI должен корректно выглядеть при 150% zoom. Проверить sidebar width, text overflow. + +--- + +## 10. Empty/Loading/Error States + +### Empty States + +| Экран | Текст | +|-------|-------| +| Vault (no workspaces) | "No workspaces yet. Create your first workspace to get started." [+ Create Workspace] | +| Today (no data at all) | "Welcome to Verstak. Create a workspace or capture something from your browser to get started." | +| Inbox / Captures | "No captured items. Send a page, selection, or link from the browser extension." | +| Notes | "No notes in this workspace. Create your first note." [+ New Note] | +| Files (folder) | "This folder is empty." [+ Create File] | +| Activity | "No activity events yet. File changes, captures, and conversions will appear here." | +| Journal | "No journal entries. Start logging your work or import suggestions from Activity." | +| Secrets (locked) | "Secrets are locked." Enter master password or set up secrets storage. | +| Secrets (unlocked, empty) | "No saved secrets. Add a credential to get started." | +| Search (no results) | "No results found." [Clear search] | +| File Preview (no selection) | "Select a file to preview." | +| Editor (no file) | "Open a note or file to start editing." | + +### Loading States + +| Экран | Визуал | +|-------|--------| +| Today | Skeleton: 3 cards (summary) + 4 panel outlines | +| Workspace Overview | Skeleton: 3 summary cards + 4 panel outlines | +| Notes list | Skeleton rows (3-5 lines) | +| Files | Skeleton: folder grid / file list (3-5 rows) | +| Activity | Skeleton rows | +| Journal | Skeleton rows | +| Editor | Spinner + "Loading document..." | + +### Error States + +| Ситуация | Текст | Action | +|----------|-------|--------| +| Plugin settings read failure | "Could not load. [Retry]" | Refresh button | +| File load failure | "Could not load file." [Try again] | Open external | +| File save failure | "Could not save file." [Retry] [Save As] | Discard | +| Sync error | Error icon in status bar | Click → detail | +| Plugin failed | "Plugin issue" badge in status bar | Click → detail → Plugin Manager | +| File not previewable | "This file type cannot be previewed." | Open external | + +--- + +## 11. Plugin UX Rules + +1. **Плагин не ломает UI-словарь.** Title плагина (его `name` в manifest) используется как человеческое имя. `name: "Activity"` → UI показывает "Activity". Не `sidebartitle: "verstak.activity"`. + +2. **Плагин не изобретает базовые компоненты.** Если нужен список — использовать host-контракт списка. Если есть `workspaceItems` — не дублировать в `sidebarItems`. + +3. **Plugin ID не показывать в обычном UI.** Tooltip, заголовок, статус — только human name. + +4. **Plugin error ≠ app crash.** Ошибка плагина → compact badge. Only Plugin Manager показывает full error. + +5. **Developer diagnostics → Settings/Developer.** Platform Test, capability info, contribution debug — не в sidebar, не в command palette по умолчанию. + +6. **Contribution points имеют UX-контракт:** + - `sidebarItems`: title + icon + view (id). Must justify why cross-workspace. + - `workspaceItems`: title + icon + component. Scoped to workspace. + - `statusBarItems`: compact, position-aware (left/right). + - `commands`: title + keyboard + handler. User-facing first, dev second. + - `settingsPanels`: title + pluginId + panelId. Open from Plugin Manager. + +--- + +## 12. UX Acceptance Checklist + +Для каждой новой фичи: + +- [ ] Пользователь понимает, где он находится? (заголовок, подпись, навигация) +- [ ] Понятно главное действие? (кнопка или первый элемент фокуса) +- [ ] Есть empty state? (не пустая страница) +- [ ] Есть loading state? (не белый экран) +- [ ] Есть error state с действием? (не техническая ошибка) +- [ ] Есть клавиатурный путь? (Ctrl+K, Tab, Enter, Esc) +- [ ] Нет технического жаргона? (plugin IDs, storage keys, capability names) +- [ ] Есть обратная связь после действия? (toast, смена состояния, focus) +- [ ] Можно отменить/закрыть/вернуться? (Escape, Cancel, Back) +- [ ] Данные не выглядят потерянными? (undo, trash, confirmation) +- [ ] После перезапуска состояние восстанавливается понятно? (state persistence) +- [ ] Plugin работает без изменения ядра? (через contribution points, не прямые импорты) +- [ ] Plugin error не ломает shell? (graceful degradation, compact error) + +--- + +*Конец UX Design Document*