kite/.planning/milestones/v0.2-ROADMAP.md

Milestone v0.2: UI Overhaul and Optimization

Status: ✅ SHIPPED 2026-06-17 Phases: 8–11 Total Plans: 33

Overview

v0.2 transformed DocuVault from a feature-complete but rough alpha into a polished, production-quality web application. The milestone covered four areas: codebase quality (decomposing monolith routers, eliminating duplication, purging dead code), admin panel rearchitecture (standalone route subtree with deep-linkable views), UX & interaction (empty states, skeletons, keyboard shortcuts, OS drag-drop, toast notifications), and visual design with responsive layout (mobile sidebar, consistent spacing, form styling, bundle optimization).

Phases

Phase 8: Stack Upgrade & Backend Decomposition

Goal: The dependency stack is current, all three backend router monoliths are split into focused sub-packages with zero URL or behavior changes, and the frontend API client is decomposed into domain modules behind a re-export barrel — the entire change is invisible to consumers and tests. Depends on: Phase 7.4 (last v0.1 phase) Requirements: PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08 Plans: 8 plans (3 waves)

Wave 0 — Foundation (parallel)

• 08-01-PLAN.md — CR-01/02/03 test stubs (3 xfail stubs in test_auth.py) + Wave 0 scaffolds for regression detection
• 08-02-PLAN.md — api/schemas.py creation + CloudConnectionOut migration from admin.py (MUST precede admin split)

Wave 1 — Phase 7.1 completion (frontend only)

• 08-03-PLAN.md — useToastStore stub + CR test promotion + SettingsAccountTab.vue + TotpEnrollment.vue inline toast replacement

Wave 2 — Backend decomposition + frontend (parallel)

• 08-04-PLAN.md — Split api/admin.py → api/admin/ package (CODE-01)
• 08-05-PLAN.md — Split api/documents.py → api/documents/ package (CODE-02)
• 08-06-PLAN.md — Split api/auth.py → api/auth/ package (CODE-03)
• 08-07-PLAN.md — Frontend client.js decomposition: utils.js + 7 domain modules + barrel rewrite (CODE-04)
• 08-08-PLAN.md — PERF-01 dependency bump + tailwind/vite config wiring + requirements.txt exact pinning

Completed: 2026-06-12

---

Phase 9: Admin Panel Rearchitecture

Goal: The admin interface is a standalone route subtree (/admin/*) with its own layout component and sidebar; each admin section is deep-linkable and browser-back-button works; the requiresAdmin navigation guard correctly protects all child routes; and the Tailwind safelist is configured so dynamic color classes render correctly in production builds. Depends on: Phase 8 Requirements: ADMIN-08, ADMIN-09, ADMIN-10, ADMIN-11, ADMIN-12, CODE-06, CODE-09 Plans: 5 plans (4 waves)

Wave 1 — Foundation (parallel)

• 09-01-PLAN.md — Backend overview.py endpoint + 8 ADMIN-11 tests
• 09-02-PLAN.md — Frontend AdminLayout + AdminSidebar + AdminOverviewView + getAdminOverview API client

Wave 2

• 09-03-PLAN.md — Extract 4 admin tab components to standalone views

Wave 3

• 09-04-PLAN.md — Router rearchitecture (nested /admin + to.matched.some guard) + Tailwind safelist + delete AdminView.vue

Wave 4

• 09-05-PLAN.md — CODE-09 comment purge + human checkpoint UAT

Completed: 2026-06-13

---

Phase 10: UX & Interaction

Goal: The application communicates state clearly at every moment — empty contexts have purposeful empty states, loading transitions show structured skeletons, power users can operate keyboard-first, files can be dragged from the OS directly onto the browser, and every action produces an immediate toast confirmation. Depends on: Phase 9 Requirements: UX-01 through UX-14, CODE-05 Plans: 13 plans (6 waves)

Wave 0 — Foundation components + xfail test stubs (parallel)

• 10-01-PLAN.md — AppIcon.vue + tests (CODE-05 foundation)
• 10-02-PLAN.md — EmptyState.vue + tests (UX-01 foundation)
• 10-03-PLAN.md — BreadcrumbBar.vue + tests (UX-12 foundation)
• 10-04-PLAN.md — Toast store + ToastContainer.vue + App.vue mount + tests (UX-10 foundation)
• 10-05-PLAN.md — Wave 0 xfail test stubs for UX-02..09, UX-11, UX-13, UX-14

Wave 1 — Wire EmptyState, skeletons, BreadcrumbBar (parallel)

• 10-06-PLAN.md — StorageBrowser + FileManagerView + CloudFolderView wiring
• 10-07-PLAN.md — AppSidebar wiring (skeleton, EmptyState, UX-14 removal)
• 10-08-PLAN.md — Admin views + Settings + SharedView + CloudStorageView

Wave 2 — Keyboard shortcuts

• 10-09-PLAN.md — Global keydown in App.vue + ref chain through FileManagerView/StorageBrowser

Wave 3 — OS drag overlay

• 10-10-PLAN.md — OsDragOverlay.vue + App.vue mount + FileManagerView.handleOsDrop

Wave 4 — Drag-to-move + dropdown clipping fixes

• 10-11-PLAN.md — Click-after-drag guard + Teleport-based folder picker + FolderRow three-dot menu

Wave 5 — SVG centralization

• 10-12-PLAN.md — Replace all inline <svg> blocks with <AppIcon name="..." />

UAT Gap Closure

• 10-13-PLAN.md — 6 UAT gaps closed: sidebar shimmer, search-at-root, admin sidebar isolation, keyboard dispatch fix, Escape modifier, OS drop capture phase

Completed: 2026-06-16

---

Phase 11: Visual Design, Responsive Layout & Cleanup

Goal: Every component uses the Tailwind spacing scale and typography system consistently, form elements have cross-browser baseline styling, interactive elements have consistent hover/focus states, the layout adapts cleanly to mobile viewports with a hamburger-toggled sidebar drawer, dead code is deleted, and bundle size is measured before and after. Depends on: Phase 10 Requirements: VISUAL-01 through VISUAL-04, RESP-01 through RESP-05, CODE-07, PERF-02, PERF-03 Plans: 7 plans (5 waves + 1 UAT gap closure)

• 11-01-PLAN.md — Bundle baseline + Vite analyzer wiring + lazy-load admin routes (PERF-02, PERF-03)
• 11-02-PLAN.md — Tailwind forms plugin + form element baseline styling (VISUAL-02)
• 11-03-PLAN.md — Responsive shells and storage rows (RESP-01, RESP-02)
• 11-04-PLAN.md — Mobile-safe modals and form baseline verification (RESP-04, RESP-05)
• 11-05-PLAN.md — Visual consistency pass — typography, focus-visible, hover/active states (VISUAL-01, VISUAL-03, VISUAL-04, RESP-03)
• 11-06-PLAN.md — Dead-code sweep + bundle final measurement (CODE-07, PERF-02 post-opt)
• 11-07-PLAN.md — Mobile storage toolbar compact icon controls (RESP-02, RESP-03 gap closure)

Completed: 2026-06-17

---

Milestone Summary

Key Decisions:

• Options API preserved in v0.2 refactor — Composition API migration is scope-creep for a UX milestone
• Admin panel as standalone route subtree — AdminView.vue as tabs-on-user-layout is architecturally wrong
• client.js barrel re-export pattern — zero consumer churn; all 35+ import sites stay unchanged
• Sub-routers carry NO prefix — parent include_router propagates prefix; sub-router with prefix causes double-segment URLs
• FastAPI 0.128+ empty-path restriction — @router.get("") on sub-router with empty include prefix raises FastAPIError
• to.matched.some() for requiresAdmin guard — Vue Router 4 does not inherit meta to children; direct to.meta check is a security regression
• Vite 6→8 upgrade — resolved moderate CVEs (CVE-2026-39363/39364); npm audit clean
• AdminLayout as route component, not App.vue branch — router resolves AdminLayout as /admin component; its router-view renders children
• Tailwind safelist with regex patterns — dynamic color classes (sky=OneDrive, amber=admin audit badges) are tree-shaken without safelist

Issues Resolved:

• Admin panel auth guard was checking to.meta.requiresAdmin directly (Vue Router 4 doesn't inherit meta to children) — fixed to to.matched.some()
• Three-dot dropdown menus clipped by scroll containers — fixed with Teleport + getBoundingClientRect positioning
• Admin views loaded synchronously — all lazy-loaded, reducing initial bundle by 81 kB (−30.6%)
• Inline SVG duplicated path data in 66 instances — centralized in AppIcon.vue
• Mobile toolbar overflow below 550px — compact icon controls added in 11-07

Issues Deferred:

• Virtual scrolling — quota cap (100 MB/user) limits lists to hundreds of items; v-for sufficient
• Dark mode — coherent color token system must exist first
• Folder reordering by drag — requires persistent position column in DB
• Composition API migration — separate milestone

Technical Debt Incurred:

• Options API retained throughout — intentional deferral; next milestone may begin Composition API migration

---

For current project status, see .planning/ROADMAP.md