# 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)
- [x] 08-01-PLAN.md — CR-01/02/03 test stubs (3 xfail stubs in test_auth.py) + Wave 0 scaffolds for regression detection
- [x] 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)
- [x] 08-03-PLAN.md — `useToastStore` stub + CR test promotion + SettingsAccountTab.vue + TotpEnrollment.vue inline toast replacement

**Wave 2** — Backend decomposition + frontend (parallel)
- [x] 08-04-PLAN.md — Split `api/admin.py` → `api/admin/` package (CODE-01)
- [x] 08-05-PLAN.md — Split `api/documents.py` → `api/documents/` package (CODE-02)
- [x] 08-06-PLAN.md — Split `api/auth.py` → `api/auth/` package (CODE-03)
- [x] 08-07-PLAN.md — Frontend `client.js` decomposition: utils.js + 7 domain modules + barrel rewrite (CODE-04)
- [x] 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)
- [x] 09-01-PLAN.md — Backend overview.py endpoint + 8 ADMIN-11 tests
- [x] 09-02-PLAN.md — Frontend AdminLayout + AdminSidebar + AdminOverviewView + getAdminOverview API client

**Wave 2**
- [x] 09-03-PLAN.md — Extract 4 admin tab components to standalone views

**Wave 3**
- [x] 09-04-PLAN.md — Router rearchitecture (nested /admin + to.matched.some guard) + Tailwind safelist + delete AdminView.vue

**Wave 4**
- [x] 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)
- [x] 10-01-PLAN.md — AppIcon.vue + tests (CODE-05 foundation)
- [x] 10-02-PLAN.md — EmptyState.vue + tests (UX-01 foundation)
- [x] 10-03-PLAN.md — BreadcrumbBar.vue + tests (UX-12 foundation)
- [x] 10-04-PLAN.md — Toast store + ToastContainer.vue + App.vue mount + tests (UX-10 foundation)
- [x] 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)
- [x] 10-06-PLAN.md — StorageBrowser + FileManagerView + CloudFolderView wiring
- [x] 10-07-PLAN.md — AppSidebar wiring (skeleton, EmptyState, UX-14 removal)
- [x] 10-08-PLAN.md — Admin views + Settings + SharedView + CloudStorageView

**Wave 2** — Keyboard shortcuts
- [x] 10-09-PLAN.md — Global keydown in App.vue + ref chain through FileManagerView/StorageBrowser

**Wave 3** — OS drag overlay
- [x] 10-10-PLAN.md — OsDragOverlay.vue + App.vue mount + FileManagerView.handleOsDrop

**Wave 4** — Drag-to-move + dropdown clipping fixes
- [x] 10-11-PLAN.md — Click-after-drag guard + Teleport-based folder picker + FolderRow three-dot menu

**Wave 5** — SVG centralization
- [x] 10-12-PLAN.md — Replace all inline `<svg>` blocks with `<AppIcon name="..." />`

**UAT Gap Closure**
- [x] 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)

- [x] 11-01-PLAN.md — Bundle baseline + Vite analyzer wiring + lazy-load admin routes (PERF-02, PERF-03)
- [x] 11-02-PLAN.md — Tailwind forms plugin + form element baseline styling (VISUAL-02)
- [x] 11-03-PLAN.md — Responsive shells and storage rows (RESP-01, RESP-02)
- [x] 11-04-PLAN.md — Mobile-safe modals and form baseline verification (RESP-04, RESP-05)
- [x] 11-05-PLAN.md — Visual consistency pass — typography, focus-visible, hover/active states (VISUAL-01, VISUAL-03, VISUAL-04, RESP-03)
- [x] 11-06-PLAN.md — Dead-code sweep + bundle final measurement (CODE-07, PERF-02 post-opt)
- [x] 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*