From 2ac7dd52ec6e0774c1bde76e0f4bc802b3c2e9a2 Mon Sep 17 00:00:00 2001 From: mirivlad Date: Wed, 1 Jul 2026 07:44:17 +0800 Subject: [PATCH] Revert "docs: UX design document + UX audit report" This reverts commit bf9a769997eed0a97a7d249b934b7015f7948329. --- docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md | 432 ------------------- docs/ux/VERSTAK2_UX_DESIGN.md | 606 --------------------------- 2 files changed, 1038 deletions(-) delete mode 100644 docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md delete mode 100644 docs/ux/VERSTAK2_UX_DESIGN.md diff --git a/docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md b/docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md deleted file mode 100644 index ca15d5e..0000000 --- a/docs/ux/VERSTAK2_UX_AUDIT_CURRENT.md +++ /dev/null @@ -1,432 +0,0 @@ -# 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 deleted file mode 100644 index f6197ca..0000000 --- a/docs/ux/VERSTAK2_UX_DESIGN.md +++ /dev/null @@ -1,606 +0,0 @@ -# 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*